1. Base-URL und Versionierung
Die Base-URL der Klar-API ist https://open-api.getklar.com/ gefolgt von einem Versions-String, z.B. 12.2022.
Gut zu wissen: Eine vollständige Definition der API-Endpunkte und der verfügbaren Versionen findest du in unserer automatisch generierten API-Spezifikation.
2. Endpunkt-Übersicht und allgemeine Infos
Gut zu wissen: Wenn ein Feld in der API-Spezifikation als required markiert ist, muss es in der Übermittlung vorhanden sein. Ist es nicht required und dennoch vorhanden, muss es einen gültigen Wert haben — z.B. darf cancelledAt nicht mit dem Wert 0 übermittelt werden und muss auf undefined gesetzt sein.
Die COGS-API stellt die folgenden Endpunkte bereit:
POST /<VERSION>/cogs/validate
POST /<VERSION>/cogs/json
GET /cogs/status
POST /<VERSION>/logistics-costs/validate
Über diesen Endpunkt kannst du dein COGS-Payload auf Gültigkeit prüfen. Aktuell prüfen wir auf Verstöße gegen die Spezifikation, etwa Pflichtfelder und Attributtypen wie number, string usw. Künftig geben wir bei einem fehlerhaften Payload auch Logik-Verletzungsfehler zurück.
Der Request-Body sollte ein JSON-Objekt mit dem Key „items" enthalten, das ein Array von bis zu 1000 JSON-Objekten vom Typ COGS enthalten kann.
Gibt einen HTTP-Code 202 und den folgenden Response-Body zurück:
{
"status": "VALID"
}Gibt einen HTTP-Code 400 und eine Validator-Nachricht zurück, wenn ein Fehler auftrat:
[{
// ...
"children": [
{
"target": {
// ... COGS object
},
"value": null,
"property": "productCogs",
"children": [],
"constraints": {
"isNumber": "productCogs must be a number conforming to the specified constraints"
}
}
]
// ...
}]
POST /<VERSION>/cogs/json
Über diesen Endpunkt kannst du deine Logistikkosten-Daten zu Klar hochladen.
Der Request-Body sollte ein Array von bis zu 1000 JSON-Objekten vom Typ COGS enthalten. Die Antwort für eine erfolgreiche Übermittlung ist eine leere Antwort mit einem HTTP-Code 201.
Mit diesem Endpunkt kannst du COGS sowohl erstellen als auch aktualisieren. Übermittle einfach dieselben COGS erneut mit korrigierten oder aktualisierten Feldern — z.B. wenn sich der COGS-Betrag für ein Line Item einer Bestellung ändert.
Aktuell bieten wir keinen Endpunkt zum vollständigen Löschen hochgeladener Daten an. Wenn du eine Übermittlung löschen möchtest, wende dich bitte über den In-App-Chat oder unter [email protected] an unser Customer-Support-Team.
GET /cogs/status
Über diesen Endpunkt kannst du einige Kennzahlen abfragen, z.B. die Gesamtzahl der übermittelten Erstattungen total, die Anzahl der in der letzten Übermittlung gesendeten COGS lastBatchCount sowie den Zeitpunkt der letzten erfolgreichen / fehlgeschlagenen Übermittlung lastSuccess / lastFailure.
Gibt einen HTTP-Statuscode 200 und einen Response-Body zurück:
{
"total": "9",
"lastBatchCount": "4",
"lastSuccess": "2023-03-11T12:13:31.193Z",
"lastFailure": "2023-03-11T09:06:50.321Z"
}