Sviluppatori · per Sviluppatori

API: guida rapida

Q: Esiste un'API per gli operatori della piattaforma?

Sì: l'API della piattaforma (/api/platform/v1, chiavi che iniziano con gpp_) crea tenant e domini. Vedi la sezione platform del riferimento API.

Crea una chiave API, fai la prima chiamata, crea prenotazioni dal tuo PMS, leggi lo stato di check-in e pagamenti e reagisci agli eventi con i webhook.

Tutto ciò che fa la dashboard è disponibile come API REST JSON. Usi tipici: creare prenotazioni dal tuo PMS o booking engine, inserire il link al portale ospiti nei tuoi messaggi, leggere i dati del check-in online o importare la dichiarazione MTA nella contabilità.

Il riferimento completo è su /api/docs, in formato leggibile dalle macchine come OpenAPI 3.1.

1. Crea una chiave API #

Settings → API keys (Impostazioni → Chiavi API, solo owner): assegna alla chiave un nome e un ruolo. La chiave può fare esattamente ciò che può fare quel ruolo — usa Viewer per le integrazioni in sola lettura. La chiave completa (gpk_…) viene mostrata una sola volta; conservala nel tuo archivio di segreti. Puoi revocarla lì in qualsiasi momento.

2. Fai la prima chiamata #

Invia la chiave come bearer token. L'URL di base è l'indirizzo del tuo portale.

curl https://stay.example.com/api/v1/me \
  -H "Authorization: Bearer gpk_xxxxxxxxxxxx"

La risposta indica il tenant, il ruolo della chiave e i relativi permessi.

3. Crea una prenotazione #

curl -X POST https://stay.example.com/api/v1/bookings \
  -H "Authorization: Bearer gpk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyId": "p_xxxxxxxxxx",
    "checkIn": "2026-11-18", "checkOut": "2026-11-23",
    "adults": 2, "children": 0,
    "guest": { "firstName": "Sofia", "lastName": "Rossi", "email": "sofia@example.com", "phone": "+39 333 1234567" },
    "source": "mypms", "externalId": "RES-48213",
    "sendPortalLink": true
  }'

Con source + externalId la chiamata è un upsert: inviando di nuovo la stessa prenotazione la si aggiorna invece di creare un duplicato.
Date sovrapposte restituiscono 409; aggiungi "allowOverlap": true se è voluto.
La risposta contiene la prenotazione con portalUrl — il link personale dell'ospite.

Gli ID delle strutture si ottengono da GET /api/v1/properties.

4. Leggi stato e dati del check-in #

GET /api/v1/bookings?from=2026-11-01&to=2026-11-30 — elenco con gli stati dei pagamenti (eco.status, deposit.status), stayState e unlocked.
GET /api/v1/bookings/{id} — prenotazione completa, inclusi i dati del check-in online e il registro attività.
GET /api/v1/bookings?format=csv — esportazione per fogli di calcolo.

Altri endpoint #

Endpoint	Cosa fa
`GET /api/v1/reports/stats?propertyId=&from=&to=`	Statistiche per struttura e periodo (`format=csv` per il CSV)
`GET /api/v1/reports/owner-statement?propertyId=&from=&to=`	Rendiconto dell'eco-contribution per il proprietario; `POST …/owner-statement/send` lo invia via email
`GET`/`PUT /api/v1/properties/{id}/translations`	Le traduzioni della guida per lingua; `POST …/translations/auto` completa quelle mancanti
`PATCH /api/v1/settings`	Comprende `stayTimes` (early/late), `journey` (messaggi agli ospiti), `pushArrivalHours` e `checkin.formType` (`short` o `long`)
`POST /api/v1/settings/journey/test`	Ti invia come test un passaggio della sequenza di messaggi
`GET /api/v1/push`, `POST /api/v1/push/subscribe`	Notifiche sul telefono dell'utente che ha effettuato l'accesso

L'API per gli ospiti accetta l'header X-GP-Lang (en, de, it, fr, es, nl, pl, mt) e restituisce la guida in quella lingua.

5. Reagisci agli eventi #

Invece di interrogare periodicamente l'API, registra un webhook (Settings → Webhooks) e ricevi eventi firmati come checkin.completed, payment.completed o feedback.received — vedi Webhook.

Convenzioni #

Argomento	Regola
Formato	JSON in ingresso e in uscita, UTF-8; date `YYYY-MM-DD`, timestamp ISO 8601 UTC
Errori	Stato HTTP + `{ "error": "message" }` — 400 input non valido, 401 chiave errata, 403 non consentito, 404 non trovato, 409 conflitto, 429 troppe richieste
Importi	Numeri decimali nella valuta dell'account (EUR per impostazione predefinita)
Segreti	Mascherati nelle risposte; invia un valore vuoto per mantenere un segreto già salvato

Domande frequenti #

Esiste una sandbox? #

Usa l'account demo per esplorare e la modalità sandbox di Revolut per i pagamenti. Nella demo non si possono creare chiavi API — crea un account gratuito per lo sviluppo.

Esiste un'API per gli operatori della piattaforma? #

Sì: l'API della piattaforma (/api/platform/v1, chiavi che iniziano con gpp_) crea tenant e domini. Vedi la sezione platform del riferimento API.