Hinweis: Dieser Artikel wurde automatisch übersetzt. 🤖
1. Basis-URL und Versionierung
Die Basis-URL der Klar API ist https://open-api.getklar.com/ gefolgt von einer Versionszeichenfolge, 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. Header
Name | Wert |
Content-Type |
|
Authorization |
|
3. Endpunktübersicht und allgemeine Infos
Die Order API bietet die folgenden Endpunkte:
POST /<VERSION>/orders/validate
POST /<VERSION>/orders/json
GET /orders/status
Gut zu wissen: Wenn ein Feld in der API-Spezifikation als erforderlich markiert ist, muss es in der Übermittlung vorhanden sein. Wenn es nicht erforderlich ist und vorhanden ist, muss es einen gültigen Wert haben, z. B. kann cancelledAt nicht mit dem Wert 0 übermittelt werden und muss auf undefined gesetzt werden.
POST /<VERSION>/orders/validate
Mit diesem Endpunkt kannst du deine Bestell-Payload auf Gültigkeit prüfen. Wir prüfen derzeit auf Verstöße gegen die Spezifikation wie erforderliche Felder und Attributtypen, z. B. number, string usw. In Zukunft werden wir auch Logikverletzungsfehler als Ergebnis einer fehlerhaften Payload zurückgeben. Der Anfragetext sollte ein Array von bis zu 1000 JSON-Objekten vom Typ Order enthalten.
Gibt einen HTTP-Code 201 und den folgenden Antworttext zurück:
{
"status": "VALID"
}
Gibt einen HTTP-Code 400 und eine Validator-Nachricht zurück, wenn ein Fehler aufgetreten ist:
[{
// ...
"children": [
{
"target": {
"descriptor": "",
"taxAmount": 0.98,
"taxRate": "17%",
"title": "string"
},
"value": "17%",
"property": "taxRate",
"children": [],
"constraints": {
"isNumber": "taxRate muss eine Zahl sein, die den angegebenen Einschränkungen entspricht"
}
}
]
// ...
}]
Gut zu wissen: Beim Übermitteln großer Bestellchargen kann es hilfreich sein, leicht identifizieren zu können, welche Bestellung einen Validierungsfehler ausgelöst hat. Du kannst dies erreichen, indem du den Anfrageparameter failedOrderIds=true zu deiner Anfrage hinzufügst. Die URL sieht dann wie folgt aus: https://open-api.getklar.com/12.2022/orders/validate?failedOrderIds=true
Die zurückgegebene Payload sieht dann ungefähr so aus:
"status": "INVALID", "orderIds": [ "16933333360", "16933333361", "18933333360" ], "errors": [ "orders.0.createdAt: (1.6972342323232322e+22) muss ein Unix-Zeitstempel sein! (isTimestamp)", "orders.0.shipping.taxes.0.taxRate: (-24) muss 0 oder positiv sein! (isPositive)", "orders.1.createdAt: (1.6972342323232322e+22) muss ein Unix-Zeitstempel sein! (isTimestamp)", "orders.2.createdAt: (1.6972342323232322e+22) muss ein Unix-Zeitstempel sein! (isTimestamp)" ]
POST /<VERSION>/orders/json
Mit diesem Endpunkt kannst du deine Bestelldaten bei Klar hochladen.
Der Anfragetext 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 muss ein String sein",
"value": 1111
}
]
}
Mit diesem Endpunkt kannst du eine Bestellung sowohl erstellen als auch aktualisieren. Da die id eindeutig sein muss, übermittle einfach dieselbe Bestellung mit korrigierten oder aktualisierten Feldern erneut, z. B. wenn sich der Bestellstatus von pending zu paid ändert.
Wenn du eine Bestellung löschen möchtest, d. h. sie soll nicht von Klar verarbeitet werden, kannst du den Feld financialStatus einfach auf 'cancelled' setzen.
Wir bieten derzeit keinen Endpunkt zum vollständigen Löschen hochgeladener Daten an. Wenn du eine Übermittlung löschen möchtest, schreibe bitte unserem Kundensupport über unseren In-App-Chat oder per [email protected].
Du kannst auch den Anfrageparameter failedOrderIds=true zu deiner Anfrage hinzufügen, um die orderIds von Bestellungen zu erhalten, die wir im Rückgabeobjekt nicht validieren konnten. Die URL sieht dann wie folgt aus: https://open-api.getklar.com/12.2022/orders/json?failedOrderIds=true Die zurückgegebene Payload sieht genau so aus wie die für die Validierung zurückgegebene.
GET /orders/status
Mit diesem Endpunkt kannst du einige Metriken abfragen, wie z. B. die Gesamtzahl der übermittelten Bestellungen total (nur Bestellungen, die am oder nach dem 14.03.2023 übermittelt wurden), die Anzahl der Bestellungen in der letzten Übermittlung lastBatchCount und die Zeit der letzten erfolgreichen/fehlgeschlagenen Übermittlung lastSuccess / lastFailure.
Gibt einen HTTP-Statuscode 200 und einen Antworttext zurück:
{
"total": "2",
"lastBatchCount": "1",
"lastSuccess": "2023-03-14T09:06:42.281Z",
"lastFailure": "2023-03-14T09:06:50.981Z"
}