Convenzioni

Ogni endpoint segue le stesse convenzioni per codici di stato, errori, nuovi tentativi e paginazione. Imparale una volta e valgono ovunque.

Codici di stato

La struttura di errore

Ogni errore restituisce lo stato corrispondente e un unico oggetto error:

{
  "error": {
    "type": "permission",
    "code": "insufficient_scope",
    "message": "Missing required scope: reservations:write.",
    "request_id": "req_a1b2c3d4e5"
  }
}

• type: la categoria: invalid_request, authentication, permission, not_found, conflict, rate_limit o server.
• code: un identificativo stabile e leggibile da una macchina. Basa i tuoi controlli su questo valore, non su message.
• message: una spiegazione leggibile da una persona. Puoi registrarla nei log, ma non analizzarla.
• param: il campo della richiesta che ha causato l'errore. Presente solo negli errori 400 di validazione dei campi, altrimenti omesso.
• estimated_end: una marca temporale ISO che indica quando dovrebbe finire una finestra di manutenzione. Presente solo con 503, e solo quando è stato fissato un orario di fine. È più preciso dell'intestazione Retry-After, che ne deriva, quindi preferiscilo quando mostri uno stato “torniamo alle”.
• request_id: identifica in modo univoco la richiesta. Includilo quando contatti l'assistenza.

I codici più comuni che incontrerai:

Identificativi

Tutti gli identificativi delle risorse Veridien sono UUID, per esempio 7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27. Il riferimento di prenotazione mostrato all'ospite è un'altra cosa: confirmation_code è un codice breve e leggibile da una persona (per esempio B7XKQ4M2NZ) mostrato a ospiti e personale, mai usato come identificativo di risorsa. Gli identificativi di richiesta hanno il prefisso req_. I campi che fornisci tu, come payment_reference, sono opachi per Veridien e mantengono il formato usato dal tuo sistema.

Idempotenza

Le richieste POST e PATCH sono quelle che cambiano lo stato: creare un ospite, bloccare la disponibilità, confermare una prenotazione, riscattare punti, registrare un addebito. Per rendere sicuri i nuovi tentativi, invia un'intestazione Idempotency-Key con un valore univoco (un UUID va benissimo):

curl -X POST https://veridien.app/api/v1/holds \
  -H "Authorization: Bearer vrdn_live_..." \
  -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 }'

• La prima richiesta con una data chiave viene eseguita normalmente e la sua risposta viene conservata.
• Un nuovo tentativo con la stessa chiave e lo stesso corpo riproduce la risposta conservata: nessun secondo blocco, nessun secondo addebito.
• Riutilizzare la chiave con un corpo diverso restituisce 409 idempotency_key_reuse.
• Inviare la stessa chiave in parallelo, prima che la prima richiesta sia terminata, restituisce 409 idempotency_in_progress. Riprova tra un momento e otterrai la risposta conservata. La chiave viene occupata prima che l'operazione parta, quindi la seconda richiesta non la esegue mai.
• Una richiesta che fallisce libera la sua chiave, così un nuovo tentativo in buona fede viene eseguito davvero invece di riprodurre l'errore. Vengono conservate solo le risposte riuscite: un 409 no_availability per un esaurimento momentaneo non viene riprodotto per sempre una volta che la camera si libera.

Le chiavi di idempotenza sono limitate alla singola chiave API. Usa una Idempotency-Key nuova per ogni operazione logica.

Paginazione

GET /reservations pagina con limit e offset. Gli altri endpoint di elenco (/room-types, /services, /rate-plans) restituiscono l'insieme completo della struttura e non paginano.

La risposta racchiude i risultati in data e indica se ne restano altri:

{
  "has_more": true,
  "data": [ /* ... */ ]
}

Per ottenere la pagina successiva, somma limit al tuo offset precedente. Fermati quando has_more è false.

Denaro e valuta

Ogni valore monetario è una stringa decimale, mai un numero in virgola mobile: "1310.40", non 1310.4. Interpretali con un tipo decimale, non con uno binario in virgola mobile.

Una struttura ha una sola valuta base, e un conto può portare righe in più valute contemporaneamente (una camera in USD con una riga di ristorante in MVR è normale). Da qui derivano due regole:

Gli importi in valute diverse non si sommano mai tra loro. Ovunque venga riportato un saldo, un array balances fornisce i valori reali per valuta, ed è quella la cifra di cui fidarsi:

"balances": [
  { "currency": "USD", "charges": "1310.40", "payments": "0.00", "balance": "1310.40" },
  { "currency": "MVR", "charges": "1500.00", "payments": "1500.00", "balance": "0.00" }
]

Un conto è settled solo quando non si deve nulla in nessuna valuta. Un debito in USD non viene mai compensato da un credito in MVR.

I totali complessivi sono una valorizzazione e possono essere null. Campi come balance, total_charges e folio_balance sono cifre di comodo valorizzate nella valuta base della struttura, costruite a partire dal tasso di cambio congelato su ogni riga nel momento in cui è stata scritta. Poiché il tasso è congelato, una sua modifica successiva non altera mai il valore dichiarato di un addebito già esistente. Se una riga è in una valuta per cui la struttura non ha un tasso configurato, non può essere valorizzata, e questi campi valgono null invece di un numero sbagliato. Gestisci il caso null prima di fare calcoli.

Limiti di frequenza

I limiti di frequenza usano un secchio forato (token bucket), per chiave API. Il tuo secchio contiene fino a 600 gettoni e si ricarica a un ritmo costante di 10 gettoni al secondo (600 al minuto). Ogni richiesta spende un gettone:

• Una raffica può svuotare il secchio in un colpo solo, fino a 600 richieste di fila.
• La portata sostenuta è il ritmo di ricarica, 10 richieste al secondo.

Quando il secchio è vuoto, le richieste restituiscono 429 con un'intestazione Retry-After. Attendi almeno i secondi indicati, poi riprova. Meglio mettere in cache le letture (/property, /room-types e /services portano un Cache-Control breve, mentre /availability e /rates sono disponibilità in tempo reale e volutamente non memorizzate in cache, quindi non metterle in cache nemmeno tu) ed evitare i cicli di interrogazione serrati.

Identificativi di richiesta

A ogni risposta, riuscita o con errore, è associato un request_id (restituito anche nei corpi di errore e da /me). Registralo nei log. Quando segnali un problema, l'identificativo di richiesta permette all'assistenza di risalire alla chiamata esatta.