Panoramica dell'API
L'API di Veridien è un'interfaccia REST verso i dati della tua struttura: disponibilità e tariffe, ospiti e programma fedeltà, prenotazioni e conti. È lo stesso motore che fa funzionare i percorsi di prenotazione di Veridien, esposto perché tu possa costruirci sopra un motore di prenotazione su misura, un'app mobile per gli ospiti, un'integrazione con un programma fedeltà o qualsiasi automazione di back office.
È una comune API HTTP/JSON. Ti autentichi con una chiave API, invii e ricevi JSON e ti affidi ai codici di stato standard. Tutto è limitato a una singola struttura: una chiave non può mai leggere né modificare dati diversi da quelli della struttura a cui appartiene.
Costruita per applicazioni reali
Questa API guida da un capo all'altro il percorso di prenotazione e fedeltà in produzione delle strutture Veridien: cercare la disponibilità, bloccare una camera, registrare un ospite, confermare una prenotazione con il pagamento, registrare addebiti sul conto e accumulare o riscattare punti fedeltà. Segui l'Avvio rapido per percorrere tu stesso l'intero flusso.
Tutte le richieste passano da un unico URL di base con versione:
https://veridien.app/api/v1Ogni percorso di questo riferimento è relativo a quella base. Il controllo di stato, per esempio, è https://veridien.app/api/v1/health.
Le richieste si autenticano con una chiave API bearer nell'intestazione Authorization:
Authorization: Bearer vrdn_live_xxxxxxxxxxxxxxxxxxxxOgni chiave è legata a una sola struttura e porta un insieme di ambiti che decidono quali endpoint può chiamare. Crea e gestisci le chiavi nella dashboard, in Impostazioni → Chiavi API. Gli endpoint meta pubblici (/health, /openapi.json) non richiedono alcuna chiave, tutto il resto sì.
Vedi Autenticazione per il formato delle chiavi, l'elenco completo degli ambiti e un esempio funzionante.
- JSON in entrata, JSON in uscita. Invia
Content-Type: application/jsonsulle richieste che hanno un corpo. I nomi dei campi sono insnake_case(room_type_id,check_in_date). - Il denaro è in stringhe. Gli importi sono stringhe decimali con due cifre (
"249.00") per evitare gli arrotondamenti in virgola mobile. La valuta è un codice ISO di 3 lettere. - Le date sono stringhe. Le date di calendario si scrivono
YYYY-MM-DD. Le marche temporali sono in ISO 8601 (2026-06-19T08:30:00.000Z). - Gli errori sono uniformi. Ogni errore restituisce la stessa struttura
error, con uncodeleggibile da una macchina e unrequest_id. - I nuovi tentativi sono sicuri. Le richieste che modificano i dati accettano una
Idempotency-Key, così un nuovo tentativo non addebita né prenota mai due volte.
Le regole complete si trovano in Convenzioni.
| Area | Endpoint |
|---|---|
| Catalogo | Dettagli della struttura, tipi di camera, disponibilità e tariffe soggette a regole di visibilità. Vedi Struttura e catalogo. |
| Offerte | Elenca i piani tariffari e i pacchetti pubblici e verifica un codice promozionale prima di quotarlo. Vedi Offerte e codici promozionali. |
| Ospiti | Registra o collega un ospite, leggi e aggiorna le schede, leggi il programma fedeltà, riscatta i punti. Vedi Ospiti e programma fedeltà. |
| Prenotazioni | Blocca la disponibilità, trasforma un blocco in una prenotazione pagata, elenca e leggi le prenotazioni, annulla. Vedi Prenotazioni. |
| Conti | Leggi il conto di una prenotazione e registraci gli addebiti. Vedi Conti. |
L'API è versionata nel percorso (/api/v1). Le modifiche non retrocompatibili escono con una nuova versione, le modifiche additive (nuovi endpoint, nuovi campi facoltativi) avvengono dentro v1. Tratta i campi di risposta sconosciuti come aggiunte e ignorali invece di generare un errore.
Una descrizione OpenAPI 3.1 di ogni endpoint, leggibile da una macchina, viene servita senza autenticazione all'indirizzo:
GET https://veridien.app/api/v1/openapi.jsonUsala per generare client tipizzati o per verificare esattamente quali endpoint e quali strutture sono in produzione. È la fonte di verità e corrisponde sempre all'API in funzione.