Referenz

Authentifizierung & Konventionen

Alles, was für jeden Endpunkt gilt: wie man sich authentifiziert, die Limits und wie Antworten aufgebaut sind.

Authentifizierung

Jede Anfrage enthält einen Authorization: Bearer-Header mit einem Schlüssel, den du in deinem Dashboard erstellst. Schlüssel sehen aus wie oac_live_…, sind auf dein Unternehmen beschränkt und werden bei der Erstellung nur einmal angezeigt — bewahre sie sicher auf. Ein fehlender, fehlerhafter oder widerrufener Schlüssel gibt einen 401 zurück.

Authorization: Bearer oac_live_3f9a…c1e7

Jeder Lesezugriff ist automatisch auf die Restaurants deines Unternehmens beschränkt — du kannst niemals die Daten eines anderen Mandanten sehen, auch nicht durch Erraten einer ID. Erstelle oder widerrufe Schlüssel unter API-Schlüssel.

Ratenbegrenzungen

60 Anfragen pro Minute pro API-Schlüssel. Jede Antwort enthält das aktuelle Kontingent; Anfragen über dem Limit erhalten einen 429 mit einem Retry-After-Header (in Sekunden).

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 41
X-RateLimit-Reset: 1734556800
Retry-After: 17          # only on 429

Brauchst du ein höheres Limit für eine Massensynchronisierung? Sprich mit uns.

Fehler

Fehler verwenden standardmäßige HTTP-Statuscodes und einen JSON-Body mit einem menschenlesbaren error-Feld.

{ "error": "Restaurant not found" }

Status	Bedeutung
200 / 201	Erfolg. POST-Anfragen, die eine Ressource erstellen, geben 201 zurück.
400	Fehlerhafte Anfrage — ungültiges JSON oder ungültige/fehlende Felder.
401	Fehlender, fehlerhafter oder widerrufener API-Schlüssel.
404	Ressource nicht gefunden oder gehört nicht zu deinem Unternehmen.
409	Konflikt — Buchungen deaktiviert oder das Zeitfenster ist ausgebucht.
429	Ratenbegrenzung überschritten. Warte gemäß Retry-After.
5xx	Vorübergehender Serverfehler — mit Backoff erneut versuchen.

Paginierung

Listen-Endpunkte sind cursor-paginiert. Übergib limit (Standard 50, max. 100) und folge nextCursor, bis es null ist. Verlasse dich niemals auf Offsets.

Durch alle Buchungen blättern

let cursor = null;
do {
  const url = new URL("https://openalacarte.com/api/v1/bookings");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const { data, nextCursor } = await (await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.OAC_API_KEY}` },
  })).json();
  handle(data);
  cursor = nextCursor;
} while (cursor);

Versionierung & Stabilität

Die API wird in der URL versioniert (/api/v1/…). Inkompatible Änderungen werden als v2 neben der v1 ausgeliefert.
Die v1 bleibt nach jeder Veraltungsmitteilung mindestens 12 Monate online.
Additive Änderungen (neue Felder, Endpunkte, Webhook-Ereignisse) sind nicht inkompatibel — toleriere unbekannte Felder.
Alle Zeitstempel sind ISO-8601 in UTC.

Generiere ein typisiertes SDK oder importiere in Postman aus der OpenAPI-3.0-Spezifikation.