Überblick
Die Klar API erlaubt dir, Bestelldaten aus jeder Quelle (z. B. eigenen E-Commerce-Engines, ERPs oder Legacy-Systemen) in das Klar-Ökosystem zu pushen. Anders als synchrone APIs nutzt Klar eine „Landing Zone"-Architektur, bei der Daten im Rohformat aufgenommen und periodisch in deine Dashboards verarbeitet werden.
Wichtig: Diese API ist zum SENDEN von Daten AN Klar gedacht, nicht zum Abrufen von Daten VON Klar.
1. Erste Schritte: Das 3-Schritt-Setup
Um mit dem Senden von Daten zu beginnen, folge diesen Schritten:
Account-Zugang: Stell sicher, dass du einen aktiven Klar-Account hast.
Credentials erzeugen: Erstelle eine Klar API Data Source in der App. Das erzeugt ein JWT (JSON Web Token), das für die Authentifizierung nötig ist.
Erster Push: Sende deine Bestelldaten per
POST-Request an die API. Du kannst pro Request bis zu 1.000 Bestellungen in einem einzigen Array von JSON-Objekten senden.
Wichtige Ressourcen:
2. Datenverarbeitung verstehen
Es ist wichtig zu verstehen, dass das System, an das du Daten sendest, nicht dasselbe System ist, das die Dashboards anzeigt.
Die Landing Zone: Deine Bestellungen werden unmittelbar nach dem Empfang im Rohformat gespeichert.
Processing Pipeline: Daten werden im Klar-Frontend erst sichtbar, nachdem die Processing Pipeline gelaufen ist. Das passiert automatisch jede Stunde.
Manuelle Trigger: Du kannst ein Update erzwingen, indem du in deinen Store Settings auf „Update Store Data" klickst. Ein Ladeindikator zeigt den Status.
Debugging: Wenn Daten falsch aussehen, nutze den Order Debugger in der Detailansicht der Data Source, um das rohe JSON zu inspizieren, das Klar empfangen hat.
3. Kern-API-Logik & Endpoints
Primärer Endpoint
Der wichtigste Endpoint ist POST /orders/json. Das ist der „Master"-Endpoint für alle Bestelldaten.
Subset-Endpoints
Klar bietet spezifische Endpoints für Refunds, COGS (Cost of Goods Sold), Logistic Costs und Transaction Costs. Diese werden genutzt, wenn deine Daten über verschiedene Systeme verteilt sind.
Beispiel: Wenn deine Bestellungen aus Shopware kommen, deine Logistikkosten aber in einem ERP verwaltet werden, nutzt du den Standard-Shopware-Connector für Bestellungen und den Logistics-API-Endpoint für die Versandkosten.
Idempotenz (Daten aktualisieren)
Die API ist idempotent. Um eine bestehende Bestellung zu aktualisieren (z. B. einen Status von „pending" zu „paid" ändern), sende das Bestellobjekt einfach erneut mit derselben ID.
Hinweis: Es gibt keine spezifischen
PATCH-,PUT- oderDELETE-Endpoints. Dieselbe ID zu senden ersetzt den vorherigen Datensatz in der Landing Zone.
4. Technische Richtlinien & Preis-Logik
Versionierung
Klar-API-URLs haben einen Versions-String als Präfix.
12.2022: Die ältere stabile Version.07.2025: Die aktuelle Version, die Unterstützung für Bundle-Produkte eingeführt hat.
Preis- und Steuerberechnungen
Das ist der häufigste Bereich für Integrationsfehler. Bitte befolge diese Regeln strikt:
Werte pro Einheit: Sowohl Discount- als auch Tax-Informationen für Line Items müssen pro einzelner Menge gesendet werden.
Klars interne Berechnung:
Gross Revenue = Quantity * Product GMVNet Value = (Quantity * Product GMV) - (Quantity * Taxes) - (Quantity * Discounts)
Prüfsummen: Die Felder
totalAmountBeforeundtotalAmountAfterTaxeswerden nur als interne Prüfsummen genutzt. Alle finalen Metriken werden aus den einzelnen Werten auf Item-Ebene berechnet.
Bundle-Produkte (v07.2025+)
Beim Senden von Bundles wird das Parent-Objekt des Bundle-Line-Items für Finanzberechnungen weitgehend ignoriert. Werte werden „bottom-up" aus den einzelnen Bundle-Bestandteilen berechnet.
5. Financial Status & Customizations
Klar mappt den Bestellstatus deines Systems auf vier interne Status: paid, cancelled, refunded und partially refunded.
Standard-Mapping: Wir mappen gängige Strings wie open, pending, paid, cancelled usw. automatisch.
Custom-Mapping: Wenn dein System eigene Status-Strings nutzt, kannst du in der Klar-UI eine Data Source Customization anwenden, um deine Custom-Werte auf unsere internen Status zu mappen.
6. Attribution & Pixel-Matching
Wenn du den Klar Pixel fürs Tracking nutzt, muss die order_id, die über die Pixel-Events gesendet wird, mit der über die API gesendeten ID übereinstimmen.
Klar versucht, Daten zu matchen anhand von:
IDOrder NumberOrder Name
Wenn diese nicht übereinstimmen, musst du das Feld optionalIdentifiers.googleAnalyticsTransactionID nutzen, um sicherzustellen, dass die Attributionsdaten korrekt mit der Bestellung verknüpft werden.
7. Häufige Fallstricke, die du vermeiden solltest
Fallstrick | Auswirkung | Lösung |
Total- vs. Unit-Pricing | Finanzdaten werden falsch multipliziert. | Sende Taxes und Discounts immer pro Einheit, nicht die Summe für das Line Item. |
ID-Mismatch | Marketing-Attribution bricht. | Stell sicher, dass die API- |
Bundle-Parent-Daten | Umsatz könnte doppelt gezählt oder verpasst werden. | Stell sicher, dass die Bundle-Bestandteile die korrekten Preis-/Steuerdaten enthalten. |
Batch-Limits | Requests werden abgelehnt. | Überschreite nie 1.000 Objekte pro POST-Request. |
Status-Mapping | Bestellungen erscheinen eventuell in der falschen Dashboard-Kategorie. | Nutze Data Source Customizations, um Nicht-Standard-Status-Strings zu mappen. |
Brauchst du mehr Details? Erkunde unsere Object Schemas für eine vollständige Feld-für-Feld-Aufschlüsselung.