Spring til indholdet

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

HeaderBetydning
X-Request-IdKaldets id i vores logs. Log den — det er den, vi beder om i en supportsag.
X-WalletPlus-Api-VersionAltid v1 på dette API.
X-RateLimit-LimitKald pr. minut på nøglen.
X-RateLimit-RemainingHvor mange kald der er tilbage i dette minut.
X-RateLimit-ResetSekunder til tælleren nulstilles.
Retry-AfterKun ved 429: sekunder I skal vente.
ETagKun 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.

403
{
  "error": {
    "code": "missing_scope",
    "message": "Kaldet kræver loyalty:write, som ikke er givet.",
    "request_id": "9f1c0f6e-2b3a-44d1-9e0e-1c2f8a7b5d33"
  }
}
KodeStatusHvad I gør
unauthorized401Der mangler en Authorization-header. Send Authorization: Bearer <nøgle>.
invalid_key401Ukendt nøgle eller forkert format — eller en testnøgle brugt mod produktion (og omvendt).
key_revoked401Nøglen er tilbagekaldt. Restaurantens egen udvikler opretter en ny under API-nøgler i WalletPlus; en leverandør skriver til os.
partner_suspended403Adgangen er sat på pause af WalletPlus. Kontakt os.
forbidden403Kaldet er ikke tilladt for denne nøgle.
no_grant403Virksomheden har ikke (eller ikke længere) givet systemet adgang — eller company_id er forkert.
missing_scope403Kaldet kræver en adgang, nøglen ikke har. Beskeden nævner hvilken.
not_found404Findes ikke i virksomheden — fx et forkert ordre-id eller en ukendt kunde.
invalid_request400Valideringsfejl. fields siger hvilke felter.
invalid_cursor400Cursoren kan ikke læses. Start forfra med updated_since.
idempotency_key_required400Skrivende kald mangler headeren Idempotency-Key.
idempotency_key_reused422Samme Idempotency-Key er brugt til en anden forespørgsel. Brug en ny pr. handling.
conflict409Fx for få point, kunden er ikke medlem, eller et identisk kald behandles lige nu. Kan prøves igen.
rate_limited429For mange kald — eller for mange forkerte nøgler fra samme IP. Vent det antal sekunder, Retry-After siger.
internal_error500Vores 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.

SituationSvar
Samme nøgle, samme bodyDet oprindelige svar, uændret — også statuskoden.
Samme nøgle, anden body422 idempotency_key_reused. Brug en ny nøgle pr. handling.
Samme nøgle, mens første kald kører409 conflict. Prøv igen om et øjeblik.

Der er et net under

Kommer gentagelsen med en ny idempotensnøgle — fx efter en genstart — fanger vi den stadig på jeres egen reference: external_id på et salg og reference på en indløsning. Send altid samme reference for samme bon.