https://api.kuvert.dkAlle kall godkjennes med en API-nøkkel i Authorization-headeren som et bearer-token.
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 ekte penger, får en pk_live_. Nøkler fra det andre miljøet avvises ved første kall. Derfor finnes det ingen knapp som kan velge feil.
Alle kall er bundet til nøkkelens 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.
Svar er JSON. Et gavekort ligger under nøkkelen giftCard, en liste under giftCards.
Beløp er alltid heltall i øre, og tidspunkter er ISO 8601 i UTC. Hvert svar har en x-request-id-header. Ta den med når du kontakter oss om et bestemt kall, så kan vi finne akkurat det.
Lister er ikke sidedelt: GET /v1/api/giftcards svarer med alle bedriftens kort på én gang, nyeste først.
En feil har alltid samme form: et objekt med ett felt kalt error.
{ "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, så 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 kallet den ble brukt til, og den 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, gir rett til å få restbeløpet utbetalt kontant, og den retten kan ikke et flagg fjerne. Utsted som b2b eller comp. |
| 404 | merchant_not_found | Nøkkelen er gyldig, men bedriften bak den finnes ikke lenger. Det skjer sjelden og kan ikke rettes av en klient. 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 blitt sendt av oss, for det ble utlevert over disken. Det er ingen levering å gjenta. |
| 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 leverandøren vår, og den avviste forsendelsen. Det er ingenting galt med kortet, og ingenting er trukket. Prøv igjen, eller kontroller adressen. |
| 403 | key_environment_mismatch | Nøkkelen er gyldig, men fra et annet Stripe-miljø enn det butikken din selger i, for eksempel en pk_test_ på en butikk som selger for ekte penger, eller omvendt. 403 og ikke 401: å logge inn igjen hjelper ikke, du må bruke den andre nøkkelen. |
| 404 | not_found | Stien finnes ikke. Kontroller metode og sti. En POST til en sti som bare tar GET, svarer også slik. |
| 429 | rate_limited | For mange kall for tett. Retry-After-headeren sier hvor mange sekunder det går før du kan prøve igjen. Se Grenser. |
| 500 | internal_error | En uventet feil hos oss. Ingenting i svaret avslører hvilken; send oss x-request-id-headeren, så finner vi den. |
Innløsning har i tillegg sine egne svar om 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. Der gjelder det bare et annullert eller fryst kort, og den har sin egen tabell lenger ned.
Du kan gjøre 240 kall per 60 sekunder mot /v1/api, telt i faste vinduer. Går du over, svarer vi 429 rate_limited med en Retry-After-header som sier hvor mange sekunder som er igjen av vinduet.
Var siden nyttig?