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 Refunds-API stellt die folgenden Endpunkte bereit:
POST /<VERSION>/refunds/validate
POST /<VERSION>/refunds/json
GET /refunds/status
POST /<VERSION>/refunds/validate
Über diesen Endpunkt kannst du dein Refunds-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 Refund enthalten.
Gibt einen HTTP-Code 200 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": {
// ... refund object
},
"value": null,
"property": "refundedQuantity",
"children": [],
"constraints": {
"isNumber": "refundedQuantity must be a number conforming to the specified constraints"
}
}
]
// ...
}]
POST /<VERSION>/refunds/json
Über diesen Endpunkt kannst du deine Refunds-Daten zu Klar hochladen.
Der Request-Body sollte ein Array von bis zu 1000 JSON-Objekten vom Typ Refund enthalten. Die Antwort für eine erfolgreiche Übermittlung ist eine leere Antwort mit einem HTTP-Code 201.
Mit diesem Endpunkt kannst du eine Erstattung sowohl erstellen als auch aktualisieren. Da die id eindeutig sein muss, übermittelst du einfach dieselbe Erstattung erneut mit korrigierten oder aktualisierten Feldern — z.B. wenn sich die Menge der erstatteten lineItems einer Bestellung ändert.
Wenn du die Erstattungen „löschen" möchtest, also nicht willst, dass sie von Klar verarbeitet werden, kannst du einfach ein leeres Array für das Feld lineItems übermitteln.
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 /refunds/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 Erstattungen 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"
}