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 Versionsangabe, 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 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.
Die Rückerstattungs-API bietet die folgenden Endpunkte:
POST /<VERSION>/refunds/validate
POST /<VERSION>/refunds/json
GET /refunds/status
POST /<VERSION>/refunds/validate
Mit diesem Endpunkt kannst du deine Rückerstattungs-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 Anfragekörper sollte ein Array von bis zu 1000 JSON-Objekten vom Typ Rückerstattung enthalten.
Gibt einen HTTP-Code 200 und den folgenden Antwortkörper zurück:
{ "status": "VALID" }
Gibt einen HTTP-Code 400 und eine Validator-Nachricht zurück, wenn ein Fehler aufgetreten ist:
[{
// ...
"children": [
{
"target": {
// ... Rückerstattungsobjekt
},
"value": null,
"property": "refundedQuantity",
"children": [],
"constraints": {
"isNumber": "refundedQuantity muss eine Zahl sein, die den angegebenen Einschränkungen entspricht"
}
}
]
// ...
}]
POST /<VERSION>/refunds/json
Mit diesem Endpunkt kannst du deine Rückerstattungsdaten an Klar hochladen.
Der Anfragekörper sollte ein Array von bis zu 1000 JSON-Objekten vom Typ Rückerstattung enthalten. Die Antwort auf eine erfolgreiche Übermittlung ist eine leere Antwort mit einem HTTP-Code 201.
Mit diesem Endpunkt kannst du eine Rückerstattung sowohl erstellen als auch aktualisieren. Da die id eindeutig sein muss, übermittle einfach dieselbe Rückerstattung erneut mit korrigierten oder aktualisierten Feldern, z.B. wenn sich die Menge der zurückerstatteten Artikel einer Bestellung ändert.
Wenn du die Rückerstattungen löschen möchtest, d.h. sie sollen nicht von Klar verarbeitet werden, kannst du einfach ein leeres Array für das Feld lineItems übermitteln.
Wir bieten derzeit keinen Endpunkt zum vollständigen Löschen von hochgeladenen Daten an. Wenn du eine Übermittlung löschen möchtest, schreibe bitte unserem Kundensupport über unseren In-App-Chat oder per [email protected].
GET /refunds/status
Mit diesem Endpunkt kannst du einige Metriken abfragen, wie z.B. den Gesamtbetrag der übermittelten Rückerstattungen total, die Menge der in der letzten Übermittlung enthaltenen Rückerstattungen lastBatchCount und den Zeitpunkt der letzten erfolgreichen/fehlgeschlagenen Übermittlung lastSuccess / lastFailure.
{
"total": "9",
"lastBatchCount": "4",
"lastSuccess": "2023-03-11T12:13:31.193Z",
"lastFailure": "2023-03-11T09:06:50.321Z"
}