Kontodaten und Berichte abfragen

Exportieren Sie geschäftsbezogene Datensätze und erstellen Sie Berichte mithilfe von Management v1. Führen Sie den Schnellstart durch und beantragen Sie die für Ihre Integration erforderlichen Berechtigungsbereiche. Jedes der folgenden Beispiele verwendet /api/graphql/management/v1 und einen dedizierten Management-Zugangsschlüssel.

Detaillierte Bestellungen exportieren

Diese Abfrage wählt Bestelldetails für ein halboffenes Zeitfenster zum Erstellungszeitpunkt aus:

query ExportOrders($after: String, $filter: OrderFilter) {
  orders(first: 100, after: $after, filter: $filter) {
    nodes {
      id
      number
      state
      paymentState
      createdAt
      updatedAt
      tombstone
      contactId
      salesChannelId
      orderChannelId
      totalGrossValueCents
      currency
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Variablen für Oktober 2026 in UTC:

{ "after": null, "filter": { "createdSince": "2026-10-01T00:00:00Z", "createdBefore": "2026-11-01T00:00:00Z" } }

Lassen Sie den Filter für alle Datumsangaben weg. Führen Sie die Seitenabfrage so lange durch, bis hasNextPage den Wert „false“ annimmt; ersetzen Sie after durch jeden zurückgegebenen Cursor, wobei die Filter unverändert bleiben. Speichern Sie jeden Datensatz nach Konto und ID. Filter nach Erstellungsdatum erfassen keine späteren Änderungen an alten Bestellungen; verwenden Sie die inkrementelle Synchronisation für fortlaufende Exporte.

Bestellungen mit den dazugehörigen Artikeln und Kunden verknüpfen

Rufen Sie zugehörige Datensätze anhand der übergeordneten IDs ab:

query OrderDetails($orderId: ID!, $contactId: ID!) {
  order(id: $orderId) {
    id
    number
    totalGrossValueCents
    currency
  }
  orderItems(filter: { orderIds: [$orderId] }, first: 100) {
    nodes {
      id
      orderId
      offerType
      offerId
      offerName
      quantity
      span
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
  contact(id: $contactId) {
    id
    firstName
    lastName
    email
    customerId
  }
}

Verwenden Sie die ID eines exportierten Auftrags und contactId. Falls kein Ansprechpartner vorhanden ist, lassen Sie die Ansprechpartnersuche weg. Führen Sie die Paginierung auch bei untergeordneten Sammlungen durch. Bei einem Data Warehouse ist es in der Regel einfacher, jede vollständige Sammlung zu exportieren und lokal zusammenzuführen, als jeden übergeordneten Eintrag separat abzufragen.

Beziehungen können null sein, und Datensätze können länger bestehen bleiben als die mit ihnen verknüpften Datensätze. Behalten Sie diese Datensätze in Ihrem Export bei. Verwerfen Sie eine Rechnung nicht einfach deshalb, weil ein zugehöriger Auftrag oder Kontakt nicht verfügbar ist.

Für historische Rechnungs- und Lieferadressen wählen Sie bei Bestellungen billingAddressSnapshot/shippingAddressSnapshot oder bei Rechnungen billingAddressSnapshot. Dafür ist zusätzlich contacts:read erforderlich. Diese gespeicherten Adressen können von der aktuellen Adresse abweichen, die über eine Adress-ID abgerufen wird.

Rechnungspositionen enthalten außerdem Nettosummen, Rabatte und gespeicherte Steuerkomponenten (taxes { salesTaxId included taxRate taxValueCents currency }). Zahlungen enthalten gespeicherte Erstattungen mit Erstattungsrechnung, Betrag, Währung und ausstehendem Bestätigungsstatus. Diese Angaben ermöglichen einen Finanzabgleich, ohne interne Daten des Zahlungsanbieters abzurufen.

Aufträge nach Vertriebskanal aufschlüsseln

In den Berichten werden alle übereinstimmenden Quelldatensätze zusammengefasst, nicht nur die erste Seite:

query OrderCounts($filter: OrderFilter) {
  orderReport(filter: $filter, metric: { measure: records, dimension: pos_id, aggregations: [count] }) {
    data {
      dimension
      label
      count
    }
  }
}

Verwenden Sie beim Vergleich von Populationen dasselbe Filterobjekt wie beim Auftragsexport; Berichte beziehen sich standardmäßig auf aktive Quelldatensätze. Ein Beispiel für eine solche Zeile ist {"dimension":"channel-id","label":"Online-Shop","count":"42"}. Dies zählt Bestellungen, nicht automatisch nur bezahlte Bestellungen oder Tickets. Fügen Sie states oder paymentStates hinzu, wenn Ihre Abfrage diese Einschränkungen erfordert.

Rechnungs- und Belegzeilenumsatz abfragen

Verwenden Sie revenueReport für den Bruttoumsatz der auf Rechnungen basierenden bzw. auf Belegen basierenden Einzelposten, anstatt die Auftragssummen als beglichene Zahlungen zu interpretieren:

query RevenueByChannel($filter: RevenueFilter, $currency: String!) {
  revenueReport(filter: $filter, currency: $currency, metric: { measure: revenue, dimension: pos_id, aggregations: [sum] }) {
    data {
      dimension
      label
      sum
      currency
    }
  }
}

Variablen:

{ "currency": "EUR", "filter": { "dates": ["[2026-10-01,2026-11-01)"] } }

Ein Beispiel für eine solche Zeile ist {"dimension":"channel-id","label":"Online-Shop","sum":"12500","currency":"EUR"}. Diese steht für einen Brutto-Positionsumsatz von 125,00 EUR, einschließlich Positionsrabatten und Steuern. Der explizite Währungsfilter filtert die Quelldatensätze; der Bericht führt keine Umrechnung durch. Führen Sie den Bericht für jede Währung separat aus. Der Umsatz auf Rechnungs- bzw. Belegzeilen stellt weder eine Zahlungsabrechnung noch einen Bankabgleich dar.

Bei Umsatzberichten filtert dates die Daten der Buchungen, createdAtDates die Daten der Zeilen-Erstellung und visitDates die Daten der Besuche. Datumsbereiche umfassen ihre untere Grenze und schließen ihre obere Grenze in der Zeitzone des Kontos aus. Zusätzliche Filter dienen zur Auswahl von Ereignissen, Eventvorlagen, Eintritten, Artikeln, Gutscheinen, Kontakten, Bestellungen und Kanälen. Siehe RevenueFilter in der generierten Referenz.

Teilnehmerdaten und benutzerdefinierte Antworten gruppieren

Verwenden Sie attendanceReport zusammen mit records/count und check_in_status, um Check-ins zu zählen. Geben Sie filter: {eventIds: [...]} oder filter: {orderIds: [...]} an, um die Quelle einzuschränken. ticket_price aggregiert die Preise der verkauften Eintrittskarten und erfordert die explizite Angabe einer Währung. Lesen Sie attendances, um die einzelnen Datensätze der Teilnehmenden hinter einer Zählung abzurufen.

Bestell-, Kontakt- und Anwesenheitsberichte unterstützen customFieldDimension: {inputId: "...", inputScope: ..., includeBlank: false} anstelle von dimension sowie optional secondaryCustomFieldDimension. Ermitteln Sie die Eingaben über customFieldInputs und wählen Sie die entsprechende inputScope-Enumeration in der Referenz aus. Bestellberichte mit benutzerdefinierten Feldern unterstützen ausschließlich records. Antworten zu benutzerdefinierten Feldern können auch direkt exportiert werden, ohne dass die Berichterstellung aktiviert ist.

Kunden filtern und übereinstimmende Konten zählen

In diesem Beispiel werden Unternehmenskonten anhand ihres Namens oder ihrer Unternehmenskennung ausgewählt. Hierfür ist contacts:read erforderlich; der Bericht erfordert außerdem reports:read sowie die Aktivierung der Berichtsfunktion.

query CompanyCustomers {
  customers(first: 100, filter: { accountTypes: ["company"], text: "Museum", discarded: false }) {
    nodes {
      id
      name
      number
      accountType
      groupId
      guest
      buyerReference
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
  customerReport(filter: { accountTypes: ["company"], text: "Museum", discarded: false }, metric: { measure: records, dimension: account_type, aggregations: [count] }) {
    data {
      dimension
      count
    }
  }
}

Fahren Sie mit der Paginierung der Liste der Kunden fort, um die vollständige Liste anzuzeigen. Die Zählung umfasst alle Treffer. Verwenden Sie addressReport, um Adressen nach Land/Stadt zu zählen, und invoiceReport, um Rechnungen nach Zahlungsstatus oder Veröffentlichungsdatum zu zählen. Ihre Filtereingaben entsprechen jeweils addresses und invoices.

Bestellungen nach einer benutzerdefinierten Antwort filtern

Ermitteln Sie die Eingabe-ID von customFieldInputs und prüfen Sie den Eingabebereich der zugehörigen Feldgruppe. Dieses Beispiel erfordert orders:read, custom-fields:read und aktivierte benutzerdefinierte Felder. Verwenden Sie eine Buchungseingabe, die die Antwort Museum akzeptiert:

query OrdersWithAnswer($inputId: ID!, $after: String) {
  orders(first: 100, after: $after, filter: { customAnswers: [{ inputId: $inputId, inputScope: BOOKING, values: ["Museum"] }] }) {
    nodes {
      id
      number
      contactId
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Übergeben Sie {"inputId":"your-input-id","after":null} und führen Sie die Paginierung wie gewohnt durch. Eine Bestellung erscheint nur einmal, auch wenn mehrere Bestellpositionen die Antwort enthalten. Verwenden Sie denselben Filter customAnswers zusammen mit orderReport, um diese Bestellungen zu zählen. Ersetzen Sie values durch missing: true, um Bestellungen ohne eine nicht leere Antwort zu ermitteln. Um die Anzahl der einzelnen gespeicherten Antworten zu ermitteln, verwenden Sie customFieldValueReport und gruppieren Sie nach input_id oder value; wiederholte Antworten bei verschiedenen Bestellpositionen werden separat gezählt.

Fehlerbehebung

Verwandte Artikel

• Referenz zur Management-API
• Synchronisierung von Management-API-Datensätzen
• Bericht auswählen