# API-Schnellstart

Alles, was das Dashboard kann, steht als JSON-REST-API zur Verfügung. Typische Einsatzzwecke: Buchungen aus Ihrem PMS oder Ihrer Buchungsmaschine anlegen, den Gästeportal-Link in Ihre eigenen Nachrichten einfügen, die Daten des Online-Check-ins lesen oder die MTA-Meldung in die Buchhaltung übernehmen.

Die vollständige Referenz finden Sie unter [/api/docs](/api/docs), maschinenlesbar als [OpenAPI 3.1](/api/v1/openapi.json).

## 1. API-Schlüssel erstellen

**Settings → API keys** (Einstellungen → API-Schlüssel, nur für Owner): Geben Sie dem Schlüssel einen Namen und eine **Rolle**. Der Schlüssel darf genau das, was diese Rolle darf – verwenden Sie *Viewer* für reine Lese-Integrationen. Der vollständige Schlüssel (`gpk_…`) wird **einmal** angezeigt; bewahren Sie ihn in Ihrem Secret Store auf. Dort können Sie ihn jederzeit widerrufen.

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

## 2. Erster Aufruf

Senden Sie den Schlüssel als Bearer-Token. Die Basis-URL ist Ihre Portaladresse.

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

Die Antwort nennt Ihnen den Mandanten, die Rolle des Schlüssels und seine Berechtigungen.

## 3. Buchung anlegen

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

- Mit `source` + `externalId` ist der Aufruf ein **Upsert**: Senden Sie dieselbe Reservierung erneut, wird sie aktualisiert statt doppelt angelegt.
- Überschneidende Daten liefern **409**; fügen Sie `"allowOverlap": true` hinzu, wenn das beabsichtigt ist.
- Die Antwort enthält die Buchung mit `portalUrl` – dem persönlichen Link des Gastes.

Die IDs der Unterkünfte erhalten Sie über `GET /api/v1/properties`.

## 4. Status und Check-in-Daten lesen

- `GET /api/v1/bookings?from=2026-11-01&to=2026-11-30` – Liste mit Zahlungsstatus (`eco.status`, `deposit.status`), `stayState` und `unlocked`.
- `GET /api/v1/bookings/{id}` – vollständige Buchung inkl. Daten des Online-Check-ins und Aktivitätsprotokoll.
- `GET /api/v1/bookings?format=csv` – Export als Tabelle.

## Weitere Endpunkte

| Endpunkt | Funktion |
|---|---|
| `GET /api/v1/reports/stats?propertyId=&from=&to=` | [Statistiken](/docs/statistics) pro Unterkunft und Zeitraum (`format=csv` für CSV) |
| `GET /api/v1/reports/owner-statement?propertyId=&from=&to=` | Eco-Contribution-Abrechnung für den Eigentümer; `POST …/owner-statement/send` versendet sie per E-Mail |
| `GET`/`PUT /api/v1/properties/{id}/translations` | Die [Übersetzungen](/docs/guest-languages) der Gästemappe pro Sprache; `POST …/translations/auto` ergänzt fehlende |
| `PATCH /api/v1/settings` | Enthält `stayTimes` ([früh/spät](/docs/early-check-in-late-check-out)), `journey` ([Gästenachrichten](/docs/guest-message-timeline)), `pushArrivalHours` und `checkin.formType` (`short` oder `long`) |
| `POST /api/v1/settings/journey/test` | Sendet Ihnen einen Schritt des Nachrichtenablaufs als Test |
| `GET /api/v1/push`, `POST /api/v1/push/subscribe` | [Push-Benachrichtigungen](/docs/host-app-notifications) des angemeldeten Benutzers |

Die Gäste-API akzeptiert den Header `X-GP-Lang` (`en`, `de`, `it`, `fr`, `es`, `nl`, `pl`, `mt`) und liefert die Gästemappe in dieser Sprache.

## 5. Auf Ereignisse reagieren

Statt regelmäßig abzufragen, registrieren Sie einen Webhook (**Settings → Webhooks**) und erhalten signierte Ereignisse wie `checkin.completed`, `payment.completed` oder `feedback.received` – siehe [Webhooks](/docs/webhooks).

## Konventionen

| Thema | Regel |
|---|---|
| Format | JSON in beide Richtungen, UTF-8; Datumsangaben `YYYY-MM-DD`, Zeitstempel ISO 8601 UTC |
| Fehler | HTTP-Status + `{ "error": "message" }` – 400 ungültige Eingabe, 401 ungültiger Schlüssel, 403 nicht erlaubt, 404 nicht gefunden, 409 Konflikt, 429 zu viele Anfragen |
| Beträge | Dezimalzahlen in der Kontowährung (standardmäßig EUR) |
| Geheimnisse | In Antworten maskiert; senden Sie einen leeren Wert, um ein gespeichertes Geheimnis zu behalten |

## Häufige Fragen

### Gibt es eine Sandbox?

Nutzen Sie das [Demo-Konto](/demo) zum Ausprobieren und den Sandbox-Modus von Revolut für Zahlungen. In der Demo können keine API-Schlüssel erstellt werden – legen Sie für die Entwicklung ein kostenloses Konto an.

### Gibt es eine API für Plattformbetreiber?

Ja: Die Plattform-API (`/api/platform/v1`, Schlüssel beginnen mit `gpp_`) richtet Mandanten und Domains ein. Siehe den Plattform-Abschnitt der [API-Referenz](/api/docs#platform).