1. Base-URL und Versionierung
Die Base-URL der Klar-API ist https://open-api.getklar.com/ gefolgt von einem Versions-String, z.B. 04.2024.
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 Logistics-Costs-API stellt die folgenden Endpunkte bereit:
POST /<VERSION>/logistics-costs/validate
POST /<VERSION>/logistics-costs/json
GET /logistics-costs/status
POST /<VERSION>/logistics-costs/validate
Über diesen Endpunkt kannst du dein Logistics-Costs-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 LogisticsCosts 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": {
// ... LogisticsCosts object
},
"value": null,
"property": "logisticsCosts",
"children": [],
"constraints": {
"isNumber": "logisticsCosts must be a number conforming to the specified constraints"
}
}
]
// ...
}]
POST /<VERSION>/logistics-costs/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 LogisticsCosts enthalten. Die Antwort für eine erfolgreiche Übermittlung ist eine leere Antwort mit einem HTTP-Code 201.
Mit diesem Endpunkt kannst du Logistikkosten sowohl erstellen als auch aktualisieren. Übermittle einfach dieselben Logistikkosten erneut mit korrigierten oder aktualisierten Feldern — z.B. wenn sich der für eine Bestellung ausgegebene Logistikkosten-Betrag ä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 /logistics-costs/state
Über diesen Endpunkt kannst du einige Kennzahlen abfragen, z.B. die Gesamtzahl der übermittelten Erstattungen total, die Anzahl der in der letzten Übermittlung gesendeten 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"
}