Doku · API

Eine REST-API für Ihr Lokal, mit einem Schlüssel an der kurzen Leine.

Alles, was das Dashboard tut, tut es über diese API. Sie spricht JSON über HTTPS, sie antwortet unter api.guestavo.com, und ein Aufrufer kommt mit einem Schlüssel hinein, der zu genau einer Organisation gehört und nur das öffnet, was Sie angehakt haben.

Schlüssel sind freigeschaltet. Diese Seite ist die Orientierung, erzeugt wird der Schlüssel in den Einstellungen.

Ab sofort verfügbar

Schlüssel in den Einstellungen erzeugen

Ein Schlüssel gehört zu einer Organisation und wird deshalb dort angelegt: Einstellungen, dann Organisationen, dann die gewünschte, dann deren Reiter API-Schlüssel. Sie wählen die Standorte, an denen er arbeiten darf, und die Aktionen, die er dort ausführen darf, und Sie kopieren den Wert einmal, denn wir zeigen ihn nie wieder. Danach ist es ein Header an jeder Anfrage. Widerrufen Sie ihn, wann Sie möchten, und der nächste Aufruf kommt als 401 zurück.

Organisation wählen, in der er entstehen soll

Die Bauform

Schlichtes REST, keine Überraschungen

Wer im letzten Jahrzehnt irgendeine JSON-API benutzt hat, weiß bereits, wie sich diese verhält.

Basisadresse: https://api.guestavo.com, ausschließlich HTTPS. Jede dokumentierte Route liegt unter /api.
Format: JSON rein, JSON raus. Bei allem mit Body gehört Content-Type: application/json dazu. Bodies werden gegen ein Schema geprüft, bevor ein Handler sie sieht.
Methoden: GET liest, POST erzeugt, PATCH aktualisiert, DELETE entfernt. Ein Lesezugriff verändert nie etwas.
Bezeichner: UUIDs. Datumsangaben sind ISO-Kalenderdaten (2026-09-14), Uhrzeiten sind 24-stündig (19:30) in der Zeitzone des Lokals.
Wiederholungen: Einige erzeugende Routen akzeptieren einen Idempotency-Key-Header und beantworten eine Wiederholung mit der ersten Antwort, statt einen zweiten Datensatz zu schreiben.

Authentifizierung

Ein Header, eine Organisation

Ein Schlüssel ist ein Bearer-Token. Er gehört bei jeder Anfrage in den Authorization-Header. Mehr ist es nicht: kein Token-Tausch, kein Refresh.

Authorization: Bearer gvsk_your_key_here
Content-Type: application/json

01
An eine Organisation gebunden
Ein Schlüssel gehört zu genau einer Organisation und erreicht keine andere. Zielt er woandershin, kommt ein 403 zurück, das sagt, dass der Schlüssel für diese Organisation nicht gilt, ohne eine ID zu nennen, die Sie nicht sehen dürfen.
02
Durch Scopes eingegrenzt
Scopes gelten pro Modul und pro Richtung: booking:read, booking:write, menu:read, staff:read, analytics:read und so weiter. Ein Schreib-Scope bringt seine Lesehälfte mit, und der Einstellungsbildschirm sagt das ausdrücklich, statt es stillschweigend vorauszusetzen. Geld hat einen eigenen Scope: analytics:read liefert Umsatz, Marge und Lohnzahlen, und nichts sonst zieht ihn nach sich.
03
Noch enger, wenn Sie wollen
Über die Scopes hinaus lässt sich ein Schlüssel auf bestimmte Standorte und bestimmte Aktionen begrenzen. Ein Schlüssel, der am Hafen Buchungen anlegen und überall sonst nur die Karte lesen darf, ist völlig normal.
04
Er läuft ab
Neunzig Tage, sofern Sie nichts anderes sagen, und höchstens ein Jahr. Rotieren kostet nichts: neuen erzeugen, alten widerrufen.
05
Er ist ein Geheimnis
Schlüssel beginnen mit gvsk_ und verhalten sich wie ein Passwort für das Lokal. Also auf einem Server halten, nie im Browser oder in einer App, und nie in einem Repository.

Antworten

Jede Antwort trägt denselben Umschlag

Ob Erfolg oder Fehler, die oberste Ebene sieht gleich aus. Ein Client kann also auf einen einzigen Boolean verzweigen, bevor er sich irgendetwas anderes ansieht.

Erfolg

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "pagination": {
      "type": "offset",
      "totalCount": 214,
      "filteredCount": 12,
      "count": 12,
      "page": 1,
      "limit": 20,
      "hasMore": false
    }
  }
}

data trägt die Nutzlast. Eine Liste ergänzt meta.pagination mit Seite, Limit, gefilterter Anzahl und der Angabe, ob noch etwas wartet. Manche Routen legen eine Meldung für Menschen bei, und ein Anlegen antwortet mit 201.

Fehler

{
  "success": false,
  "error": {
    "message": "This API key is not permitted to use create_booking",
    "code": "FORBIDDEN",
    "details": { "reason": "tool_not_granted" }
  }
}

error.code ist der maschinenlesbare Teil und das, worauf verzweigt wird. error.message ist englische Prosa fürs Log, und details trägt bei einer Schemaverletzung die Probleme pro Feld.

Die drei, die Ihnen wirklich begegnen

401Nicht authentifiziert
Der Schlüssel fehlt, ist unlesbar, abgelaufen oder widerrufen, oder das Konto seines Inhabers gibt es nicht mehr.
Nicht weiter wiederholen. Ein Schlüssel in diesem Zustand erholt sich nie von allein, also einen neuen erzeugen und austauschen.
403Verboten
Mit dem Schlüssel ist alles in Ordnung, mit der Anfrage nicht. Entweder fehlt der Scope, oder der Schlüssel ist an eine andere Organisation gebunden, oder seine Freigaben öffnen diese Aktion oder diesen Standort nicht.
error.details.reason lesen. Dort steht, welcher der Fälle es war, und nur einer davon lässt sich vom Aufrufer beheben: ein ungeklärter Standort bedeutet, dass die Anfrage nie eine propertyId genannt hat, für die der Schlüssel gilt. Also eine nennen und es erneut versuchen.
429Zu viele Anfragen
Einer der Töpfe weiter unten ist leer.
Zurückschalten und nach dem Retry-After-Header erneut versuchen, oder nach dem Wert in X-RateLimit-Reset, falls kein Retry-After dabei ist. Dieselbe Arbeit auf mehr Schlüssel zu verteilen hilft nicht, weil die Sammeltöpfe sie zusammenzählen.

Der Rest

Ein 400 ist eine fehlerhafte Anfrage oder ein Schemaverstoß, 404 ein Datensatz, den es nicht gibt oder den Ihr Schlüssel nicht sehen darf, 409 ein Konflikt wie eine Buchung, die nicht mehr passt, 500 liegt an uns, und 503 heißt, dass die Datenbank oder eine andere Abhängigkeit nicht erreichbar ist. Die letzten beiden lohnen einen erneuten Versuch mit wachsendem Abstand.

Ratenbegrenzung

Vier Töpfe, nicht einer

Eine Anfrage mit Schlüssel wird viermal gezählt, und der erste leere Topf lehnt sie ab. Ein Limit pro Schlüssel wäre gar kein Limit, denn ein zweiter Schlüssel würde einfach einen zweiten Topf öffnen.

600pro Minute
Pro aufrufendem Host
Wird abgebucht, bevor die Route überhaupt nachgeschlagen wird, damit Herumprobieren den Probierenden kostet. Hoch angesetzt, weil ein Host für ein Dutzend Lokale vermitteln kann.
120pro Minute
Pro Schlüssel
Gezählt auf dem Token, wie es ankommt, noch vor der Prüfung. Ein ungültiger Schlüssel wird also mitgezählt.
300pro Minute
Pro Schlüsselinhaber
Alles, was die Schlüssel einer Person erzeugen, wie viele es auch sein mögen.
600pro Minute
Pro Organisation
Alles, was ein Lokal aufnimmt, gleich wer die Schlüssel hält.

Anfragen ohne Schlüssel begrenzt getrennt davon die allgemeine Grenze von 100 pro Minute je Adresse. Gezählt wird über alle Instanzen hinweg, und X-RateLimit-Limit, X-RateLimit-Remaining sowie X-RateLimit-Reset kommen mit der Antwort zurück, damit ein Client sich selbst takten kann, statt gegen die Wand zu laufen.

Beispiel

Wer kommt heute Abend

Ein echter Endpunkt von vorn bis hinten. GET /api/bookings listet die Buchungen einer Organisation, filterbar nach Standort, Zeitraum, Status und Gastname. Nötig ist booking:read, das ein booking:write-Schlüssel bereits mitbringt.

Anfrage

curl -G https://api.guestavo.com/api/bookings \
  -H "Authorization: Bearer gvsk_your_key_here" \
  --data-urlencode "organizationId=8f14e45f-ceea-467a-9f4c-1b2c3d4e5f60" \
  --data-urlencode "dateFrom=2026-09-14" \
  --data-urlencode "dateTo=2026-09-14" \
  --data-urlencode "status=confirmed" \
  --data-urlencode "limit=20"

Antwort

{
  "success": true,
  "data": [
    {
      "id": "b7a0c5d2-1f3e-4a58-9c21-6d0e7f8a9b10",
      "propertyId": "3c9d1a77-2b4e-4f60-8d5a-11e2f3a4b5c6",
      "name": "Hribar",
      "date": "2026-09-14",
      "time": "19:30",
      "partySize": 6,
      "status": "confirmed",
      "notes": "Window table if there is one"
    }
  ],
  "meta": { "pagination": { "type": "offset", "count": 1, "page": 1, "limit": 20, "hasMore": false } }
}

01
organizationId ist Pflicht und muss die Organisation sein, an die der Schlüssel gebunden ist.
02
propertyId, status, dateFrom, dateTo und search sind optionale Filter, und page zusammen mit limit blättert durch die Treffer.
03
Ein Schlüssel ohne analytics:read bekommt dieselben Buchungen ohne die Geldfelder statt einer Ablehnung, denn wer nach dem heutigen Abend fragt, soll den heutigen Abend bekommen.

Der vollständige Vertrag

Diese Seite ist nicht die Referenz

Die API registriert weit über tausend Routen, und diese Seite dokumentiert absichtlich eine davon. Was Sie als Nächstes brauchen, hängt davon ab, was Sie bauen.

01
Das OpenAPI-Dokument
Erzeugt aus denselben Schemata, gegen die der Server prüft, es kann also nicht von den Routen abweichen. Die interaktive Ansicht ist in der Produktion bewusst abgeschaltet, denn jede Route und jedes Schema zu veröffentlichen wäre eine Landkarte, über die sich ein Angreifer freut. Läuft die API lokal, liegt sie unter /docs.
02
Die Agentenschnittstelle
Wer einen Assistenten anschließt statt einen Client zu schreiben, findet dort eine deutlich kürzere Liste kuratierter Werkzeuge, beschrieben auf einer eigenen Seite.
Zur Agenten-Doku
03
Einen Menschen fragen
Eine eigene Support-Schlange für Entwickler gibt es noch nicht. Sagen Sie uns, was Sie bauen und was die API stattdessen tut, dann liest das ein Mensch.
Schreiben Sie uns

Eine REST-API für Ihr Lokal, mit einem Schlüssel an der kurzen Leine.

Schlüssel in den Einstellungen erzeugen

Schlichtes REST, keine Überraschungen

Ein Header, eine Organisation

An eine Organisation gebunden

Durch Scopes eingegrenzt

Noch enger, wenn Sie wollen

Er läuft ab

Er ist ein Geheimnis

Jede Antwort trägt denselben Umschlag

Die drei, die Ihnen wirklich begegnen

Vier Töpfe, nicht einer

Pro aufrufendem Host

Pro Schlüssel

Pro Schlüsselinhaber

Pro Organisation

Wer kommt heute Abend

Diese Seite ist nicht die Referenz

Das OpenAPI-Dokument

Die Agentenschnittstelle

Einen Menschen fragen