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. Headers
Name | Value |
Content-Type |
|
Authorization |
|
3. Endpunkt-Übersicht und allgemeine Infos
Die Order-API stellt die folgenden Endpunkte bereit:
POST /<VERSION>/orders/validate
POST /<VERSION>/orders/json
GET /orders/status
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.
POST /<VERSION>/orders/validate
Über diesen Endpunkt kannst du dein Order-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 Array von bis zu 1000 JSON-Objekten vom Typ Order enthalten.
Gibt einen HTTP-Code 201 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": {
"descriptor": "",
"taxAmount": 0.98,
"taxRate": "17%",
"title": "string"
},
"value": "17%",
"property": "taxRate",
"children": [],
"constraints": {
"isNumber": "taxRate must be a number conforming to the specified constraints"
}
}
]
// ...
}]
Gut zu wissen: Beim Übermitteln großer Order-Batches kann es hilfreich sein, einfach zu erkennen, welche Bestellung einen Validierungsfehler ausgelöst hat. Das erreichst du, indem du den Request-Parameter failedOrderIds=true zu deiner Anfrage hinzufügst. Die URL sieht dann so aus: https://open-api.getklar.com/12.2022/orders/validate?failedOrderIds=true
Das zurückgegebene Payload sieht in etwa so aus:
"status": "INVALID",
"orderIds": [
"16933333360",
"16933333361",
"18933333360"
],
"errors": [
"orders.0.createdAt: (1.6972342323232322e+22) has to be a unix timestamp! (isTimestamp)",
"orders.0.shipping.taxes.0.taxRate: (-24) has to be 0 or positive! (isPositive)",
"orders.1.createdAt: (1.6972342323232322e+22) has to be a unix timestamp! (isTimestamp)",
"orders.2.createdAt: (1.6972342323232322e+22) has to be a unix timestamp! (isTimestamp)"
]
}
POST /<VERSION>/orders/json
Über diesen Endpunkt kannst du deine Order-Daten zu Klar hochladen.
Der Request-Body sollte ein Array von bis zu 1000 JSON-Objekten vom Typ Order enthalten.
Die Antwort für eine erfolgreiche Übermittlung ist das folgende JSON-Objekt mit einem HTTP-Code 201.
{ "status": "VALID" }
Die Antwort für eine ungültige Übermittlung ist das folgende JSON-Objekt mit einem HTTP-Code 400.
{
"status": "INVALID",
"errors": [
{
"id": 1111,
"key": "0.orderId",
"message": "orderId must be a string",
"value": 1111
}
]
}
Mit diesem Endpunkt kannst du eine Bestellung sowohl erstellen als auch aktualisieren. Da die id eindeutig sein muss, übermittelst du einfach dieselbe Bestellung erneut mit korrigierten oder aktualisierten Feldern — z.B. wenn sich der Bestellstatus von pending auf paid ändert.
Wenn du eine Bestellung „löschen" möchtest, also nicht willst, dass sie von Klar verarbeitet wird, kannst du einfach das Feld financialStatus auf 'cancelled' setzen.
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.
Du kannst außerdem den Request-Parameter failedOrderIds=true zu deiner Anfrage hinzufügen, um im Rückgabeobjekt die orderIds der Bestellungen zu erhalten, die wir nicht validieren konnten. Die URL sieht dann so aus: https://open-api.getklar.com/12.2022/orders/json?failedOrderIds=true Das zurückgegebene Payload sieht genauso aus wie das bei der Validierung zurückgegebene.
GET /orders/status
Über diesen Endpunkt kannst du einige Kennzahlen abfragen, z.B. die Gesamtzahl der übermittelten Bestellungen total (zählt nur Bestellungen, die am oder nach dem 14.03.2023 übermittelt wurden), die Anzahl der in der letzten Übermittlung gesendeten Bestellungen lastBatchCount sowie den Zeitpunkt der letzten erfolgreichen / fehlgeschlagenen Übermittlung lastSuccess / lastFailure.
Gibt einen HTTP-Statuscode 200 und einen Response-Body zurück:
{
"total": "2",
"lastBatchCount": "1",
"lastSuccess": "2023-03-14T09:06:42.281Z",
"lastFailure": "2023-03-14T09:06:50.981Z"
}