Réservations
Une réservation se crée en deux temps : bloquer les disponibilités pendant que le client paie, puis confirmer le blocage en réservation. Ce découpage fait que les disponibilités sont retenues dès que le client s'engage, et que la réservation n'est finalisée qu'une fois le paiement réussi.
Le cycle de vie d'une réservation
POST /holds crée une réservation provisoire qui retient une chambre pendant 15 minutes. POST /holds/{id}/confirm la transforme en réservation confirmée et enregistre le paiement. Les blocages non confirmés expirent simplement et relâchent leurs disponibilités.
POST /holdsPortée : reservations:write · accepte Idempotency-Key
Crée une réservation provisoire qui retient un type de chambre sur un tarif pour la période. Le séjour est tarifé (nuitées et taxes applicables) sur une nouvelle note. Le blocage se décompte des disponibilités jusqu'à sa confirmation ou l'expiration de sa fenêtre de 15 minutes.
| Champ du corps | Requis | Notes |
|---|---|---|
room_type_id | oui | Doit appartenir à cet établissement. |
rate_plan_id | oui | Tarif actif pour ce type de chambre ; ses règles de visibilité sont revérifiées. |
check_in | oui | YYYY-MM-DD. |
check_out | oui | YYYY-MM-DD, après check_in ; 30 nuits au maximum. |
guest_id | oui | Le client pour qui le blocage est fait. |
adults | oui | Entier de 1 à 20 ; le groupe doit tenir dans max_occupancy. |
children | non | Entier de 0 à 20, 0 par défaut. |
child_ages | non | Tableau des âges des enfants (entiers ≥ 0). Quand il est présent, il fait foi pour le nombre d'enfants et pilote la tarification par tranche d'âge des personnes supplémentaires. |
bed_config | non | Le libellé de configuration de lits choisi par le client ; il doit faire partie de ceux qu'offre le type de chambre. Consigné sur la réservation pour l'entretien. |
add_ons | non | Tableau des extras choisis par le client (10 au maximum), chacun tarifé sur la note au moment du blocage pour être compris dans le total facturé. Voyez les champs ci-dessous. |
promo_code | non | Requis si le tarif choisi est réservé à un code promo. |
Chaque entrée de add_ons référence un service réservable par le client :
| Champ d'extra | Requis | Notes |
|---|---|---|
service_id | oui | Le service ajouté. |
modifier_values | non | Objet { modifier_key: value } pour les champs de saisie du service. {} par défaut. |
quantity | non | Unités de l'extra (entier de 1 à 99). 1 par défaut. |
curl -X POST "$VRDN_BASE/holds" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1d2c9a-8b3e-4a17-9c2f-1e5b7d0a4c83" \
-d '{
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02",
"check_in": "2026-08-01",
"check_out": "2026-08-04",
"guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
"adults": 2
}'{
"reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"folio_id": "1a6c3e9f-4d2b-4e8a-b5c7-9f0e6d4a2c81",
"hold_expires_at": "2026-06-19T08:45:00.000Z",
"total": "1260.00",
"currency": "USD",
"status": "tentative"
}| Erreur | Cas |
|---|---|
409 no_availability | Le type de chambre est complet sur la période. |
404 rate_plan_not_found | Le tarif est inactif, ou ses règles de visibilité excluent ce client ou ce contexte. |
400 party_too_large | adults + children dépasse le max_occupancy du type de chambre. |
POST /holds/{id}/confirmPortée : reservations:write · accepte Idempotency-Key
Encaissez le paiement dans votre propre parcours, puis confirmez le blocage avec un payment_reference. Veridien revérifie les disponibilités (sans compter le blocage lui-même), passe la réservation et son hébergement en confirmed, enregistre le paiement sur la note et, pour les séjours en USD, attribue des points de fidélité sur le chiffre d'affaires chambre.
La méthode 1 repose sur une déclaration de confiance, à lire absolument
Cet endpoint repose sur la confiance. Votre payment_reference est une déclaration selon laquelle vous avez encaissé l'argent : une affirmation, jamais une preuve. Veridien ne vérifie pas que l'argent a bougé : votre hôtel est le commerçant de référence, et les fonds, les litiges et les remboursements sont à votre charge. Par conséquent :
- Envoyez une référence réelle et unique pour chaque réservation. Ne réutilisez et ne modifiez jamais un identifiant de paiement d'une réservation à l'autre.
- Chaque confirmation est inscrite au journal d'audit comme une déclaration de paiement (qui a déclaré, la référence, le montant).
- Les garde-fous de la confirmation rejettent les entrées manifestement fausses, mais ils ne peuvent pas vérifier que de l'argent a réellement changé de mains.
Si vous voulez que Veridien vérifie lui-même le paiement (encaissement hébergé par Stripe et vérifié par la plateforme), c'est le rôle du moteur de réservation hébergé (méthode 2), pas de cette API.
| Champ du corps | Requis | Notes |
|---|---|---|
payment_reference | oui | Votre identifiant de paiement : une déclaration non vérifiée que vous avez encaissé. La confirmation est idempotente sur cette valeur. |
payment_currency | non | Devise ISO-4217 facultative que vous déclarez avoir facturée. Rejetée si elle diffère de la devise de la réservation. |
payment_amount | non | Montant facultatif que vous déclarez avoir encaissé. Rejeté s'il diffère du total de la note. |
curl -X POST "$VRDN_BASE/holds/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/confirm" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9a2e7c10-4b3f-4d28-8c1f-2e6b8d0a5d94" \
-d '{ "payment_reference": "pay_abc123", "payment_currency": "USD", "payment_amount": 1260.00 }'{
"reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"status": "confirmed",
"check_in_date": "2026-08-01",
"check_out_date": "2026-08-04",
"currency": "USD",
"folio_balance": "0.00",
"already_confirmed": false
}| Erreur | Cas |
|---|---|
409 hold_expired | La fenêtre de paiement de 15 minutes du blocage a expiré avant votre confirmation. Créez un nouveau blocage. |
409 no_availability | Le blocage a perdu ses disponibilités entre le blocage et la confirmation. |
409 not_confirmable | La réservation n'est pas un blocage provisoire confirmable (par exemple, elle est déjà annulée). |
400 currency_mismatch | payment_currency diffère de la devise de la réservation. |
400 amount_mismatch | payment_amount diffère du total de la note. |
Idempotent de deux façons
Reconfirmer une réservation déjà confirmée, ou rejouer le même payment_reference, renvoie le résultat confirmé existant avec "already_confirmed": true, sans deuxième paiement ni deuxième réservation (un index unique (folio, reference) met l'opération à l'abri des accès concurrents). Combinée à un Idempotency-Key, la confirmation peut être retentée sans risque.
La fidélité est libellée en USD
Les points de fidélité se cumulent sur le chiffre d'affaires chambre en USD. Un séjour dans une autre devise ne cumule pas zéro en silence ; le cumul écarté est consigné pour rapprochement, en attendant l'arrivée du cumul multidevise.
GET /reservationsPortée : reservations:read
Les réservations de l'établissement, triées par date d'arrivée, de la plus ancienne à la plus récente, avec le solde restant dû de la note de chacune.
| Paramètre de requête | Notes |
|---|---|
guest_id | Filtrer sur un seul client. |
status | Filtrer par statut : tentative, confirmed, checked_in, checked_out, cancelled, no_show. |
limit | Taille de page, 25 par défaut, 100 au maximum. |
offset | Nombre d'enregistrements à sauter. |
curl "$VRDN_BASE/reservations?guest_id=3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34&limit=10" -H "Authorization: Bearer $VRDN_KEY"{
"has_more": false,
"data": [
{
"id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"status": "confirmed",
"guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
"check_in_date": "2026-08-01",
"check_out_date": "2026-08-04",
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"room_type_name": "Deluxe Ocean Villa",
"nightly_rate": "420.00",
"currency": "USD",
"folio_balance": "0.00",
"balances": []
}
]
}Voyez Conventions pour parcourir les résultats page par page.
GET /reservations/{id}Portée : reservations:read
Une réservation unique avec ses hébergements (les segments du séjour, chambre par chambre) et le solde de sa note.
curl "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27" -H "Authorization: Bearer $VRDN_KEY"{
"id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"status": "confirmed",
"guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
"check_in_date": "2026-08-01",
"check_out_date": "2026-08-04",
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"room_type_name": "Deluxe Ocean Villa",
"nightly_rate": "420.00",
"currency": "USD",
"adults": 2,
"children": 0,
"number_of_guests": 2,
"booking_source": "direct_web",
"special_notes": null,
"folio_id": "1a6c3e9f-4d2b-4e8a-b5c7-9f0e6d4a2c81",
"folio_balance": "0.00",
"balances": [{ "currency": "USD", "charges": "1310.40", "payments": "1310.40", "balance": "0.00" }],
"accommodations": [
{
"id": "2b9e6f4d-8a3c-4e1b-9d5f-7a0c4e8b2d63",
"room_id": null,
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"check_in_date": "2026-08-01",
"check_out_date": "2026-08-04",
"status": "confirmed",
"nightly_rate": "420.00"
}
]
}POST /reservations/{id}/cancelPortée : reservations:write
Annule une réservation tentative ou confirmed et libère ses disponibilités. Les réservations dont l'arrivée ou le départ est déjà enregistré, ou déjà annulées, ne peuvent pas être annulées par l'API (409 not_cancellable). La note et les éventuelles factures sont annulées (conservées pour l'audit) et, si la réservation était payée, un remboursement conforme à la politique est émis avant la libération des disponibilités.
| Champ du corps | Requis | Notes |
|---|---|---|
reason | non | Enregistré comme motif d'annulation. |
curl -X POST "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/cancel" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{ "reason": "Guest changed plans" }'{ "reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27", "status": "cancelled", "refund_minor": 0, "refund_provider": null }| Champ | Type | Notes |
|---|---|---|
refund_minor | integer | Montant remboursé, en unités mineures (centimes). 0 quand la réservation n'était pas payée ou que la politique ne rembourse rien. |
refund_provider | string | null | Le prestataire qui a traité le remboursement, ou null si aucun remboursement n'a été émis. |
- Notes : lire le relevé et passer des frais.
- Clients et fidélité : le client à qui appartient une réservation.