Notes
Une note est le relevé courant d'une réservation. Elle rassemble les frais (nuitées, taxes, services) et les paiements, et son solde est ce que le client doit encore. Chaque réservation a exactement une note, adressée par l'identifiant de la réservation.
Une note peut porter plusieurs devises : une facture de chambre en USD avec une ligne de restaurant en MVR est normale. Des montants dans des devises différentes ne sont jamais additionnés. Chaque réponse fournit balances, les montants réels par devise, et c'est ce chiffre qu'il faut croire. Les champs à plat total_charges, total_payments et balance sont une valorisation de commodité, dans la devise de base de l'établissement.
GET /reservations/{id}/folioPortée : folio:read
Le grand livre complet : chaque ligne, chaque paiement et les totaux calculés. {id} est l'identifiant de la réservation.
curl "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/folio" -H "Authorization: Bearer $VRDN_KEY"{
"folio_id": "1a6c3e9f-4d2b-4e8a-b5c7-9f0e6d4a2c81",
"reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"status": "settled",
"currency": "USD",
"base_currency": "USD",
"balances": [
{ "currency": "USD", "charges": "1310.40", "payments": "1310.40", "balance": "0.00" }
],
"total_charges": "1310.40",
"total_payments": "1310.40",
"balance": "0.00",
"inclusive_tax_total": "0.00",
"line_items": [
{ "id": "8e3b5d1c-7a9f-4b2e-a6c4-0d8f2e5b7a93", "description": "Room charge - Night 1", "amount": "420.00", "quantity": 1, "unit_price": "420.00", "date": "2026-08-01", "category": "room", "revenue_type": "hotel", "is_inclusive": false, "tax_rate": null, "currency": "USD", "voided": false },
{ "id": "4f9a1c7e-2d6b-4a3f-8b9e-6c0d5f3a8e12", "description": "GST", "amount": "50.40", "quantity": 1, "unit_price": "50.40", "date": "2026-08-01", "category": "tax", "revenue_type": "hotel", "is_inclusive": false, "tax_rate": "12.0000", "currency": "USD", "voided": false }
],
"payments": [
{ "id": "b7d2f8a5-1e4c-4d9b-a3f6-8c1e0b6d4f25", "amount": "1310.40", "method": "card", "reference": "pay_abc123", "currency": "USD" }
]
}| Champ | Type | Notes |
|---|---|---|
status | string | settled seulement quand rien n'est dû dans aucune devise ; open sinon. |
currency | string | La devise d'affichage de la note (celle de la réservation). |
base_currency | string | La devise de base de l'établissement, dans laquelle les totaux à plat sont valorisés. |
balances | array | Les montants réels par devise, la devise d'affichage en premier. La référence à retenir sur une note multidevise. |
balances[].balance | string | charges − payments à l'intérieur de cette seule devise. |
total_charges | string | null | Les frais non inclus et non annulés, valorisés en base_currency. |
total_payments | string | null | Les paiements valorisés en base_currency. |
balance | string | null | total_charges − total_payments, en base_currency. |
inclusive_tax_total | string | Les taxes incluses, affichées à part ; elles ne s'ajoutent pas au solde. |
line_items[].quantity | integer | Unités facturées (nuits ou quantité). 1 par défaut. |
line_items[].unit_price | string | null | Prix unitaire ; amount = quantity × unit_price. null sur les anciennes lignes (à traiter comme amount). |
line_items[].tax_rate | string | null | Lignes de taxe uniquement : le taux configuré, par exemple "12.0000" pour 12 %. null sinon. |
line_items[].voided | boolean | Si la ligne a été annulée ou contrepassée. |
Comment le solde est calculé
Les frais ne font que s'ajouter. Une ligne de frais annulée est inscrite comme écriture de contrepassation plutôt que supprimée, le grand livre reste donc toujours auditable. Le solde compte les frais non inclus et non annulés, moins tous les paiements ; les taxes incluses sont indiquées dans inclusive_tax_total mais ne modifient pas le solde.
Sur une note multidevise, lisez balances. Une note n'est soldée que lorsque chaque devise revient à zéro, une dette en USD n'est donc jamais annulée par un crédit en MVR.
Les totaux à plat peuvent valoir null
total_charges, total_payments et balance sont des valorisations construites à partir du taux de change figé sur chaque ligne au moment où elle a été passée. Si une ligne est dans une devise pour laquelle l'établissement n'a pas de taux configuré, elle ne peut pas être valorisée, et ces trois champs valent null plutôt qu'un chiffre faux. balances est toujours présent. Traitez le cas null avant de faire des calculs dessus.
POST /reservations/{id}/folio/chargesPortée : folio:write · accepte Idempotency-Key
Ajoute des frais personnalisés à la note d'une réservation : un soin au spa, une commande au restaurant portée sur la chambre, un article de minibar. {id} est l'identifiant de la réservation.
Fournissez soit un amount à plat, soit un unit_price (avec un quantity facultatif), et le total est calculé comme quantity × unit_price.
| Champ du corps | Requis | Notes |
|---|---|---|
description | oui | 200 caractères au maximum. |
amount | au choix | Total de la ligne, chaîne décimale à deux décimales au maximum, par exemple "120.00". Fournissez ce champ ou unit_price. |
unit_price | au choix | Prix unitaire ; total de la ligne = unit_price × quantity. Fournissez ce champ ou amount. |
quantity | non | Entier ≥ 1, utilisé avec unit_price. 1 par défaut. |
category | non | Un libellé court (par exemple service, restaurant). custom par défaut. |
currency | non | Code ISO à 3 lettres. Par défaut, la devise de la réservation. La valeur en devise de base est figée au taux courant de l'établissement au moment où les frais sont passés, les changements de taux ultérieurs ne modifient donc jamais la valeur affichée de cette ligne. |
curl -X POST "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/folio/charges" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: c4f8a2d1-7e9b-4c36-a1d8-3f6e0b9a2c75" \
-d '{ "description": "Minibar - Sparkling water", "unit_price": "4.00", "quantity": 3, "category": "service" }'{
"line_item_id": "6d4f8b2a-9c1e-4f7d-b8a3-2e5c9f0a1d74",
"folio_balance": "120.00",
"balances": [{ "currency": "USD", "balance": "120.00" }]
}La réponse renvoie l'identifiant de la nouvelle ligne et le solde mis à jour de la note. folio_balance est la valorisation en devise de base, et vaut null quand une ligne ne peut pas être valorisée ; balances porte les montants réels par devise. Envoyez un Idempotency-Key pour qu'une requête retentée ne passe jamais les frais deux fois.
- Réservations : la réservation à laquelle appartient une note.
- Notes : comment les notes fonctionnent dans le tableau de bord Veridien.