GET/api/v1/guests
Die Gästekartei seitenweise lesen — für den Abgleich mit einem Newsletter-Werkzeug, einem CRM oder der Buchhaltung.
Rechte
guests:readPlan-Merkmal guests — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.
Abfrageparameter
| Name | Typ | Bedeutung |
|---|---|---|
limit | integer 1–200Vorgabe: 50 | Zeilen je Seite. Mehr als 200 liefert kein Aufruf, auch nicht auf Wunsch. |
cursor | undurchsichtiger Zeiger | `pagination.nextCursor` der vorigen Antwort, unverändert weitergereicht. |
updatedSince | ISO-8601 mit Zone | Nur Gäste, die sich seit diesem Zeitpunkt geändert haben. Der Filter, der aus einem Stundenkontingent ein Nichtproblem macht. |
email | EXAKTER Treffer auf die vollständige Adresse. Kleinschreibung wird angeglichen, ein Teilstring trifft nie. | |
phone | Rufnummer | EXAKTER Treffer. Die Nummer wird wie beim Schreiben nach E.164 normalisiert; eine unvollständige Nummer ergibt 400, keine Trefferliste. |
tag | string, 1–40 Zeichen | Genau dieses Merkmal. Anführungszeichen und Rückstriche sind nicht erlaubt, weil das Merkmal samt seiner Klammern gesucht wird — sonst träfe „VIP" auch „VIP-Kunde". |
vip | true | false | Nur Gäste mit bzw. ohne VIP-Kennzeichnung. |
newsletter | true | false | `true` liefert AUSSCHLIESSLICH bestätigte und nicht ausgetragene Abonnenten — die einzige Menge, an die geschrieben werden darf. `false` liefert alle übrigen. |
Mögliche Fehler
- validation — Unbekannter Parameter (ein stillschweigend ignoriertes `updated_since` wäre der teuerste Tippfehler dieser API), unlesbare Rufnummer, unlesbarer Cursor.
- forbidden — Dem Schlüssel fehlt `guests:read`.
- plan_upgrade_required — Der Plan des Betriebs enthält das Gästemodul nicht.
- rate_limited — Minutenkontingent oder das Stundenkontingent für zeilenliefernde Gästeaufrufe (120 je Stunde und Schlüssel) ausgeschöpft.
- Umschlag dieses Bereichs: `{ "data": [...], "pagination": { "limit", "nextCursor", "hasMore" }, "meta": { "restaurantId", "timezone" } }`.
- Sortiert AUFSTEIGEND nach `updatedAt`, dann `id`. Eine Zeile, die während des Blätterns geändert wird, wandert ans Ende und wird in diesem Durchlauf noch gelesen.
- `personal` ist in jeder Listenzeile `null` — auch mit der Handlung `guests.personal`.