Autenticazione
Ogni richiesta autenticata porta con sé una chiave API bearer. La chiave identifica la struttura su cui stai operando e gli ambiti che ti è consentito usare. Non ci sono nomi utente, password o flussi OAuth: una chiave per integrazione.
Una chiave API di Veridien si presenta così:
vrdn_live_xxxxxxxxxxxxxxxxxxxx- Ha il prefisso
vrdn_live_. - Viene mostrata una sola volta, alla creazione. Veridien conserva soltanto un hash SHA-256 della chiave, che non può più essere recuperata, solo revocata e sostituita.
- È legata a una sola struttura. La struttura è implicita nella chiave, quindi nessun endpoint ti chiede un identificativo di struttura.
Tratta le chiavi come password
Una chiave concede i suoi ambiti sui dati reali della tua struttura. Tienila in un archivio di segreti lato server o in una variabile d'ambiente, mai nel codice lato client o in un repository pubblico. Se una chiave viene esposta, revocala subito ed emettine una nuova.
Crea le chiavi nella dashboard, in Impostazioni → Chiavi API:
- Clicca su Crea chiave e dalle un nome descrittivo (per esempio,
Sunrise Bay booking engine). - Seleziona gli ambiti di cui l'integrazione ha bisogno, concedendo il minimo necessario.
- Copia la chiave mostrata nella finestra di conferma e conservala in modo sicuro. Non verrà mostrata di nuovo.
Le chiavi possono essere revocate in qualsiasi momento dalla stessa schermata. Una chiave revocata smette di funzionare subito, e le richieste che la usano restituiscono 401.
Metti la chiave nell'intestazione Authorization di ogni richiesta:
curl https://veridien.app/api/v1/me \
-H "Authorization: Bearer vrdn_live_xxxxxxxxxxxxxxxxxxxx"Una chiamata riuscita a /me conferma che la chiave funziona e ne riporta struttura e ambiti:
{
"property_id": "p_8f2a1c",
"property_slug": "sunrise-bay",
"scopes": ["availability:read", "reservations:write", "folio:write"],
"request_id": "req_a1b2c3d4e5"
}Se l'intestazione manca o è malformata ricevi 401 missing_api_key, se la chiave è sconosciuta, disattivata o scaduta ricevi 401 invalid_api_key.
Una chiave può chiamare un endpoint solo se possiede l'ambito di quell'endpoint. Chiamare un endpoint senza il suo ambito restituisce 403 insufficient_scope. Gli ambiti hanno la forma resource:action.
| Ambito | Concede |
|---|---|
availability:read | Leggere disponibilità e tariffe (/availability, /rates, /room-types, /services e le offerte pubblicate). |
rates:read | Leggere le risorse di gestione tariffaria (GET /rate-plans/{id}/intervals, /inclusions, /promo-codes). Gli endpoint di lettura dei prezzi (/rates, /rate-plans) accettano availability:read. |
rates:write | Creare, aggiornare ed eliminare piani tariffari e promozioni, intervalli stagionali, inclusioni e crediti, e codici promozionali (/rate-plans, /intervals, /promo-codes). |
reservations:read | Elencare e leggere le prenotazioni (/reservations, /reservations/{id}). |
reservations:write | Creare blocchi, confermare prenotazioni e annullare (/holds, /holds/{id}/confirm, /reservations/{id}/cancel). |
guests:read | Leggere le schede degli ospiti, esclusi i dati personali. |
guests:read:pii | Restituire in più i dati personali dell'ospite (email, telefono, indirizzo, documento). |
guests:write | Registrare, collegare e aggiornare gli ospiti (POST /guests, PATCH /guests/{id}). |
loyalty:read | Leggere saldo punti, livello e movimenti fedeltà di un ospite. |
loyalty:write | Riscattare i punti fedeltà (/loyalty/redemptions). |
folio:read | Leggere il conto di una prenotazione. |
folio:write | Registrare addebiti su un conto (/reservations/{id}/folio/charges). |
webhooks:manage | Riservato alla futura gestione degli abbonamenti ai webhook. |
Privilegio minimo
Concedi solo gli ambiti di cui un'integrazione ha bisogno. Un widget di sola lettura della disponibilità richiede il solo availability:read, un motore di prenotazione completo di solito richiede availability:read, guests:write, reservations:write e folio:write, più loyalty:* se mostra i punti.
Le schede degli ospiti si dividono in una vista base e una vista PII. Con guests:read ricevi gli identificativi e i campi non sensibili (nome, nazionalità, stato, indicatore di verifica come residente locale). Per ricevere in più email, phone, address e i campi del documento, la chiave deve possedere anche guests:read:pii. Così puoi costruire, per dire, un widget pubblico che legge lo stato di un ospite senza mai esporne i recapiti.
Due endpoint meta non richiedono né chiave né ambito:
GET /health: una sonda di attività che restituisce{ "status": "ok" }.GET /openapi.json: lo schema OpenAPI 3.1 dell'intera API.
Tutto il resto richiede una chiave valida con l'ambito adeguato.
- Convenzioni: errori, idempotenza, paginazione e limiti di frequenza.
- Avvio rapido: un flusso di prenotazione completo, dalla chiave alla prenotazione confermata.