Individuelle API Verbindung

Zweck dieser Seite

Diese Seite ist die praktische Anleitung für deinen ersten funktionierenden Import über die Integrations-API. Du lernst den Ablauf in klaren Schritten und verstehst das Beispiel-JSON ohne Vorwissen.

Den vollständigen technischen Vertrag mit allen Regeln und Fehlercodes erhältst du über die interne Integrationsdokumentation für Custom-Data-Imports.

Wann diese Verbindung sinnvoll ist

Nutze diese Verbindung, wenn ein externes System Daten automatisch nach Zweigen senden soll. Typische Fälle sind ERP-Exporte, interne Datenbanken oder eigene Tracking-Pipelines.

Der Kernnutzen: Du importierst serverseitig, reproduzierbar und ohne manuelle Uploads.

API oder Upload?

Zweigen bietet zwei Einstiegspfade auf derselben Custom-Data-Importbasis:

• Individuelle API-Verbindung: für wiederkehrende, automatisierte Server-zu-Server-Imports
• CSV/XLSX-Upload: für manuelle Einrichtung, Einmalimporte oder fachlich vorbereitete Dateien

Beide Pfade enden in derselben Validierungs- und Importpipeline. Die Lanes bleiben jedoch source-getrennt: Quellen aus der custom_api-Lane dürfen den Public-API-Contract nutzen; Quellen aus der csv_xlsx-Lane bleiben im Upload-Pfad.

Was du vorbereitest

Lege zuerst unter Datenquellen → Benutzerdefinierte API eine eigene Datenquelle an. Ohne gültige Datenquelle kann Zweigen den Import nicht zuordnen.

Außerdem brauchst du:

• einen API-Key mit der Berechtigung api.org.customData.ingest
• einen stabilen Idempotency-Key pro semantischem Import
• ein Backend oder einen Integrationsdienst, der den Request sendet (kein Browser-Code)
• eine Quelle, die für die API-Lane angelegt wurde

Schritt 1: Import-Request senden

Sende den Import an POST /api/integrations/v1/custom-data/imports. Der Endpoint arbeitet asynchron und antwortet bei neuen Requests mit 202 Accepted.

Pflicht-Header:

• Authorization: Bearer <API_KEY>
• Content-Type: application/json
• Idempotency-Key: <dein-stabiler-key>

Body-Beispiel:

{
  "dataSourceId": "550e8400-e29b-41d4-a716-446655440000",
  "dataset": {
    "version": 1,
    "schema": {
      "datasetId": "550e8400-e29b-41d4-a716-446655440000",
      "schemaVersion": 1,
      "name": "Revenue Import",
      "timezone": "UTC",
      "supportedGranularities": ["day"],
      "metrics": [{ "id": "revenue", "label": "Revenue", "dataType": "number", "aggregation": "sum" }],
      "dimensions": []
    },
    "data": [{ "ts": "2026-01-01T00:00:00+00:00", "metric": "revenue", "value": 1234.56 }],
    "meta": {
      "exportedAt": "2026-01-02T09:00:00+00:00",
      "dataSourceId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Antworten:

• 202: Import wurde angenommen und wird verarbeitet.
• 200: Derselbe Idempotency-Key mit identischem Payload existierte bereits.

Schritt 2: Beispiel-Body verstehen

Damit der Import stabil bleibt, muss jedes Feld eine klare Rolle haben.

dataSourceId auf Top-Level ist das Ziel deiner Daten. Diese UUID muss zu einer vorhandenen Datenquelle in deiner Organisation gehören.

dataset.schema beschreibt die Struktur des Datensatzes: datasetId, schemaVersion, name, timezone, supportedGranularities, metrics und dimensions.

dataset.data enthält die Messwerte im Long-Format: jede Zeile hat Zeitstempel (ts), Kennzahl-ID (metric) und Zahlenwert (value). Der Zeitstempel muss ein ISO-Format mit Offset haben, zum Beispiel +00:00.

dataset.meta liefert Kontext zum Export: exportedAt und dataSourceId, die mit der Top-Level dataSourceId konsistent sein muss.

Schritt 3: Status abfragen

Da der Import asynchron läuft, fragst du den Status aktiv ab:

GET /api/integrations/v1/custom-data/imports/status mit dataSourceId und importRequestId.

Polling-Regel: alle 2 bis 5 Sekunden; bei COMPLETED oder FAILED stoppen.

Schritt 4: Fehler behandeln

Behandle Fehler über den Fehlercode, nicht über Freitext:

• 401 unauthorized / 403 forbidden: Authentifizierung oder Berechtigung prüfen
• 409 idempotency_key_mismatch: denselben Key nicht mit verändertem Payload wiederverwenden
• 413 payload_too_large: Request aufteilen oder Datensatz verkleinern
• 429 rate_limited: Intervall erhöhen und Backoff verwenden

Betriebsregeln

• Nutze die API für geplante oder wiederkehrende Imports.
• Nutze den Upload, wenn ein Mensch die Datei vor dem Import prüfen soll.
• Halte eine Quelle in genau einer Lane.
• Behandle nur COMPLETED und FAILED als terminale Importzustände.