Referenz zur Management-API

Auf dieser Seite können Sie Berechtigungsbereiche, Sammlungen und Abfrageargumente auswählen. Die generierte Referenz listet alle Felder, Filter, Eingaben und Aufzählungen auf.

Endpunkt und Authentifizierung

Senden Sie JSON-Anfragen an POST https://<api-host>/api/graphql/management/v1 unter Angabe von Content-Type: application/json und Authorization: Bearer <management-token>. Die Anmeldedaten legen ein Konto fest; lassen Sie X-Tenant-Domain weg. Ein widersprüchlicher Konto-Header wird abgelehnt. Ältere Benutzer-API-Schlüssel, JWTs und Booking-Zugangsdaten können Management-Anfragen nicht authentifizieren.

account { id name currency timeZone } gibt das ausgewählte Konto und dessen Berichtszeitzone zurück. Die Kontowährung ist ein Standardwert und stellt keine Garantie dafür dar, dass alle Finanzdatensätze diese Währung verwenden.

Datenkategorien und Berechtigungsbereiche

Jede Sammlung verfügt zudem über eine Einzelabfrage, wie beispielsweise order(id: "..."), invoiceItem(id: "...") oder customFieldValue(id: "..."). Eine fehlende oder zu einem anderen Konto gehörende ID liefert den Wert „null“. Für die Sammlung und die Suche ist derselbe Berechtigungsbereich erforderlich.

Bereiche gewähren kontoweiten Zugriff innerhalb ihrer jeweiligen Kategorie. Beziehungs-IDs können sich auf eine andere Kategorie beziehen; zum Abrufen dieser Kategorie ist ein eigener Bereich erforderlich. So umfasst beispielsweise orders:read Bestellsummen und Kontakt-IDs, während zum Abrufen von E-Mail-Adressen der Bereich contacts:read erforderlich ist.

Argumente der Sammlung

Jeder Filter unterstützt ids, createdSince, createdBefore, updatedSince, updatedBefore und discarded. Untere Zeitgrenzen sind inklusive; obere Grenzen sind exklusiv. Das Weglassen von discarded umfasst aktive und verworfene Datensätze; „true“ wählt verworfene Datensätze aus, „false“ wählt aktive Datensätze aus. Typen ohne Unterstützung für das Verwerfen geben für discarded: true keine Zeilen zurück.

Weitere Filter folgen den Beziehungen: orderItems(filter: {orderIds: [...]}), pricings(filter: {orderItemIds: [...]}), invoiceItems(filter: {invoiceIds: [...]}), payments(filter: {invoiceIds: [...]}) und customFieldValues(filter: {responseIds: [...]}). Anwesenheitsfilter akzeptieren eventIds und orderIds. Die vollständige Liste entnehmen Sie bitte den generierten Eingabetypen; die Filter unterscheiden sich je nach Sammlung.

Die Ergebnisse enthalten nodes und pageInfo { endCursor hasNextPage }, sortiert nach updatedAt in aufsteigender Reihenfolge und anschließend nach ID. Alle Datensätze enthalten id, name, number, createdAt, updatedAt, discardedAt und tombstone; bei bestimmten Datensatztypen können nullfähige Felder fehlen. Zeitstempel behalten Mikrosekunden bei. Beträge, die auf Cents enden, verwenden kleinere Währungseinheiten und werden als Dezimalzeichenfolgen serialisiert; sie behalten ihre Währung bei und werden ohne 32-Bit-Abschneidung geparst. Für den Euro bedeutet "12500" 125,00 EUR.

Geschäftsfilter

Ein und derselbe Filter-Eingabewert wird sowohl von einer Sammlung als auch vom zugehörigen Bericht akzeptiert. Innerhalb einer Liste genügt im Allgemeinen ein übereinstimmender Eintrag; verschiedene Filterfelder werden mit UND verknüpft. Die Ausnahme für tagIds steht unten. Leere Listen stimmen mit nichts überein. Berichte verwenden standardmäßig den Wert discarded: false; legen Sie diesen Wert beim Export explizit fest, wenn Sie die Anzahl der Einträge vergleichen.

tagIds erfordert bei Vorgängen, Rechnungen und Anwesenheiten alle ausgewählten Schlagwörter. Bei Vorgängen müssen alle Schlagwörter zum Angebot einer einzigen nicht verworfenen Position passen; Event-Schlagwörter umfassen geerbte Schlagwörter der Eventvorlage. Bei Rechnungen können die Schlagwörter zu verschiedenen Positionsangeboten oder Artikeln passen, einschließlich eingebetteter Unterpositionen. Bei Anwesenheiten können die Schlagwörter vom Event oder Eintritt (einschließlich geerbter Schlagwörter der Eventvorlage) und vom wirksamen Artikel stammen; ein expliziter Artikel der Anwesenheit hat Vorrang vor dem Artikel der Preisposition. Bei Kunden genügt für tagIds eines der ausgewählten Schlagwörter.

text ist eine wörtliche Teilzeichenfolge der eigenen Identifikatoren oder beschreibenden Felder des Datensatzes, bei der die Groß-/Kleinschreibung keine Rolle spielt. Verknüpfte Datensätze werden dabei nicht durchsucht; verwenden Sie für Beziehungen deren IDs. % und _ sind wörtliche Zeichen. Textfilter akzeptieren 1–255 Zeichen. Filter für Land, Ländereinstellung, Versandstatus und andere Aufzählungsfilter verwenden die genauen Werte aus der generierten Referenz.

visitDates und ticketScanDates akzeptieren halb offene, Datumsbereiche in der Zeitzone des Kontos wie beispielsweise "[2026-10-01,2026-11-01)". Die Besuchsdaten beziehen sich auf das gebuchte Angebot, nicht auf die Auftragserstellung. Angebots- und Besuchsbedingungen können für verschiedene Positionen innerhalb desselben Auftrags übereinstimmen, entsprechend den Backoffice-Auftragsfiltern. checkedInSince/checkedInBefore filtern den Zeitstempel des Anwesenheits-Check-ins; ticketScanDates filtert das damit verknüpfte Check-in-Scan-Ereignis und schließt Datensätze ohne ein solches Ereignis aus.

Für customAnswers sind custom-fields:read sowie aktivierte benutzerdefinierte Felder erforderlich. Unterstützte Anwendungsbereiche sind BOOKING/CONTACT für Bestellungen, CONTACT für Kontakte sowie ATTENDEE/BOOKING/CONTACT bei Anwesenheiten. Geben Sie ein inputId sowie entweder values oder missing: true an; werden beide weggelassen, wird jede nicht leere Antwort ausgewählt. Die Werte werden mit den normalisierten Antworten abgeglichen, wobei umgebende Leerzeichen entfernt werden; beim Export gespeicherter Antworten bleibt der ursprüngliche Text erhalten. Bis zu zehn Antwortbedingungen werden mit „UND“ kombiniert; jede Bedingung akzeptiert bis zu 100 alternative Werte. Wiederholte übereinstimmende Antworten führen nicht zu einer Duplizierung des übergeordneten Datensatzes oder dessen Zählwerts. missing: true kann nicht mit values kombiniert werden. Unterstützte Eingabetypen sind Text, Telefonnummer, E-Mail, Datum, Auswahlfeld, Optionsfeld und Kontrollkästchen; Datei-Uploads sind ausgeschlossen.

Bestellungen liefern billingAddressSnapshot und shippingAddressSnapshot; Rechnungen liefern billingAddressSnapshot. Diese geben, sofern verfügbar, die zum Zeitpunkt der Transaktion gespeicherte Adresse zurück, während Adress-IDs zu aktuellen Adressdatensätzen führen. Die Auswahl eines Snapshots erfordert zusätzlich contacts:read.

Berichte und Berechtigungsbereiche

Für alle Berichte muss die Berichtsfunktion für das Konto aktiviert sein. Außerdem sind reports:read und folgende Datenberechtigungen erforderlich:

Die vier Zählberichte unterstützen eine primäre und eine sekundäre Gruppierung sowie Zeitgruppierungen für Zeitstempel. Rechnungsanzahlen sind keine Umsätze; Antwortanzahlen zählen gespeicherte Antwortdatensätze, nicht unterschiedliche Personen. Für Rechnungs- und Belegbeträge verwenden Sie revenueReport.

Monetäre Kennzahlen sowie Gruppierungen nach Verkaufspreisbeträgen oder Umsatzklassen erfordern finance:read sowie ein explizites currency, wie beispielsweise "EUR". Es werden ausschließlich Quellbeträge in dieser Währung berücksichtigt. Bei nichtmonetären Berichten ohne monetäre Gruppierung wird die Angabe einer Währung abgelehnt. Die Gruppierung von Umsätzen nach contact_id erfordert zusätzlich contacts:read; Kennzahlen zum Zeitpunkt des Veranstaltungskaufs erfordern orders:read; die Anzahl der Teilnehmer an einer Bestellung erfordert attendance:read. Die Gruppierung nach benutzerdefinierten Feldern erfordert custom-fields:read sowie die Aktivierung benutzerdefinierter Felder für das Konto.

Übergeben Sie ein erforderliches metric-Objekt zusammen mit einem measure, einem dimension oder einem unterstützten customFieldDimension sowie einer nicht leeren aggregations-Liste. Wählen Sie kompatible Werte aus den generierten Aufzählungslisten aus. secondaryDimension fügt eine zweite Gruppierung hinzu; timeFunction und secondaryTimeFunction gruppieren zeitliche Dimensionen in der Zeitzone des Kontos. Der Bericht filter wird vor der Aggregation über den gesamten übereinstimmenden Datensatz angewendet, unabhängig von der Datensatzpaginierung. Berichte schließen verworfene Quelldatensätze standardmäßig aus.

Die Berichte geben data Zeilen mit Gruppierungskennungen, Bezeichnungen und angeforderten Aggregaten zurück. count und sum sind Dezimalzeichenfolgen; avg, min und max sind Zahlen. Nicht zutreffende Felder sind null. Verwenden Sie Gruppen-IDs als Schlüssel anstelle der übersetzten Bezeichnungen. Berichte sind auf 10.000 Gruppen und ein Zeitlimit von 15 Sekunden für Datenbankanweisungen begrenzt; bei Überschreitung des Limits wird ein Fehler zurückgegeben, anstatt einen unvollständigen Bericht auszugeben. Schränken Sie die Quellfilter ein oder unterteilen Sie die Daten nach Zeiträumen. Addieren Sie keine Durchschnittswerte aus verschiedenen Zeiträumen.

Fehler und Einschränkungen

Überprüfen Sie sowohl den HTTP-Status als auch den GraphQL-Top-Level-Wert errors. Akzeptieren Sie niemals eine fehlerhafte Seite oder einen fehlerhaften Bericht als vollständiges Ergebnis. Bei Authentifizierungsfehlern wird der HTTP-Status 401 zurückgegeben. Bei einer Ratenbegrenzung wird der HTTP-Status 429 mit Retry-After zurückgegeben. Fehlende Bereiche führen zu Not authorized; ungültige Berichtsdefinitionen führen zu GraphQL-Fehlern. Bei einem Berichtsfehler können andere ausgewählte Felder weiterhin verfügbar sein, doch ist dieser Bericht unvollständig.

Die Standardgrenzwerte für Abfragen liegen bei einer Tiefe von 8, einer Komplexität von 1.000 und 2.000 Abfrage-Tokens. Berichtsfelder verursachen höhere Komplexitätskosten; senden Sie zur Gewährleistung einer vorhersehbaren Ausführung bitte einen Bericht pro Anfrage. Es gibt keine Mutationen oder Abonnements.