# Snel aan de slag met de API

Alles wat het dashboard doet, is beschikbaar als JSON REST API. Typische toepassingen: boekingen aanmaken vanuit je PMS of boekingsmodule, de link naar het gastenportaal in je eigen berichten zetten, de gegevens van het online inchecken uitlezen of de MTA-aangifte in je boekhouding binnenhalen.

De volledige referentie staat op [/api/docs](/api/docs), machineleesbaar als [OpenAPI 3.1](/api/v1/openapi.json).

## 1. Maak een API-sleutel aan

**Settings → API keys** (alleen owners): geef de sleutel een naam en een **rol**. De sleutel kan precies wat die rol kan — gebruik *Viewer* voor integraties die alleen lezen. De volledige sleutel (`gpk_…`) wordt **één keer** getoond; bewaar hem in je secret store. Je kunt hem daar op elk moment intrekken.

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

## 2. Doe je eerste aanroep

Stuur de sleutel mee als bearer token. De basis-URL is je portaaladres.

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

Het antwoord vertelt je de tenant, de rol van de sleutel en de bijbehorende rechten.

## 3. Maak een boeking aan

```
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
  }'
```

- Met `source` + `externalId` is de aanroep een **upsert**: als je dezelfde reservering opnieuw stuurt, wordt die bijgewerkt in plaats van gedupliceerd.
- Overlappende data geven **409** terug; voeg `"allowOverlap": true` toe als dat de bedoeling is.
- Het antwoord bevat de boeking met `portalUrl` — de persoonlijke link van de gast.

Accommodatie-ID's haal je op met `GET /api/v1/properties`.

## 4. Status en incheckgegevens uitlezen

- `GET /api/v1/bookings?from=2026-11-01&to=2026-11-30` — lijst met betaalstatussen (`eco.status`, `deposit.status`), `stayState` en `unlocked`.
- `GET /api/v1/bookings/{id}` — volledige boeking incl. gegevens van het online inchecken en activiteitenlogboek.
- `GET /api/v1/bookings?format=csv` — export als spreadsheet.

## Meer endpoints

| Endpoint | Wat het doet |
|---|---|
| `GET /api/v1/reports/stats?propertyId=&from=&to=` | [Statistieken](/docs/statistics) per accommodatie en periode (`format=csv` voor CSV) |
| `GET /api/v1/reports/owner-statement?propertyId=&from=&to=` | Overzicht van de ecobijdrage voor de eigenaar; `POST …/owner-statement/send` mailt het |
| `GET`/`PUT /api/v1/properties/{id}/translations` | De [vertalingen](/docs/guest-languages) van de gids per taal; `POST …/translations/auto` vult ontbrekende aan |
| `PATCH /api/v1/settings` | Bevat `stayTimes` ([vroeg/laat](/docs/early-check-in-late-check-out)), `journey` ([gastberichten](/docs/guest-message-timeline)), `pushArrivalHours` en `checkin.formType` (`short` of `long`) |
| `POST /api/v1/settings/journey/test` | Stuurt één stap van de berichtentijdlijn als test naar jou |
| `GET /api/v1/push`, `POST /api/v1/push/subscribe` | [Meldingen op de telefoon](/docs/host-app-notifications) van de ingelogde gebruiker |

De gast-API accepteert de header `X-GP-Lang` (`en`, `de`, `it`, `fr`, `es`, `nl`, `pl`, `mt`) en geeft de gids in die taal terug.

## 5. Reageren op events

In plaats van te pollen registreer je een webhook (**Settings → Webhooks**) en ontvang je ondertekende events zoals `checkin.completed`, `payment.completed` of `feedback.received` — zie [Webhooks](/docs/webhooks).

## Conventies

| Onderwerp | Regel |
|---|---|
| Formaat | JSON in en uit, UTF-8; datums `YYYY-MM-DD`, tijdstempels ISO 8601 UTC |
| Fouten | HTTP-status + `{ "error": "message" }` — 400 ongeldige invoer, 401 ongeldige sleutel, 403 niet toegestaan, 404 niet gevonden, 409 conflict, 429 te veel verzoeken |
| Geld | Decimale getallen in de valuta van het account (standaard EUR) |
| Geheimen | Gemaskeerd in antwoorden; stuur een lege waarde om een opgeslagen geheim te behouden |

## Veelgestelde vragen

### Is er een sandbox?

Gebruik het [demo-account](/demo) om rond te kijken en de sandboxmodus van Revolut voor betalingen. In de demo kun je geen API-sleutels aanmaken — maak een gratis account aan voor ontwikkeling.

### Is er een API voor platformbeheerders?

Ja: de platform-API (`/api/platform/v1`, sleutels die beginnen met `gpp_`) richt tenants en domeinen in. Zie het platformgedeelte van de [API-referentie](/api/docs#platform).