Prenotazioni
Una prenotazione si crea in due passaggi: blocca la disponibilità mentre l'ospite paga, poi conferma il blocco trasformandolo in una prenotazione. Dividendo il flusso in questo modo, la disponibilità viene riservata nel momento in cui l'ospite si impegna, e la prenotazione viene finalizzata solo quando il pagamento va a buon fine.
Il ciclo di vita di una prenotazione
POST /holds crea una prenotazione provvisoria che tiene bloccata una camera per 15 minuti. POST /holds/{id}/confirm la trasforma in una prenotazione confermata e registra il pagamento. I blocchi non confermati scadono e liberano la disponibilità.
POST /holdsAmbito: reservations:write · supporta Idempotency-Key
Crea una prenotazione provvisoria che blocca un tipo di camera su un piano tariffario per l'intervallo di date. Il soggiorno viene tariffato (notti di camera + imposte applicabili) su un nuovo conto. Il blocco sottrae disponibilità finché non viene confermato o finché non scade la sua finestra di 15 minuti.
| Campo del corpo | Obbligatorio | Note |
|---|---|---|
room_type_id | sì | Deve appartenere a questa struttura. |
rate_plan_id | sì | Piano attivo per il tipo di camera, di cui vengono ricontrollate le regole di visibilità. |
check_in | sì | YYYY-MM-DD. |
check_out | sì | YYYY-MM-DD, successivo a check_in, massimo 30 notti. |
guest_id | sì | L'ospite per cui vale il blocco. |
adults | sì | Intero 1–20, il gruppo deve rientrare in max_occupancy. |
children | no | Intero 0–20, predefinito 0. |
child_ages | no | Array di età dei bambini (interi ≥ 0). Quando è presente fa fede sul numero di bambini e determina il prezzo per ospite aggiuntivo in base alla fascia d'età. |
bed_config | no | L'etichetta della configurazione letto scelta dall'ospite, che deve essere una di quelle offerte dal tipo di camera. Viene registrata sulla prenotazione per le pulizie. |
add_ons | no | Array di extra scelti dall'ospite (fino a 10), ciascuno tariffato sul conto al momento del blocco, così da rientrare nel totale addebitato. Vedi i campi qui sotto. |
promo_code | no | Obbligatorio se il piano tariffario scelto è protetto da un codice promozionale. |
Ogni voce di add_ons fa riferimento a un servizio prenotabile dall'ospite:
| Campo dell'extra | Obbligatorio | Note |
|---|---|---|
service_id | sì | Il servizio che viene aggiunto. |
modifier_values | no | Oggetto { modifier_key: value } per i campi di raccolta dati del servizio. Predefinito {}. |
quantity | no | Unità dell'extra (intero 1–99). Predefinito 1. |
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"
}| Errore | Quando |
|---|---|
409 no_availability | Il tipo di camera è esaurito per l'intervallo. |
404 rate_plan_not_found | Il piano non è attivo, oppure le sue regole di visibilità escludono questo ospite o questo contesto. |
400 party_too_large | adults + children supera il max_occupancy del tipo di camera. |
POST /holds/{id}/confirmAmbito: reservations:write · supporta Idempotency-Key
Incassa il pagamento nel tuo flusso, poi conferma il blocco con un payment_reference. Veridien ricontrolla la disponibilità (escludendo il blocco stesso), segna la prenotazione e la sua sistemazione come confirmed, registra il pagamento sul conto e, per i soggiorni in USD, assegna punti fedeltà sul ricavo della camera.
Il Metodo 1 è un modello di dichiarazione fiduciaria: leggi qui
Questo endpoint si basa sulla fiducia. Il tuo payment_reference è una dichiarazione di avere incassato il denaro: un'affermazione, mai una prova. Veridien non verifica che il pagamento sia avvenuto: l'esercente titolare è il tuo hotel, e fondi, contestazioni e rimborsi restano a tuo carico. Per questo:
- Invia un riferimento reale e univoco per ogni prenotazione. Non riutilizzare né modificare mai un identificativo di pagamento fra prenotazioni diverse.
- Ogni conferma viene registrata nel registro attività come dichiarazione di pagamento (chi l'ha dichiarata, il riferimento, l'importo).
- I controlli al momento della conferma rifiutano i dati palesemente sbagliati, ma non possono verificare che il denaro sia davvero passato di mano.
Se vuoi che sia Veridien a verificare il pagamento (incasso ospitato da Stripe e verificato dalla piattaforma), quello è il motore di prenotazione ospitato (Metodo 2), non questa API.
| Campo del corpo | Obbligatorio | Note |
|---|---|---|
payment_reference | sì | Il tuo identificativo di pagamento: una dichiarazione non verificata di avere incassato. La conferma è idempotente su questo valore. |
payment_currency | no | Valuta ISO-4217 facoltativa che dichiari di avere addebitato. Viene rifiutata se differisce dalla valuta della prenotazione. |
payment_amount | no | Importo facoltativo che dichiari di avere incassato. Viene rifiutato se differisce dal totale del conto. |
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
}| Errore | Quando |
|---|---|
409 hold_expired | La finestra di pagamento di 15 minuti del blocco è scaduta prima della conferma. Crea un blocco nuovo. |
409 no_availability | Il blocco ha perso la sua disponibilità fra il blocco e la conferma. |
409 not_confirmable | La prenotazione non è un blocco provvisorio confermabile (per esempio è già stata annullata). |
400 currency_mismatch | payment_currency differisce dalla valuta della prenotazione. |
400 amount_mismatch | payment_amount differisce dal totale del conto. |
Idempotente in due modi
Riconfermare una prenotazione già confermata, o ripetere lo stesso payment_reference, restituisce il risultato confermato esistente con "already_confirmed": true, senza un secondo pagamento né una seconda prenotazione (un indice univoco (folio, reference) mette l'operazione al riparo dalle richieste in parallelo). Insieme a una Idempotency-Key, la conferma si può ritentare senza rischi.
Il programma fedeltà è denominato in USD
I punti fedeltà si accumulano sul ricavo camera in USD. Un soggiorno in un'altra valuta non accumula zero in silenzio, l'accumulo saltato viene registrato per la riconciliazione finché non arriva l'accumulo multivaluta.
GET /reservationsAmbito: reservations:read
Le prenotazioni della struttura, ordinate per data di check-in dalla più remota alla più recente, ognuna con il saldo residuo del suo conto.
| Parametro di query | Note |
|---|---|
guest_id | Filtra su un solo ospite. |
status | Filtra per stato: tentative, confirmed, checked_in, checked_out, cancelled, no_show. |
limit | Dimensione della pagina, predefinita 25, massimo 100. |
offset | Record da saltare. |
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": []
}
]
}Vedi Convenzioni per scorrere i risultati pagina per pagina.
GET /reservations/{id}Ambito: reservations:read
Una singola prenotazione con le sue sistemazioni (i segmenti del soggiorno per singola camera) e il saldo del conto.
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}/cancelAmbito: reservations:write
Annulla una prenotazione tentative o confirmed e ne libera la disponibilità. Le prenotazioni con check-in già effettuato, con check-out già effettuato o già annullate non si possono annullare dall'API (409 not_cancellable). Il conto ed eventuali fatture vengono stornati (e conservati per l'audit) e, se la prenotazione era pagata, viene emesso un rimborso secondo la policy prima che la disponibilità venga liberata.
| Campo del corpo | Obbligatorio | Note |
|---|---|---|
reason | no | Viene salvato come motivo dell'annullamento. |
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 }| Campo | Tipo | Note |
|---|---|---|
refund_minor | integer | Importo rimborsato, in unità minime (centesimi). 0 quando la prenotazione non era pagata o la policy non prevede alcun rimborso. |
refund_provider | string | null | Il gestore che ha elaborato il rimborso, oppure null quando non è stato emesso alcun rimborso. |
- Conti: leggi il conto e registra gli addebiti.
- Ospiti e programma fedeltà: l'ospite a cui appartiene una prenotazione.