Zum Hauptinhalt springen

Entwickler-Leitfaden: Verbindung zur Klar RESTful API

Dieser Artikel bietet Entwickler:innen einen umfassenden Überblick und technische Richtlinien für die Integration externer Systeme mit der Klar RESTful API.

Verfasst von Frank Birzle
Heute aktualisiert

Entwickler-Guide: So verbindest du dein System mit der Klar API

Dieser Guide gibt dir einen Überblick und die passenden Richtlinien, um externe Systeme an die Klar RESTful API anzubinden.

Überblick

Mit der Klar API kannst du Bestelldaten aus jeder beliebigen Quelle (z. B. eigene E-Commerce-Engines, ERPs oder Legacy-Systeme) direkt zu Klar schieben. Wichtig zu wissen: Klar nutzt eine „Landing Zone“-Architektur. Das heißt, deine Daten werden erst einmal im Rohformat gespeichert und dann regelmäßig in die Dashboards verarbeitet.
​

Wichtig: Verwende diese API um Daten ZU Klar zu schicken. Es gibt (noch) keinen GET Endpunkt.

1. Quickstart: In 3 Schritten zur Anbindung

Um die ersten Daten zu senden, gehe einfach so vor:

  1. Klar-Account: Check, ob du einen aktiven Klar-Account hast.

  2. Credentials: Erstelle in der App eine Klar API Datenquelle. Das generiert deinen JWT (JSON Web Token), den du für die Authentifizierung brauchst.

  3. Abfahrt: Sende deine Bestelldaten per POST-Request an die API. Pro Request kannst du bis zu 1.000 Bestellungen in einem JSON-Array übertragen.

Wichtige Ressourcen:

2. So funktioniert die Datenverarbeitung

Das System, an das du die Daten sendest, ist nicht das gleiche System, das die Dashboards anzeigt.

  • Die Landing Zone: Deine Bestellungen landen nach dem Absenden sofort als Rohdaten in einer Datenbank.

  • Verarbeitungs-Pipeline: In den Klar-Dashboards tauchen die Daten erst auf, wenn die Pipeline läuft. Das passiert automatisch jede Stunde.

  • Manueller Trigger: Wenn es schneller gehen soll, klicke in den Shop-Einstellungen auf „Store-Daten aktualisieren“. Eine Ladeanzeige zeigt dir den Status an.

  • Debugging: Wenn etwas nicht passt, nutze den Order Debugger in der Detailansicht der Datenquelle. Dort siehst du das rohe JSON, das bei Klar angekommen ist.

3. Endpunkte & Logik

Der Haupt-Endpunkt

Der wichtigste Endpunkt ist POST /orders/json. Hier fließen alle primären Bestelldaten zusammen.

Spezial-Endpunkte (Subsets)

Es gibt spezifische Endpunkte für Refunds, COGS (Herstellungskosten), Logistikkosten und Transaktionskosten. Diese sind extrem hilfreich, wenn deine Daten über verschiedene Systeme verteilt sind.

  • Beispiel: Deine Bestellungen kommen aus Shopware, aber die Logistikkosten liegen in einem ERP. Nutze einfach den Shopware-Connector für die Orders und die Logistics-API für die Versandkosten.

Idempotenz (Updates)

Die API ist idempotent. Willst du eine Bestellung aktualisieren (z. B. Status von „pending“ auf „paid“), sende das Objekt einfach erneut mit der gleichen ID.

  • Wichtig: Es gibt keine PATCH- oder DELETE-Endpunkte. Das erneute Senden mit der gleichen ID überschreibt den alten Datensatz in der Landing Zone.

4. Technische Guidelines & Berechnungen

Versionierung

Klar API-URLs nutzen Version-Strings:

  • 12.2022: Die stabile Legacy-Version.

  • 07.2025: Die aktuelle Version (jetzt auch mit Support für Produkt-Bundles).

Steuern und Rabatte (Achtung, Stolperfalle!)

Hier passieren die meisten Fehler. Halte dich bitte strikt an diese Logik:

  • Werte pro Einheit: Sende Rabatte und Steuern für Line-Items immer pro einzelnem Stück.

  • Interne Berechnung bei Klar:

    • Gross Revenue = Quantity * Product GMV

    • Net Value = (Quantity * Product GMV) - (Quantity * Taxes) - (Quantity * Discounts)

  • Prüfsummen: Die Felder totalAmountBefore und totalAmountAfterTaxes nutzen wir nur als interne Checksummen. Die echten Metriken berechnen wir aus den Einzelwerten der Positionen.

Produkt-Bundles (v07.2025+)

Wenn du Bundles sendest, wird das Parent-Objekt der Bundle-Position für die Finanzen ignoriert. Wir berechnen die Werte „Bottom-up“ aus den einzelnen Bundle-Bestandteilen.

5. Finanzstatus & Customizing

Klar mappt deinen Bestellstatus auf vier interne Status: paid, cancelled, refunded und partially refunded.

  • Standard-Mapping: Gängige Begriffe wie open, pending, paid oder cancelled erkennen wir automatisch.

  • Eigene Status: Nutzt dein System eigene Begriffe? Dann kannst du in den Klar-Einstellungen eine Datenquellen-Anpassung anlegen und deine Status unseren vier Kategorien zuordnen.

6. Attribuiton & Pixel-Matching

Nutzt du den Klar Pixel? Dann muss die order_id aus den Pixel-Events exakt mit der ID aus der API übereinstimmen.

Klar versucht den Match über diese Felder:

  1. ID

  2. Order Number

  3. Order Name

Falls das nicht klappt, nutze das Feld optionalIdentifiers.googleAnalyticsTransactionID, um die Zuordnung sicherzustellen.

7. Häufige Stolperfallen

Problem

Auswirkung

Lösung

Gesamt- statt Einzelpreise

Die Zahlen im Dashboard werden völlig falsch berechnet.

Sende Steuern/Rabatte immer pro Stück, nicht für die ganze Position.

ID-Mismatch

Das Marketing-Attribution-System bricht ab.

API-order_id und Pixel-ID müssen identisch sein.

Bundle-Parent-Daten

Umsatz wird evtl. doppelt oder gar nicht gezählt.

Achte darauf, dass die Bundle-Komponenten die korrekten Preise enthalten.

Batch-Limits

Requests werden abgelehnt.

Max. 1.000 Objekte pro POST-Request senden.

Status-Mapping

Bestellungen landen in der falschen Kategorie.

Nutze Datenquellen-Anpassungen für eigene Status-Strings.

Noch Fragen? Schau dir die Objekt-Schemas für eine detaillierte Feld-Übersicht an.

Hat dies deine Frage beantwortet?