Conti
Un conto è il registro progressivo delle spese di una prenotazione. Raccoglie addebiti (notti di camera, imposte, servizi) e pagamenti, e il suo saldo è ciò che l'ospite deve ancora. Ogni prenotazione ha esattamente un conto, a cui si accede tramite l'identificativo della prenotazione.
Un conto può contenere più di una valuta: una camera in USD con una riga di ristorante in MVR è normale. Gli importi in valute diverse non si sommano mai tra loro. Ogni risposta riporta balances, i valori reali per valuta, ed è quella la cifra di cui fidarsi. I campi complessivi total_charges, total_payments e balance sono una valorizzazione di comodo nella valuta base della struttura.
GET /reservations/{id}/folioAmbito: folio:read
Il registro completo: ogni riga, ogni pagamento e i totali calcolati. {id} è l'identificativo della prenotazione.
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" }
]
}| Campo | Tipo | Note |
|---|---|---|
status | string | settled solo quando non si deve nulla in nessuna valuta, open negli altri casi. |
currency | string | La valuta di visualizzazione del conto (la valuta della prenotazione). |
base_currency | string | La valuta base della struttura, quella in cui sono valorizzati i totali complessivi. |
balances | array | Valori reali per valuta, con la valuta di visualizzazione per prima. Il riferimento certo su un conto multivaluta. |
balances[].balance | string | charges − payments all'interno di quella singola valuta. |
total_charges | string | null | Addebiti non inclusi nel prezzo e non stornati, valorizzati in base_currency. |
total_payments | string | null | Pagamenti valorizzati in base_currency. |
balance | string | null | total_charges − total_payments, in base_currency. |
inclusive_tax_total | string | Imposte incluse nel prezzo, mostrate a parte, non aggiunte al saldo. |
line_items[].quantity | integer | Unità addebitate (notti / conteggio). Predefinito 1. |
line_items[].unit_price | string | null | Prezzo unitario, dove amount = quantity × unit_price. null sulle righe storiche (trattalo come amount). |
line_items[].tax_rate | string | null | Solo righe di imposta: l'aliquota configurata, per esempio "12.0000" per il 12%. null negli altri casi. |
line_items[].voided | boolean | Se la riga è stata stornata o annullata. |
Come viene calcolato il saldo
Gli addebiti si possono solo aggiungere. Un addebito stornato viene registrato come scrittura di storno invece di essere cancellato, così il registro resta sempre verificabile. Il saldo conta gli addebiti non inclusi nel prezzo e non stornati meno tutti i pagamenti, mentre le imposte incluse nel prezzo sono riportate in inclusive_tax_total ma non cambiano il saldo.
Su un conto multivaluta, leggi balances. Un conto è saldato solo quando ogni valuta si azzera, quindi un debito in USD non viene mai compensato da un credito in MVR.
I totali complessivi possono essere null
total_charges, total_payments e balance sono valorizzazioni costruite sul tasso di cambio congelato su ogni riga al momento della registrazione. Se una riga è in una valuta per cui la struttura non ha un tasso configurato, non può essere valorizzata, e questi tre campi valgono null invece di un numero sbagliato. balances è sempre presente. Gestisci il caso null prima di farci dei calcoli.
POST /reservations/{id}/folio/chargesAmbito: folio:write · supporta Idempotency-Key
Aggiungi un addebito personalizzato al conto di una prenotazione: un trattamento alla spa, una comanda del ristorante addebitata sulla camera, un articolo del minibar. {id} è l'identificativo della prenotazione.
Fornisci un amount complessivo, oppure un unit_price (con una quantity facoltativa), e il totale viene calcolato come quantity × unit_price.
| Campo del corpo | Obbligatorio | Note |
|---|---|---|
description | sì | Fino a 200 caratteri. |
amount | uno dei due | Totale della riga, stringa decimale con al massimo due cifre, per esempio "120.00". Fornisci questo oppure unit_price. |
unit_price | uno dei due | Prezzo unitario, dove il totale della riga = unit_price × quantity. Fornisci questo oppure amount. |
quantity | no | Intero ≥ 1, usato con unit_price. Predefinito 1. |
category | no | Un'etichetta breve (per esempio service, restaurant). Predefinito custom. |
currency | no | Codice ISO di 3 lettere. Per impostazione predefinita, la valuta della prenotazione. Il valore in valuta base viene congelato al tasso corrente della struttura quando l'addebito viene registrato, quindi le variazioni successive del tasso non alterano mai il valore dichiarato di questo addebito. |
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 risposta restituisce l'identificativo della nuova riga e il saldo aggiornato del conto. folio_balance è la valorizzazione in valuta base ed è null quando qualche riga non può essere valorizzata, mentre balances porta i valori reali per valuta. Invia una Idempotency-Key così una richiesta ritentata non registra mai l'addebito due volte.
- Prenotazioni: la prenotazione a cui appartiene un conto.
- Conti: come funzionano i conti dentro la dashboard di Veridien.