API — oversikt og godkjennelse | Kuvert dokumentasjon

Base-URL

https://api.kuvert.dk

Godkjennelse

Alle kall godkjennes med en API-nøkkel i Authorization-headeren som et bearer-token.

Terminal

curl https://api.kuvert.dk/v1/api/giftcards \
  -H "Authorization: Bearer pk_live_..."

Nøkler opprettes under Innstillinger → API-nøkler. Bare eieren kan opprette og tilbakekalle dem. Det finnes to prefikser, og du velger ikke selv mellom dem:

Prefiks	Brukes til
pk_test_	Utprøving. Rører ikke virkelige penger.
pk_live_	Drift. Arbeider på virkelige kort og saldi.

Butikken din selger i nøyaktig ett Stripe-miljø, og nøkkelen får det miljøet. En demobutikk får en pk_test_-nøkkel; en butikk som selger for virkelige penger, får en pk_live_. Nøkler fra det andre miljøet avvises på første kall — derfor er det ingen knapp som kan velge feil.

Alle kall er bundet til nøkkels bedrift. Du kan ikke se eller røre en annen bedrifts kort, og en nøkkel virker bare mens bedriften er aktiv — en bedrift som ennå ikke har fullført Stripe, eller som er suspendert, får 401.

Svarformat

Svar er JSON. Et gavekort ligger under nøkkelen giftCard, en liste under giftCards.

Feil

En feil har alltid samme form: et objekt med ett felt kalt error.

JSON

{ "error": "unauthorized" }

Status	error	Betyr
400	invalid_issue_request	Kroppen stemmer ikke med det utstedelse krever.
400	invalid_redeem_request	Kroppen stemmer ikke med det innløsning krever.
400	bad_request	Kaltet mangler noe grunnleggende, typisk koden i stien.
400	not_a_gift_card	Koden i stien er en billettkode (TKT-…). Den hører til innsjekking, ikke til et gavekort — svaret er 400 og ikke 404, slik at du ikke går og leter etter et kort som aldri har eksistert.
401	unauthorized	Nøkkelen mangler, er tilbakekalt, eller bedriften er ikke aktiv.
404	gift_card_not_found	Koden finnes ikke på denne bedriften.
409	idempotency_key_conflict	Nøkkelen er brukt på et ANNET kort. En gjenbrukt nøkkel gjentar bare nøyaktig det kaltet det ble brukt til — det kan aldri lykkes på et nytt kort.
409	cash_claim_cannot_be_denied	noCashClaim kan ikke settes på et SOLGT kort. Et kort kunden har betalt for, bærer retten til å få restbeløpet utbetalt kontant, og den rett kan et flagg ikke fjerne — utsted som b2b eller comp.
404	merchant_not_found	Nøkkelen er gyldig, men bedriften bak den finnes ikke lenger. Sjeldent, og ikke noe en klient kan rette — kontakt oss.
404	order_not_found	Gjenfs fant kortet, men ikke ordren det kom fra. Et kort utstedt i hånden har ingen ordre og kan derfor ikke gensendes på den måten.
409	card_has_no_delivery	Kortet har aldri vært sendt av oss — det ble utlevert over disken. Det er ingen levering å gjenta.
409	order_has_recipient_list	Ordren er adressert kort for kort, og så er det ikke én adresse på den å rette. Gjenfs det enkelte kort med recipient i stedet — det er den ene mottakeren rettelsen handler om.
422	invalid_recipient	recipient i kroppen på gjenfs er ikke en e-postadresse vi kan sende til. Utelat feltet for å sende til den adressen kortet allerede står med.
502	delivery_failed	Vi nådde vår leverandør, og den avviste forsendelsen. Kortet feiler ingenting, og ingenting er trukket — prøv igjen, eller kontroller adressen.

Innløsning har sine egne svar ovenpå — kortets tilstand, gyldigheten, forsinkelsen og saldoen. De står samlet i tabellen under Innløs på Gavekort-siden. Ett av dem går igjen: card_inactive svarer Angre en innløsning også med, men på en smalere port — det er bare et annullert eller fryst kort der, og det har sin egen tabell lenger nede.