https://api.kuvert.dkAlle Aufrufe werden mit einem API-Schlüssel im Authorization-Header als Bearer-Token authentifiziert.
curl https://api.kuvert.dk/v1/api/giftcards \
-H "Authorization: Bearer pk_live_..."Schlüssel werden unter Einstellungen → API-Schlüssel erstellt. Nur der Eigentümer kann sie erstellen und widerrufen. Es gibt zwei Präfixe, und Sie wählen nicht zwischen ihnen:
| Präfix | Wird verwendet für |
|---|---|
pk_test_ | Testen. Berührt kein echtes Geld. |
pk_live_ | Produktion. Arbeitet mit echten Karten und Salden. |
Ihr Shop verkauft in genau einer Stripe-Umgebung, und der Schlüssel gehört zu dieser Umgebung. Ein Demo-Shop erhält einen pk_test_-Schlüssel; ein Shop, der für echtes Geld verkauft, erhält einen pk_live_. Schlüssel aus der anderen Umgebung werden beim ersten Aufruf abgewiesen. Deshalb gibt es keinen Button, bei dem man falsch wählen kann.
Alle Aufrufe sind an das Unternehmen des Schlüssels gebunden. Sie können die Gutscheine eines anderen Unternehmens weder sehen noch verändern, und ein Schlüssel funktioniert nur, solange das Unternehmen aktiv ist. Ein Unternehmen, das Stripe noch nicht abgeschlossen hat oder gesperrt ist, erhält 401.
Antworten sind JSON. Ein Gutschein liegt unter dem Schlüssel giftCard, eine Liste unter giftCards.
Beträge sind immer Ganzzahlen in Øre, und Zeitpunkte sind ISO 8601 in UTC. Jede Antwort trägt einen x-request-id-Header. Geben Sie ihn an, wenn Sie uns wegen eines bestimmten Aufrufs kontaktieren, dann finden wir genau diesen.
Listen sind nicht paginiert: GET /v1/api/giftcards antwortet mit allen Karten des Unternehmens auf einmal, die neueste zuerst.
Ein Fehler hat immer dieselbe Form: ein Objekt mit einem Feld namens error.
{ "error": "unauthorized" }| Status | error | Bedeutet |
|---|---|---|
| 400 | invalid_issue_request | Der Textteil entspricht nicht dem, was die Ausstellung erfordert. |
| 400 | invalid_redeem_request | Der Textteil entspricht nicht dem, was die Einlösung erfordert. |
| 400 | bad_request | Der Aufruf fehlt etwas Grundlegendes, typischerweise der Code im Pfad. |
| 400 | not_a_gift_card | Der Code im Pfad ist ein Ticketcode (TKT-…). Er gehört zum Check-in, nicht zu einem Gutschein. Die Antwort ist 400 und nicht 404, damit Sie nicht nach einer Karte suchen, die es nie gab. |
| 401 | unauthorized | Der Schlüssel fehlt, wurde widerrufen, oder das Unternehmen ist nicht aktiv. |
| 404 | gift_card_not_found | Der Code existiert nicht auf diesem Unternehmen. |
| 409 | idempotency_key_conflict | Der Schlüssel wurde für eine ANDERE Karte verwendet. Ein wiederverwendeter Schlüssel wiederholt nur genau den Aufruf, für den er verwendet wurde, und kann bei einer neuen Karte nie erfolgreich sein. |
| 409 | cash_claim_cannot_be_denied | noCashClaim kann nicht bei einer VERKAUFTEN Karte gesetzt werden. Eine Karte, die der Kunde bezahlt hat, trägt das Recht, sich das Restguthaben bar auszahlen zu lassen, und dieses Recht kann ein Flag nicht entfernen. Stellen Sie sie als b2b oder comp aus. |
| 404 | merchant_not_found | Der Schlüssel ist gültig, aber das Unternehmen dahinter existiert nicht mehr. Das kommt selten vor und kann von keinem Client behoben werden. Kontaktieren Sie uns. |
| 404 | order_not_found | Resend hat die Karte gefunden, aber nicht die Bestellung, aus der sie stammt. Eine manuell ausgegebene Karte hat keine Bestellung und kann daher nicht auf diese Weise erneut gesendet werden. |
| 409 | card_has_no_delivery | Die Karte wurde nie von uns versendet, denn sie wurde an der Kasse ausgehändigt. Es gibt keine Zustellung, die wiederholt werden könnte. |
| 422 | invalid_recipient | recipient im Body von Resend ist keine E-Mail-Adresse, an die wir senden können. Lassen Sie das Feld weg, um an die Adresse zu senden, die die Karte bereits hat. |
| 502 | delivery_failed | Wir haben unseren Anbieter erreicht, und er hat den Versand abgelehnt. Mit der Karte ist alles in Ordnung, und es wurde nichts abgezogen. Versuchen Sie es erneut oder prüfen Sie die Adresse. |
| 403 | key_environment_mismatch | Der Schlüssel ist gültig, stammt aber aus der anderen Stripe-Umgebung als der, in der Ihr Shop verkauft, etwa ein pk_test_ bei einem Shop, der für echtes Geld verkauft, oder umgekehrt. 403 und nicht 401: Erneutes Anmelden hilft nicht, Sie brauchen den anderen Schlüssel. |
| 404 | not_found | Der Pfad existiert nicht. Prüfen Sie Methode und Pfad. Ein POST an einen Pfad, der nur GET annimmt, erhält ebenfalls diese Antwort. |
| 429 | rate_limited | Zu viele Aufrufe in zu kurzer Zeit. Der Retry-After-Header sagt, wie viele Sekunden vergehen müssen, bevor Sie es wieder dürfen. Siehe Grenzen. |
| 500 | internal_error | Ein unerwarteter Fehler bei uns. Die Antwort verrät nicht, welcher; senden Sie uns den x-request-id-Header, dann finden wir ihn. |
Die Einlösung hat zusätzlich eigene Antworten zum Zustand der Karte, zur Gültigkeit, zur Verzögerung und zum Guthaben. Sie stehen gesammelt in der Tabelle unter Einlösen auf der Seite Gutscheine. Eine davon kommt noch einmal vor: card_inactive gibt auch Einlösung rückgängig machen zurück, aber unter engeren Bedingungen. Dort betrifft sie nur eine stornierte oder eingefrorene Karte und hat eine eigene Tabelle weiter unten.
Sie können 240 Aufrufe pro 60 Sekunden an /v1/api senden, gezählt in festen Zeitfenstern. Überschreiten Sie das, antworten wir 429 rate_limited mit einem Retry-After-Header, der angibt, wie viele Sekunden vom Fenster noch übrig sind.
War diese Seite hilfreich?