# API: guida rapida

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](/api/docs), in formato leggibile dalle macchine come [OpenAPI 3.1](/api/v1/openapi.json).

## 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.

![Settings → API keys](/site/img/docs/d-settings-apikeys.webp "Settings → API keys")

## 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](/docs/statistics) 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](/docs/guest-languages) della guida per lingua; `POST …/translations/auto` completa quelle mancanti |
| `PATCH /api/v1/settings` | Comprende `stayTimes` ([early/late](/docs/early-check-in-late-check-out)), `journey` ([messaggi agli ospiti](/docs/guest-message-timeline)), `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](/docs/host-app-notifications) 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](/docs/webhooks).

## 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](/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](/api/docs#platform).