Regler

Seks regler som gjelder for alle kall. Følger du dem, kan du trygt prøve igjen, synkronisere og tåle at API-et vokser.

1. Nøkkelen i overskriften

Nøkkelen sendes i Authorization: Bearer <nøkkel>, aldri i adressen.

Authorization: Bearer vb_live_…

Se Nøkler og tilgang.

2. Idempotency-Key når du lager noe

POST /orders og POST /customers krever Idempotency-Key. Bruk en ny UUID per handling, og den samme når du prøver igjen. Samme nøkkel og samme innhold gir samme svar, aldri to ordre.

Idempotency-Key: 6f1c2e9a-0d5b-4a7e-9f31-2b8c4d7e1a90

• Nøkkelen er 8–255 synlige ASCII-tegn. En UUID passer.
• Et svar som gjentas, har overskriften Idempotent-Replayed: true, og innholdet er slik det var første gang.
• Uten nøkkelen svarer API-et 428 idempotency_key_required.
• Samme nøkkel med annet innhold gir 422 idempotency_key_reused.
• Holder den første forespørselen fortsatt på, får du 409 idempotency_in_progress med Retry-After.
• Vi husker en Idempotency-Key i 24 timer.

3. If-Match når du endrer

PATCH krever If-Match med versjonen du så ("v3"). Versjonen står i version på ordren. En gammel versjon svarer 409 stale_version: hent ordren på nytt og send med ny versjon.

If-Match: "v3"

Uten If-Match svarer API-et 428 precondition_required.

4. Send bare felt vi kjenner

Felt vi ikke kjenner i det du sender, gir 400 invalid_request med feltet i fields. Svarene kan få nye felt: les bare de du kjenner.

5. Lister og synkronisering

Lister svarer { data, nextCursor }. limit er 1–100, 25 når du ikke sender den. Send nextCursor som cursor for neste side. Er nextCursor null, har du alt.

curl "https://vbeslag.com/api/v1/orders?sort=updatedAt&updatedSince=2026-12-14T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $VBESLAG_KEY"

Synkroniser med sort=updatedAt, updatedSince og cursor:

• Ta vare på siste nextCursor, og fortsett derfra neste gang.
• Ordre som er endret de siste 2 sekundene, tas med først neste gang, så en treg lagring aldri havner bak markøren din.
• Har du allerede ordren med samme number og version, har du den nyeste.

Bedre enn å spørre ofte: bruk webhooks og GET /events.

6. v1 endres ikke uten varsel

v1 endres ikke uten varsel. Nye felt, operasjoner og hendelser kan komme; noe som fjernes eller endres, kommer først i v2. v1 lever i minst tolv måneder etter at v2 kommer.