API-konvensjoner

Forespørselsformat

Hver operasjon er en RPC-lignende POST:

POST /v1/{module}/{resource}/{action}

Moduler: reference, partners, catalog, sales, purchases, ledger, bank, declarations, files, webhooks, audit. Handlinger er verb: create, get, update, delete, list, i tillegg til domenehandlinger som issue, register, match, apply-advance, generate.

Autentisering og omfang (scopes)

Authorization: Bearer <api key>. Nøkklene inneholder omfang som sjekkes per handling:

• {module}:read - hent- og listehandlinger
• {module}:write - endringer
• {module}:* eller * - jokertegn

Manglende omfang gir 403 forbidden. Manglende eller ugyldig nøkkel gir 401 unauthorized.

Listespørringer

Alle list-handlinger deler samme kontrakt:

{
  "page": 1,
  "pageSize": 50,
  "sort": [{ "field": "createdAt", "dir": "desc" }],
  "filter": [{ "field": "paymentStatus", "op": "eq", "value": "unpaid" }]
}

Filteroperatorer: eq (lik), ne (ikke lik), contains (tekstsøk som ikke skiller mellom store og små bokstaver, gjelder kun tekstfelt), gte (større enn eller lik), lte (mindre enn eller lik), in (en av en liste med opptil 500 verdier). Felt som kan sorteres og filtreres, er hvitlistet per endepunkt (se OpenAPI-spesifikasjonen); ukjente felt returnerer 400. Legg til totals: ["field", …] i forespørselen for å summere numeriske felt på tvers av alle matchende rader. Når postene har en valuta, gir totalsByCurrency de samme summene fordelt på valutakode. Svar: { rows, total, page, pageSize, totals?, totalsByCurrency? }.

Penger og datoer

Pengebeløp er desimalstrenger med opptil fire desimaler ("121.0000") og brukes aldri som flyttall (floats). Merverdiavgift beregnes per linje med avrunding til nærmeste med opprunding ved halvveis (half-up rounding). Datoer er på formatet YYYY-MM-DD, og tidsstempler følger ISO 8601 UTC.

Feil

Ett enkelt meldingsformat over alt:

{
  "error": {
    "code": "validation",
    "message": "Request validation failed",
    "requestId": "k1x…",
    "key": "request_invalid",
    "fieldErrors": { "lines.0.unitPriceExclVat": ["Invalid value"] }
  }
}

Koder: validation (400/422, og 413 hvis en opplastet fil eller forespørselstekst er for stor), unauthorized (401), payment_required (402, prøveperioden eller forhåndsbetalt saldo har utløpt; meldingen forklarer hvordan du går videre), forbidden (403), not_found (404), conflict (409), idempotency_key_reuse (422), idempotency_in_progress (409), rate_limited (429), internal (5xx). Når meldingen er en av de faste meldingene, angir key denne slik at en klient kan vise sin egen oversettelse, og params inneholder verdiene som fylles inn i den (for eksempel { "period": "2026-09" } for en låst regnskapsperiode). Inkluder requestId ved feilrapportering.

Idempotens

Legg til Idempotency-Key: <vilkårlig streng ≤255 tegn> på alle endrende kall:

• Nytt forsøk med samme nøkkel og nyttelast gir det lagrede svaret spilt av byte for byte med x-idempotent-replay: true.
• Samme nøkkel med annen nyttelast gir 422 idempotency_key_reuse.
• Samtidig duplikat mens det første kallet pågår, gir 409 idempotency_in_progress.
• Nøklene tilhører API-nøkkelen eller brukeren som sender dem, innenfor selskapskonteksten kallet utføres for, slik at to integrasjoner for ett selskap kan bruke samme nøkkel. Kall som utføres før et selskap eksisterer, samt account/*-kall, beholder nøkler per bruker, slik at gjentatte account/companies/create-kall kun oppretter ett selskap.
• Et lagret svar returneres bare etter at anroperen har bestått de samme tilgangskontrollene på nytt (omfang, rolle, selskap og faktureringsstatus). Ellers mottar kallet den gjeldende feilen.
• Nøkler utløper etter 24 timer. Feilresponsar (4xx) blir også spilt av på nytt, mens 5xx-responser ikke lagres, slik at nye forsøk kjøres på nytt.

Hastighetsbegrensninger (rate limits)

300 forespørsler per minutt per API-nøkkel (per presentert påloggingsinformasjon; uautentiserte forespørsler begrenses per IP-adresse). Ved 429 må du rette deg etter retry-after-headeren. x-ratelimit-*-headere viser status for kvoten din.

Webhooks

Hendelser skrives til en transaksjonell utboks (outbox) i samme databasetransaksjon som endringen. Et dokument som rulles tilbake, utløser aldri en hendelse, og ingen hendelser går tapt. Levering:

• POST til nettadressen din med hendelsens JSON-data
• x-nordlet-timestamp: <unix-sekunder>, tidspunktet leveringen ble signert på
• x-nordlet-signature-v2: t=<timestamp>,v1=<heksadesimal HMAC-SHA256 av "<timestamp>.<rå nyttelast>"> ved bruk av abonnementshemmeligheten din
• x-nordlet-signature: sha256=<heksadesimal HMAC-SHA256 av den rå nyttelasten>, beholdt uendret for eksisterende mottakere
• x-nordlet-delivery inneholder leverings-ID-en, som er den samme ved alle forsøk på å levere en hendelse på nytt
• Svar som ikke er i 2xx-serien, eller omdirigeringer, prøves på nytt etter 30 sekunder, 2 minutter, 10 minutter, 30 minutter, 1 time, 3 timer, 6 timer og 12 timer (totalt ca. 24 timer) før leveringen markeres som mislyktes
• Hver levering sendes av én server om gangen, slik at kjøring av flere API-instanser ikke fører til dobbeltsending

Verifiser x-nordlet-signature-v2 ved hjelp av en konstanttidssammenligning før du stoler på nyttelasten, og avvis leveringer der tidsstemplet avviker med mer enn 5 minutter fra din egen klokke. Tidsstemplet er en del av den signerte teksten, slik at en fanget opp levering ikke kan spilles av på nytt senere med et nytt tidsstempel. Lagre x-nordlet-delivery-ID-ene du har behandlet, for å ignorere duplikater innenfor det tidsvinduet. En mislykket levering kan sendes på nytt med webhooks/deliveries/redeliver.

Sporbarhet (audit)

Hver endring loggføres (actor, action, entity, diff) og kan forespørres via audit/list.

Regnskapsgarantier

• Bunader (journalposter) er alltid i balanse. Dette håndteres av en utsatt databasetrigger ved fullføringstidspunktet (commit), ikke bare i applikasjonskoden.
• Dokumentnumre har ingen hull i nummerserien per serie og år, og tildelingen er konkurransesikker (concurrency-safe).
• Låste regnskapsperioder avviser alle bokføringer som er daterte innenfor perioden (409).
• Logisk slettede dokumenter (soft-deleted) beholder sporbarhetsloggen sin. Utstedte eller registrerte dokumenter kan ikke slettes.