POS-API · Konventioner
Beløb, fejl, kvoter og idempotens
Det, der gælder for alle kald: penge i øre, tid i UTC, samme fejlformat overalt, en kvote pr. nøgle og idempotente genforsøg, så en kasse med ustabilt netværk aldrig giver point to gange.
Konventioner
Beløb, tid og headers
Penge er øre
Alle beløb er heltal i øre og hedder noget med _minor: 159,50 kr er 15950. Valutaen er altid "DKK". Brug aldrig kommatal til penge — det er sådan en øres afvigelse pr. bon opstår. Ét point er én krone (point_value_minor: 100).
Tid
Tidsstempler er ISO 8601 med tidszone, normalt i UTC (2026-09-24T10:05:00.000Z). Restauranten arbejder i Europe/Copenhagen, så husk sommertid, når I viser tider. Undtagelsen er pickup_time, som er den tekst restauranten har aftalt med kunden, fx "18:30".
Headers på hvert svar
| Header | Betydning |
|---|---|
X-Request-Id | Kaldets id i vores logs. Log den — det er den, vi beder om i en supportsag. |
X-WalletPlus-Api-Version | Altid v1 på dette API. |
X-RateLimit-Limit | Kald pr. minut på nøglen. |
X-RateLimit-Remaining | Hvor mange kald der er tilbage i dette minut. |
X-RateLimit-Reset | Sekunder til tælleren nulstilles. |
Retry-After | Kun ved 429: sekunder I skal vente. |
ETag | Kun på /menu: menukortets fingeraftryk. |
Fejl
Alle fejl har samme form. Kod mod code, ikke mod message — teksten er skrevet til mennesker og kan ændre sig. Send request_id med, når I skriver til os.
{
"error": {
"code": "missing_scope",
"message": "Kaldet kræver loyalty:write, som ikke er givet.",
"request_id": "9f1c0f6e-2b3a-44d1-9e0e-1c2f8a7b5d33"
}
}| Kode | Status | Hvad I gør |
|---|---|---|
unauthorized | 401 | Der mangler en Authorization-header. Send Authorization: Bearer <nøgle>. |
invalid_key | 401 | Ukendt nøgle eller forkert format — eller en testnøgle brugt mod produktion (og omvendt). |
key_revoked | 401 | Nøglen er tilbagekaldt. Restaurantens egen udvikler opretter en ny under API-nøgler i WalletPlus; en leverandør skriver til os. |
partner_suspended | 403 | Adgangen er sat på pause af WalletPlus. Kontakt os. |
forbidden | 403 | Kaldet er ikke tilladt for denne nøgle. |
no_grant | 403 | Virksomheden har ikke (eller ikke længere) givet systemet adgang — eller company_id er forkert. |
missing_scope | 403 | Kaldet kræver en adgang, nøglen ikke har. Beskeden nævner hvilken. |
not_found | 404 | Findes ikke i virksomheden — fx et forkert ordre-id eller en ukendt kunde. |
invalid_request | 400 | Valideringsfejl. fields siger hvilke felter. |
invalid_cursor | 400 | Cursoren kan ikke læses. Start forfra med updated_since. |
idempotency_key_required | 400 | Skrivende kald mangler headeren Idempotency-Key. |
idempotency_key_reused | 422 | Samme Idempotency-Key er brugt til en anden forespørgsel. Brug en ny pr. handling. |
conflict | 409 | Fx for få point, kunden er ikke medlem, eller et identisk kald behandles lige nu. Kan prøves igen. |
rate_limited | 429 | For mange kald — eller for mange forkerte nøgler fra samme IP. Vent det antal sekunder, Retry-After siger. |
internal_error | 500 | Vores fejl. Prøv igen med backoff; send request_id til os, hvis det bliver ved. |
Kvoter
600 kald i minuttet pr. nøgle. Rammer I loftet, svarer vi 429 rate_limited med Retry-After i sekunder. Hvert svar fortæller med X-RateLimit-Remaining, hvor meget der er tilbage.
Også afviste kald tæller, når nøglen er genkendt. Og mange kald med en ukendt eller forkert nøgle fra samme IP spærrer IP'en et kort stykke tid — også for gyldige nøgler.
Hent ordrer med cursoren hvert 10.–30. sekund — det er rigeligt til en kasse og bruger en brøkdel af kvoten. Menukortet ændrer sig sjældent: send ETag'en med, så koster et uændret kort ingenting.
Kvoten gælder nøglen, ikke den enkelte restaurant. Har I mange restauranter på samme nøgle, så overvej webhooks frem for at polle hver enkelt, og skriv til os, hvis kvoten skal hæves.
Idempotens
Alle skrivende kald kræver headeren Idempotency-Key med en værdi, der er unik pr. handling. En kasse med ustabilt netværk sender et salg, får timeout og sender igen uden at vide, om det første kom frem — uden nøglen ville kunden få point to gange.
| Situation | Svar |
|---|---|
| Samme nøgle, samme body | Det oprindelige svar, uændret — også statuskoden. |
| Samme nøgle, anden body | 422 idempotency_key_reused. Brug en ny nøgle pr. handling. |
| Samme nøgle, mens første kald kører | 409 conflict. Prøv igen om et øjeblik. |
Der er et net under
external_id på et salg og reference på en indløsning. Send altid samme reference for samme bon.