API — översikt och autentisering

Bas-URL

https://api.kuvert.dk

Auktorisering

Alla anrop auktoriseras med en API-nyckel i Authorization-huvudet som en bearer-token.

Terminal

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

Nycklar skapas under Inställningar → API-nycklar. Bara ägaren kan skapa och återkalla dem. Det finns två prefixer, och du väljer inte själv mellan dem:

Prefix	Används för
pk_test_	Testning. Rör inte riktiga pengar.
pk_live_	Drift. Fungerar på riktiga kort och saldon.

Din butik säljer i exakt en Stripe-miljö, och nyckeln får den miljön. En demobutik får en pk_test_-nyckel; en butik som säljer för riktiga pengar får en pk_live_. Nycklar från den andra miljön avvisas på första anropet — därför finns det ingen knapp som kan välja fel.

Alla anrop är bundna till nyckelns företag. Du kan inte se eller röra ett annat företags kort, och en nyckel fungerar bara medan företaget är aktivt — ett företag som ännu inte har slutfört Stripe, eller som är suspenderat får 401.

Svarformat

Svar är JSON. Ett presentkort ligger under nyckeln giftCard, en lista under giftCards.

Fel

Ett fel har alltid samma form: ett objekt med ett fält kallat error.

JSON

{ "error": "unauthorized" }

Status	error	Betyder
400	invalid_issue_request	Kroppen matchar inte det som utfärdning kräver.
400	invalid_redeem_request	Kroppen matchar inte det som inlösen kräver.
400	bad_request	Anropet saknar något grundläggande, vanligtvis koden i vägen.
400	not_a_gift_card	Koden i vägen är en biljetkod (TKT-…). Den tillhör incheckning, inte ett presentkort — svaret är 400 och inte 404, så du inte går och letar efter ett kort som aldrig har funnits.
401	unauthorized	Nyckeln saknas, är återkallad, eller företaget är inte aktivt.
404	gift_card_not_found	Koden finns inte på detta företag.
409	idempotency_key_conflict	Nyckeln är använd på ett ANNAT kort. En återanvänd nyckel upprepar bara precis det anrop den användes för — den kan aldrig lyckas på ett nytt kort.
409	cash_claim_cannot_be_denied	noCashClaim kan inte ställas på ett SÅLT kort. Ett kort kunden har betalat för bär rätten att få återstoden utbetald kontant, och den rätten kan en flagga inte ta bort — utfärda som b2b eller comp.
404	merchant_not_found	Nyckeln är giltig, men företaget bakom den finns inte längre. Sällan, och inte något en klient kan rätta — kontakta oss.
404	order_not_found	Omskicka hittade kortet, men inte den order det kom från. Ett kort utfärdat för hand har ingen order och kan därför inte omskickas på det sättet.
409	card_has_no_delivery	Kortet har aldrig skickats av oss — det utdelades över disk. Det finns ingen leverans att upprepa.
409	order_has_recipient_list	Ordern är adresserad kort för kort, och därför finns det ingen enda adress på ordern att korrigera. Skicka om det enskilda kortet med mottagare istället — det är den ena medarbetaren ändringen handlar om.
422	invalid_recipient	recipient i body för omskicka är inte en e-postadress vi kan skicka till. Utelämna fältet för att skicka till den adress kortet redan har.
502	delivery_failed	Vi nådde vår leverantör, och den vägrade försändelsen. Kortet är inte felaktigt, och inget är debiterat — försök igen eller kontrollera adressen.

Inlösen har sina egna svar ovanpå — kortets tillstånd, giltigheten, förseningen och saldot. De står samlade i tabellen under Lös in på Presentkort-sidan. En av dem återkommer: card_inactive svarar Ångra en inlösen också med, men på en smalare port — där är det bara ett annullerat eller fryst kort, och det har sin egen tabell längre ned.