Guide d’intégration PMS pour les bornes Roommatik

Objectif : Ce document décrit l’API RESTful qu’un Property Management System (PMS) doit implémenter pour que les bornes de self-check-in Roommatik puissent communiquer avec lui. La borne agit en tant que client — votre PMS est le serveur.

Voir la collection Postman

Importez cette collection pour tester directement les endpoints de l’API.

1. Vue d’ensemble

L’intégration entre un PMS et une borne de check-in Roommatik repose sur une série de requêtes/réponses HTTP qui fournissent les informations nécessaires à la borne pour effectuer les opérations liées aux clients :

Synchronisation de la date et de l’heure du système
Recherche de réservation par code de réservation ou nom de famille du client
Enregistrement des clients à partir de documents d’identité numérisés
Enregistrement des paiements (carte, espèces ou autres méthodes)
Opérations de check-in et check-out
Disponibilité des chambres et tarifs pour les clients sans réservation
Produits d’upselling et surclassements de chambres

Nous recommandons fortement d’implémenter une API RESTful JSON. D’autres standards (SOAP, XML-RPC) et la communication par fichiers sont également pris en charge — contactez-nous pour plus de détails.

2. Authentification

Toutes les requêtes incluent un en-tête API-Key pour l’authentification :

GET /v2/basic/DateTime HTTP/1.1
Host: your-pms-server.com
API-Key: your-api-key-here

3. Format de réponse standard

Chaque endpoint doit retourner une réponse JSON avec la structure suivante :

{
    "returnCode": 0,
    "description": "Success",
    "result": { ... },
    "pmsMessage": null,
    "userMessage": null
}

Champ	Type	Description
`returnCode`	int	`0` = succès, valeurs négatives = erreur
`description`	string	Description lisible du statut
`result`	object / array / bool / null	Contenu de la réponse (varie selon l’endpoint)
`pmsMessage`	string \| null	Message interne optionnel pour la journalisation
`userMessage`	string \| null	Message optionnel à afficher au client

4. Format de date

Toutes les dates utilisent le format yyyyMMddTHHmm. Exemple : 20200414T1217 représente le 14 avril 2020 à 12h17.

Les champs contenant uniquement une date utilisent le format yyyyMMdd. Exemple : 19420618 représente le 18 juin 1942.

5. Modèles de données

5.1 Objet Guest

Champ	Type	Description
`guestId`	string	Identifiant du client dans le PMS (null pour les nouveaux clients)
`loyaltyId`	string \| null	Identifiant du programme de fidélité
`firstName`	string	Prénom
`lastName1`	string	Nom de famille
`lastName2`	string \| null	Deuxième nom de famille (le cas échéant)
`nationality`	string	Code pays ISO 3166-1 alpha-3
`birthdate`	string	Date de naissance (`yyyyMMdd`)
`gender`	string	`"M"` ou `"F"`
`idTypeName`	string	Type de document : `C` (permis de conduire), `X` (titre de séjour UE), `D` (pièce d’identité), `I` (numéro d’identification), `P` (passeport), `N` (titre de séjour espagnol)
`idNumber`	string	Numéro du document
`idIssueDate`	string	Date de délivrance du document (`yyyyMMdd`)
`idExpirationDate`	string	Date d’expiration du document (`yyyyMMdd`)
`landline`	string	Numéro de téléphone fixe
`mobile`	string	Numéro de téléphone mobile
`email`	string	Adresse e-mail
`street`	string	Adresse postale
`city`	string	Ville
`stateOrProvince`	string	État ou province
`country`	string	Code pays (ISO 3166-1 alpha-3)
`zipCode`	string	Code postal
`precheckin`	boolean	Indique si le client a effectué le pré-check-in en ligne

Champs réglementaires espagnols

Les champs suivants sont obligatoires pour les hôtels opérant en Espagne, conformément à la réglementation du Registre des Voyageurs.

Champ	Type	Description
`documentSupportNumber`	string	Code alphanumérique unique figurant sur le DNI espagnol physique
`relationShip`	string	Lien légal/familial entre le client principal et les mineurs accompagnants (ex. : `"HJ"` pour fils/fille)
`c_pro_ine`	string	Code INE de la province (ex. : `"28"` pour Madrid, `"08"` pour Barcelone)
`c_mun_ine`	string	Code INE de la municipalité (numéro à 3 chiffres unique au sein de la province)

5.2 Objet Room Type

Champ	Type	Description
`roomTypeId`	int / string	Identifiant du type de chambre
`roomTypeName`	string	Nom du type de chambre (ex. : “Twin room”)
`maxOccupancy`	int	Nombre maximum de clients
`description`	string	Description du type de chambre

5.3 Objet Room

Champ	Type	Description
`roomId`	string	Identifiant de la chambre
`roomName`	string	Nom/numéro de la chambre (ex. : “101”)
`status`	string	Statut de la chambre (ex. : “Confirmed”, “CheckIn”)
`isAvailable`	boolean	Indique si la chambre est disponible pour le check-in
`roomType`	object	Objet Room Type (voir ci-dessus)
`guest`	array	Tableau d’objets Guest assignés à cette chambre

5.4 Objet Reservation Component

Champ	Type	Description
`arrivalDateTime`	string	Date/heure d’arrivée
`departureDateTime`	string	Date/heure de départ (utilisée pour l’expiration de la carte-clé)
`numberOfAdults`	int	Nombre de clients adultes
`numberOfChildren`	int	Nombre d’enfants
`notes_remarks`	string	Demandes spéciales ou remarques
`price`	decimal	Prix de la chambre
`deposit`	decimal	Montant déjà versé en acompte
`taxPrice`	decimal	Montant des taxes
`extrasPrice`	decimal	Montant des suppléments
`currency`	string	Code de la devise (ex. : “EUR”)
`boardTypeId`	int / string	Identifiant du type de pension
`boardTypeName`	string	Nom du type de pension (ex. : “AD”)
`collectiveType`	string	Code du type de collectif
`room`	object	Objet Room (voir ci-dessus)

5.5 Types de paiement

Type	Champs
cardPayment	`amount`, `currency`, `dateTime`, `accountNumber`, `securityCode`, `cardType` (Mastercard, VISA, etc.)
cashPayment	`amount`, `currency`, `dateTime`
genericPayment	`paymentType` (ex. : “Bizum”), `amount`, `currency`, `dateTime`, `transactionId`

6. Module de base (Obligatoire)

Le module basic est le seul module qui doit être implémenté. Il couvre le flux principal de check-in : recherche de réservation, enregistrement des clients, enregistrement des paiements et exécution du check-in.

6.1 DateTime

Récupère la date et l’heure actuelles du PMS. Utilisé pour la synchronisation horaire et la vérification de disponibilité (vérifier que le PMS est opérationnel).

Méthode	`GET`
URL	`/v2/basic/DateTime`
Paramètres	Aucun

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "pmsDateTime": "20200414T1217"
    },
    "pmsMessage": null,
    "userMessage": null
}

6.2 BookingFormId

Récupère le numéro de formulaire d’enregistrement généré par le PMS pour une combinaison réservation-client spécifique. Ce numéro sera imprimé sur le PDF du formulaire d’enregistrement généré par la borne.

Méthode	`GET`
URL	`/v2/basic/BookingFormId`

Paramètres de requête :

Paramètre	Type	Description
`reservationId`	string	Identifiant de la réservation
`guestId`	string	Identifiant du client

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "bookingFormId": "A/2022/123675"
    },
    "pmsMessage": null,
    "userMessage": null
}

6.3 Reservation

Valide une référence de réservation et récupère l’ensemble des données de la réservation. Prend en charge la recherche par code de réservation ou par nom de famille du client + date de départ.

Méthode	`GET`
URL	`/v2/basic/Reservation`

Paramètres de requête (option A — par code de réservation) :

Paramètre	Type	Description
`bookingCode`	string	Référence de réservation du client

Paramètres de requête (option B — par nom de famille) :

Paramètre	Type	Description
`lastName`	string	Nom de famille du client
`departure`	string	Date de départ (`yyyyMMdd`)

Remarques importantes :

S’il n’existe pas de réservation valide pour le code de réservation fourni, retournez une réservation vide dans le résultat.
Pour les réservations multi-chambres, la borne permet le check-in partiel. Si le même code de réservation est interrogé à nouveau, définissez isAvailable: false pour les chambres déjà enregistrées afin d’éviter les doublons.
Si la valeur du deposit est égale ou supérieure au prix total, la borne ne demandera pas de paiement supplémentaire.

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "reservationId": "1234",
        "totalPrice": 102.14,
        "currency": "EUR",
        "partialPaymentsAllowed": true,
        "reservationHolder": {
            "reservationHolderId": "ESB34567891",
            "name": "ACME SL",
            "lastName1": null,
            "lastName2": null,
            "isACompany": true
        },
        "reservationComponent": [
            {
                "arrivalDateTime": "20200108T1600",
                "departureDateTime": "20200109T1200",
                "numberOfAdults": 1,
                "numberOfChildren": 0,
                "notes_remarks": "guest requested a room in the lower floors",
                "price": 100,
                "deposit": 100,
                "taxPrice": 2.09,
                "extrasPrice": 100.05,
                "currency": "EUR",
                "boardTypeId": "1",
                "boardTypeName": "AD",
                "collectiveType": "001",
                "room": {
                    "roomId": "5436",
                    "roomName": "101",
                    "isAvailable": true,
                    "status": "Confirmed",
                    "roomType": {
                        "roomTypeId": "1",
                        "roomTypeName": "Twin room",
                        "maxOccupancy": 3,
                        "description": "Sea sight non-smoker"
                    },
                    "guest": [
                        {
                            "guestId": "58796",
                            "firstName": "Paul",
                            "lastName1": "McCartney",
                            "nationality": "UK",
                            "birthdate": "19420618",
                            "gender": "M",
                            "idTypeName": "D",
                            "idNumber": "53487956B",
                            "email": "[email protected]",
                            "precheckin": true
                        }
                    ]
                }
            }
        ]
    },
    "pmsMessage": null,
    "userMessage": null
}

6.4 NewGuest

Enregistre un nouveau client ou met à jour un client existant dans le PMS avec les données d’identification capturées par la borne (généralement à partir d’un document d’identité ou d’un passeport numérisé).

Méthode	`POST`
URL	`/v2/basic/NewGuest`

Corps de la requête :

{
    "reservationId": "1234",
    "roomId": "5436",
    "guest": {
        "guestId": null,
        "loyaltyId": "qwe3498",
        "firstName": "Adriano",
        "lastName1": "Celentano",
        "lastName2": null,
        "nationality": "ITA",
        "birthdate": "19380106",
        "gender": "M",
        "idTypeName": "D",
        "idNumber": "53487956B",
        "idIssueDate": "20010101",
        "idExpirationDate": "20110101",
        "landline": "+34987654321",
        "mobile": "+34654987321",
        "email": "[email protected]",
        "street": "via Cristoforo Gluck",
        "city": "Milano",
        "stateOrProvince": "Lombardía",
        "country": "ITA",
        "zipCode": "20125",
        "documentSupportNumber": "1234ABC",
        "relationShip": "HJ",
        "c_pro_ine": "20",
        "c_mun_ine": "100"
    }
}

Remarques :

Le guestId est toujours null dans la requête. Le PMS retourne l’identifiant attribué dans la réponse.
La validation des données doit être effectuée côté PMS.
Les champs vides sont autorisés et seront envoyés.
Si le client existe déjà dans le PMS, ses données doivent être mises à jour.

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "guestId": 12345
    },
    "pmsMessage": null,
    "userMessage": null
}

6.5 TouristTax

Récupère la taxe de séjour locale. Cet endpoint n’est pas nécessaire si la taxe est déjà incluse dans le prix retourné par l’endpoint Reservation.

Méthode	`GET`
URL	`/v2/TouristTax`

Paramètres de requête :

Paramètre	Type	Description
`arrivalDate`	string	Date d’arrivée (`yyyyMMdd`)
`departureDate`	string	Date de départ (`yyyyMMdd`)
`numberOfAdults`	int	Nombre d’adultes
`numberOfChildren`	int	Nombre d’enfants
`roomTypeId`	int	Identifiant du type de chambre

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "price": 9.50,
        "currency": "EUR"
    },
    "pmsMessage": null,
    "userMessage": null
}

6.6 AddPayment

Enregistre un paiement effectué par le client à la borne. La requête peut contenir un ou plusieurs types de paiement simultanément (carte, espèces et/ou générique).

Méthode	`POST`
URL	`/v2/basic/AddPayment`

Corps de la requête :

{
    "reservationId": "123456",
    "roomId": "123",
    "paymentType": {
        "cardPayment": {
            "amount": 12.50,
            "currency": "EUR",
            "dateTime": "20200130T0551",
            "accountNumber": 0,
            "securityCode": null,
            "cardType": "Mastercard"
        },
        "cashPayment": {
            "amount": 25.00,
            "currency": "EUR",
            "dateTime": "20200130T0551"
        },
        "genericPayment": {
            "paymentType": "Bizum",
            "amount": 25.00,
            "currency": "EUR",
            "dateTime": "20200130T0551",
            "transactionId": "3409jpf0gddfs"
        }
    }
}

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": true,
    "pmsMessage": null,
    "userMessage": null
}

6.7 CheckIn (Exécution)

Exécute le check-in pour une réservation et une chambre.

Méthode	`POST`
URL	`/v2/basic/CheckIn`

Corps de la requête :

{
    "reservationId": "1234",
    "roomId": "5436"
}

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": true,
    "pmsMessage": null,
    "userMessage": null
}

6.8 CheckIn (Annulation)

Annule un check-in si une erreur survient pendant le processus. Le PMS doit rétablir l’état précédant le check-in.

Méthode	`DELETE`
URL	`/v2/basic/CheckIn`

Corps de la requête :

{
    "reservationId": "123ABC",
    "roomId": "5436"
}

Réponse : Réponse standard avec result: null en cas de succès.

6.9 SelectedCultureName

Notifie le PMS de la langue sélectionnée par le client sur la borne, afin que le PMS puisse adapter ses réponses en conséquence.

Méthode	`PUT`
URL	`/v2/basic/SelectedCultureName`

Corps de la requête :

{
    "cultureName": "ES"
}

Réponse : Réponse standard avec result: true en cas de succès.

7. Module walk-in (Optionnel)

Implémentez ce module si vous souhaitez que la borne accepte les clients sans réservation (walk-in) — des clients qui n’ont pas de réservation préalable et qui souhaitent réserver et effectuer le check-in directement à la borne.

7.1 GuestTypes

Récupère les types de clients disponibles (ex. : Standard, Fidélité).

Méthode	`GET`
URL	`/v2/GuestTypes`
Paramètres	Aucun

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "guestType": [
            { "guestTypeId": 1, "guestTypeName": "Standard" },
            { "guestTypeId": 2, "guestTypeName": "Loyalty" }
        ]
    },
    "pmsMessage": null,
    "userMessage": null
}

7.2 RoomTypes

Récupère les types de chambres disponibles avec leur statut de disponibilité.

Méthode	`GET`
URL	`/v2/RoomTypes`
Paramètres	Aucun

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "roomType": [
            {
                "roomTypeId": 1,
                "roomTypeName": "Individual",
                "maxOcuppancy": 1,
                "description": "Sea sight non-smoker",
                "isAvailable": true
            },
            {
                "roomTypeId": 2,
                "roomTypeName": "Double",
                "maxOcuppancy": 1,
                "description": "Sea sight non-smoker",
                "isAvailable": true
            },
            {
                "roomTypeId": 4,
                "roomTypeName": "Junior Suite",
                "maxOcuppancy": 1,
                "description": "Sea sight non-smoker",
                "isAvailable": false
            }
        ]
    },
    "pmsMessage": null,
    "userMessage": null
}

7.3 BoardTypes

Récupère les types de pension disponibles (formules repas) avec leurs tarifs.

Méthode	`GET`
URL	`/v2/BoardTypes`

Paramètres de requête :

Paramètre	Type	Description
`RoomTypeId`	int	Identifiant du type de chambre
`NumberGuests`	int	Nombre de clients
`Nights`	int	Nombre de nuits

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "boardType": [
            {
                "boardTypeId": 1,
                "boardTypeName": "AD",
                "description": "bed & breakfast",
                "isAvailable": true,
                "price": 100
            },
            {
                "boardTypeId": 2,
                "boardTypeName": "MP",
                "description": "half board",
                "isAvailable": true,
                "price": 200
            }
        ]
    },
    "pmsMessage": null,
    "userMessage": null
}

7.4 TimeSlots

Récupère les options de créneaux horaires disponibles pour le séjour.

Méthode	`GET`
URL	`/v2/TimeSlots`
Paramètres	Aucun

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "timeSlots": [
            {
                "timeSlotId": 43,
                "timeSlotName": "12 hours",
                "description": "only for some kind of guests",
                "isAvailable": true
            },
            {
                "timeSlotId": 1,
                "timeSlotName": "1 night",
                "description": "check-in from 22:00 and check-out before 12:00",
                "isAvailable": true
            }
        ]
    },
    "pmsMessage": null,
    "userMessage": null
}

7.5 Rates

Récupère les plans tarifaires disponibles.

Méthode	`GET`
URL	`/v2/Rates`
Paramètres	Aucun

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": [
        { "rateId": 1, "name": "Rack rate", "isAvailable": true },
        { "rateId": 2, "name": "Group rate", "isAvailable": true },
        { "rateId": 3, "name": "Family rate", "isAvailable": true }
    ],
    "pmsMessage": null,
    "userMessage": null
}

7.6 TotalPrice

Calcule le prix total pour une combinaison de paramètres donnée.

Méthode	`GET`
URL	`/v2/TotalPrice`

Paramètres de requête :

Paramètre	Type	Description
`arrivalDate`	string	Date d’arrivée (`yyyyMMdd`)
`numberOfNights`	int	Nombre de nuits
`roomTypeId`	int	Identifiant du type de chambre
`numberOfAdults`	int	Nombre d’adultes
`numberOfChildren`	int	Nombre d’enfants
`boardTypeId`	int	Identifiant du type de pension
`timeSlotId`	int	Identifiant du créneau horaire
`rateId`	int	Identifiant du plan tarifaire

S’il n’y a pas de disponibilité pour la combinaison donnée, retournez un résultat vide.

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "stayPrice": 100.0,
        "currency": "EUR"
    },
    "pmsMessage": null,
    "userMessage": null
}

7.7 Walk-in CheckIn

Crée une nouvelle réservation et effectue le check-in pour un client sans réservation en une seule opération.

Méthode	`POST`
URL	`/v2/walk-in/CheckIn`

Corps de la requête :

{
    "roomTypeId": 1,
    "arrival": "20200108T1600",
    "departure": "20200110T1600",
    "numberOfAdults": 1,
    "numberOfChildren": 0,
    "notes_remarks": "guest requested a room in the lower floors",
    "price": 100,
    "outstanding": 0,
    "currency": "EUR",
    "boardTypeId": 0,
    "guests": [
        {
            "guestId": null,
            "firstName": "Adriano",
            "lastName1": "Celentano",
            "nationality": "ITA",
            "birthdate": "19380106",
            "gender": "M",
            "idTypeName": "D",
            "idNumber": "53487956B",
            "idIssueDate": "20010101",
            "idExpirationDate": "20110101",
            "email": "[email protected]",
            "country": "ITA",
            "documentSupportNumber": "1234ABC",
            "relationShip": "HJ"
        }
    ]
}

Réponse : Retourne l’ensemble des données de la réservation (même structure que la réponse de l’endpoint Reservation), incluant la chambre attribuée et l’identifiant de réservation.

8. Module upselling (Optionnel)

Implémentez ce module pour proposer aux clients des surclassements de chambre et des services supplémentaires (spa, petit-déjeuner, navette aéroport, etc.) pendant le processus de check-in à la borne.

8.1 RoomUpgradeOptions

Récupère les options de surclassement de chambre disponibles pour une réservation donnée.

Méthode	`GET`
URL	`/v2/upselling/RoomUpgradeOptions`

Paramètres de requête :

Paramètre	Type	Description
`reservationId`	string	Identifiant de la réservation
`roomId`	string	Identifiant de la chambre actuelle

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": [
        {
            "roomType": {
                "roomTypeId": 1,
                "roomTypeName": "Twin room",
                "maxOccupancy": 3,
                "description": "Sea sight non-smoker",
                "isAvailable": true
            },
            "priceIncrement": 25.00,
            "touristTaxIncrement": 1.00,
            "currency": "EUR"
        },
        {
            "roomType": {
                "roomTypeId": 4,
                "roomTypeName": "Presidential suite",
                "maxOccupancy": 6,
                "description": "Sea sight non-smoker",
                "isAvailable": true
            },
            "priceIncrement": 35.00,
            "touristTaxIncrement": 5.00,
            "currency": "EUR"
        }
    ],
    "pmsMessage": null,
    "userMessage": null
}

8.2 UpsellingOptions

Récupère les services d’upselling disponibles (ex. : petit-déjeuner, spa, navette aéroport).

Méthode	`GET`
URL	`/v2/upselling/UpsellingOptions`

Paramètres de requête (tous optionnels) :

Paramètre	Type	Description
`bookingCode`	string	Référence de réservation
`roomId`	string	Identifiant de la chambre
`RoomTypeId`	string	Identifiant du type de chambre
`Arrival`	string	Date d’arrivée
`Departure`	string	Date de départ

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": [
        {
            "upsellingId": "s1",
            "name": "Continental breakfast",
            "description": "The best continental breakfast you have ever tasted",
            "price": 8.50,
            "currency": "EUR",
            "isAService": false,
            "startDateTime": null,
            "endDateTime": null,
            "minUnits": 1,
            "maxUnits": 1,
            "appliesPerGuest": true,
            "appliesPerDay": true
        },
        {
            "upsellingId": "s3",
            "name": "Airport shuttle",
            "description": "Enjoy our airport ride at the most affordable prices",
            "price": 50.00,
            "currency": "EUR",
            "isAService": true,
            "startDateTime": null,
            "endDateTime": null,
            "minUnits": 1,
            "maxUnits": 1,
            "appliesPerGuest": false,
            "appliesPerDay": false
        }
    ],
    "pmsMessage": null,
    "userMessage": null
}

Référence des champs d’upselling :

Champ	Type	Description
`isAService`	boolean	Si `true`, l’élément est un service réservable avec des créneaux de date/heure
`appliesPerGuest`	boolean	Si `true`, le prix est par client (multiplié par le nombre de clients)
`appliesPerDay`	boolean	Si `true`, le prix est par jour (multiplié par le nombre de nuits)

8.3 Upselling (Exécution)

Confirme les produits d’upselling sélectionnés pour une réservation.

Méthode	`POST`
URL	`/v2/upselling/Upselling`

Corps de la requête :

{
    "bookingCode": "ABC123",
    "roomId": "123",
    "guestId": "3",
    "upsellingProduct": [
        {
            "upsellingId": 1,
            "count": 1,
            "startDateTime": "20222601T1700",
            "endDateTime": "20222601T1900"
        },
        {
            "upsellingId": 2,
            "count": 1,
            "startDateTime": null,
            "endDateTime": null
        }
    ]
}

Réponse : Réponse standard avec result: null en cas de succès.

8.4 ExtraChargeToFolio

Ajoute des frais supplémentaires au folio du client (pour les articles achetés en dehors du flux d’upselling standard).

Méthode	`POST`
URL	`/v2/upselling/ExtraChargeToFolio`

Corps de la requête :

{
    "bookingCode": "ABC123",
    "extraCharge": [
        {
            "roomId": 123,
            "guestId": 3,
            "concept": "golf lesson",
            "count": 1,
            "netAmount": 100.00,
            "taxAmount": 21.00,
            "grossValue": 121.00,
            "currency": "EUR",
            "startDateTime": "20222601T1700",
            "endDateTime": "20222601T1900",
            "chargeReference": "3ew6eg3-1245g44"
        }
    ]
}

Réponse : Réponse standard avec result: null en cas de succès.

9. Module de séjour (Optionnel)

Implémentez ce module pour permettre aux clients de gérer leur séjour depuis la borne : consulter les détails du séjour en cours, prolonger le séjour et effectuer le check-out.

9.1 Stay

Récupère les données du séjour en cours pour une chambre.

Méthode	`GET`
URL	`/v2/Stay`

Paramètres de requête (l’un des deux) :

Paramètre	Type	Description
`roomId`	string	Identifiant de la chambre
`roomName`	string	Nom/numéro de la chambre

Exemple de réponse :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "roomId": "5436",
        "roomName": "101",
        "roomTypeId": 1,
        "roomTypeName": "Twin room",
        "description": "Sea sight non-smoker",
        "adults": 1,
        "children": 0,
        "isAvailable": false,
        "status": "CheckIn",
        "price": 100,
        "deposit": 90,
        "currency": "EUR",
        "boardTypeId": 1,
        "boardTypeName": "AD",
        "guests": [
            {
                "guestId": 1476,
                "firstName": "Joaquín Ramón",
                "lastName1": "Martínez",
                "lastName2": "Sabina",
                "nationality": "ESP",
                "birthdate": "19490212",
                "gender": "M",
                "idTypeName": "D",
                "idNumber": "53487956B",
                "email": "[email protected]",
                "city": "Madrid",
                "country": "ESP"
            }
        ]
    },
    "pmsMessage": null,
    "userMessage": null
}

9.2 ExtendStayOption

Vérifie si un séjour peut être prolongé et retourne le supplément tarifaire.

Méthode	`GET`
URL	`/v2/ExtendStayOption`

Paramètres de requête :

Paramètre	Type	Description
`reservationCode`	string	Code de réservation
`roomName`	string	Nom de la chambre
`nights`	int	Nombre de nuits supplémentaires

Réponse en cas de succès :

{
    "returnCode": 0,
    "description": "Success",
    "result": {
        "totalPriceIncrement": 80.0,
        "totalTouristTaxIncrement": 4.00,
        "currency": "EUR"
    },
    "pmsMessage": null,
    "userMessage": null
}

Réponse en cas d’impossibilité :

{
    "returnCode": -1,
    "description": "The stay can not be extended",
    "result": null,
    "pmsMessage": null,
    "userMessage": null
}

9.3 ExtendStay

Confirme la prolongation du séjour.

Méthode	`POST`
URL	`/v2/ExtendStay`

Corps de la requête :

{
    "reservationCode": "1234",
    "roomName": "101",
    "nights": "2"
}

Réponse : Réponse standard avec returnCode: 0 en cas de succès, returnCode: -1 en cas d’échec.

9.4 CheckOut

Effectue le check-out pour une chambre. La borne vérifie qu’il n’y a pas de frais en attente (via l’endpoint Stay) avant d’appeler cet endpoint.

Méthode	`POST`
URL	`/v2/CheckOut`

Corps de la requête :

{
    "bookingCode": "123456",
    "roomId": "1234",
    "roomName": "101"
}

Codes d’erreur pour CheckOut :

returnCode: 0 — Check-out effectué avec succès
returnCode: -1 — Nom de chambre introuvable
returnCode: -2 — Code de réservation introuvable
returnCode: -3 — Le code de réservation et le nom de la chambre ne correspondent pas

10. Prérequis d’intégration

Pour commencer le processus d’intégration et de test, veuillez nous fournir :

Une URL de test — Une URL de base permettant d’accéder à vos endpoints API (ex. : https://api.your-pms.com)
Documentation de l’API — Définitions des méthodes avec les paramètres d’entrée/sortie. Idéalement, une collection Swagger ou Postman avec des exemples.
Identifiants de test — Une clé API et des données de réservation de test que nous pourrons utiliser pendant le développement.

Besoin d’aide ? Contactez notre équipe d’intégration à l’adresse [email protected] pour obtenir de l’assistance pendant le processus de développement.