API — Übersicht und Authentifizierung

Basis-URL

https://api.kuvert.dk

Authentifizierung

Alle Aufrufe werden mit einem API-Schlüssel im Authorization-Header als Bearer-Token authentifiziert.

Terminal

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 erhält diese Umgebung. Ein Demo-Shop erhält einen pk_test_-Schlüssel; ein Shop, der echtes Geld verkauft, erhält einen pk_live_. Schlüssel aus der anderen Umgebung werden beim ersten Aufruf abgelehnt — deshalb gibt es keinen Button, der falsch wählen kann.

Alle Aufrufe sind an das Unternehmen des Schlüssels gebunden. Sie können die Karten eines anderen Unternehmens nicht sehen oder berühren, und ein Schlüssel funktioniert nur, während das Unternehmen aktiv ist — ein Unternehmen, das Stripe noch nicht abgeschlossen hat oder das ausgesetzt ist, erhält 401.

Antwortformat

Antworten sind JSON. Ein Gutschein liegt unter dem Schlüssel giftCard, eine Liste unter giftCards.

Fehler

Ein Fehler hat immer dieselbe Form: ein Objekt mit einem Feld namens error.

JSON

{ "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 zur Eincheckung, nicht zu einem Gutschein — die Antwort ist 400 und nicht 404, sodass 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 auf einer ANDEREN Karte verwendet. Ein wiederverwendeter Schlüssel wiederholt nur genau den Aufruf, für den er verwendet wurde — er kann bei einer neuen Karte niemals erfolgreich sein.
409	cash_claim_cannot_be_denied	noCashClaim kann nicht auf einer VERKAUFTEN Karte gesetzt werden. Eine Karte, für die der Kunde bezahlt hat, trägt das Recht, den Restbetrag in bar ausgezahlt zu bekommen, und dieses Recht kann ein Flag nicht aufheben — geben Sie sie stattdessen als b2b oder comp aus.
404	merchant_not_found	Der Schlüssel ist gültig, aber das Unternehmen dahinter existiert nicht mehr. Selten, und nichts, das ein Client beheben kann — 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 niemals von uns versendet — sie wurde über den Tresen ausgegeben. Es gibt keine Zustellung zum Wiederholen.
409	order_has_recipient_list	Die Bestellung wird Karte für Karte adressiert, daher gibt es keine einzelne Adresse auf der Bestellung zu korrigieren. Senden Sie die einzelne Karte stattdessen mit recipient erneut — es ist der eine Empfänger, um den es bei der Korrektur geht.
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 dieser lehnte den Versand ab. Die Karte hat keinen Fehler, und nichts wurde belastet — versuchen Sie es erneut, oder überprüfen Sie die Adresse.

Die Einlösung hat zusätzlich ihre eigenen Antwortkodes — der Status der Karte, ihre Gültigkeit, Verzögerung und der Saldo. Diese sind in der Tabelle unter Einlösen auf der Seite Gutschein zusammengefasst. Einer von ihnen taucht erneut auf: card_inactive wird auch von Einlösung umkehren beantwortet, aber unter engeren Bedingungen — dort nur für stornierte oder eingefrorene Karten, und diese haben ihre eigene Tabelle weiter unten.