Skriv trygt til API-et og håndter feilsvar
Forstå Idempotency-Key, ventende godkjenning og hva systemet skal gjøre etter en feil.
Oppdatert 15. november 2026
Opprett utkast og bruk stabile handlingsnøkler
POST /api/v1/drafts oppretter et utkast for én kunde og periode. Et bilagspunkt har title og en forklarende note. Hent kunde- og periode-ID-er fra lesekallene; ikke send kundens navn der API-et krever en ID. externalRef kan knytte utkastet og punktene til referanser i ditt eget system.
Alle POST-kall krever en Idempotency-Key-header. Bruk en ny UUID for hver ny handling, og behold samme nøkkel, sti og innhold hvis du må prøve akkurat den handlingen på nytt. Nøkkelen skal ikke ligge i JSON-innholdet.
Et gjentatt ferdig kall returnerer det lagrede resultatet. Endrede argumenter med samme nøkkel avvises. Et nytt nøkkelnummer betyr en ny handling og er derfor ikke en trygg måte å komme forbi et usikkert resultat på.
HTTP 202 betyr at handlingen venter
POST /api/v1/drafts/{draftId}/send ber om å sende utkastet. HTTP 202 med data.status lik awaiting_approval betyr at en person må godkjenne det under Venter på godkjenning i BilagPilot. Det betyr ikke at kunden har mottatt noe.
Gjenta samme kall med samme Idempotency-Key for å hente status. Du får fortsatt 202 mens det venter, resultatet når det er utført, eller et feilsvar hvis det ble avvist eller ikke lenger kan utføres. Hvis innholdet i utkastet er endret etter at det ble lagt til godkjenning, kan det ikke sendes på den gamle godkjenningen.
Godkjenning, utsending og levering til regnskapssystemet er ulike hendelser. Les status og historikk for handlingen du faktisk trenger bekreftet.
Bruk feilkoden og requestId
- 401: kontroller at riktig nøkkel sendes med Bearer, og at den ikke har utløpt eller blitt trukket tilbake.
- 403: kontroller byråets serverbryter, handlingens tillatelse, kundeutvalget og IP-adressene. Gi ikke automatisk mer tilgang for å få kallet gjennom.
- 400 eller 422: rett argumentene etter error.code og error.message før du prøver igjen. Manglende Idempotency-Key må legges til som en header.
- 429 RATE_LIMITED: vent som angitt i Retry-After. SEND_LIMIT_REACHED gjelder den daglige kontaktgrensen og nullstilles neste dag etter Oslo-tid.
- TIMEOUT, IDEMPOTENCY_CONFLICT eller UNKNOWN_OUTCOME: et skrivekall kan fremdeles være under behandling. Behold samme handlingsnøkkel og kontroller utsendingen og leveringshistorikken før en ny handling vurderes.
Ved kontakt med support: oppgi feilkode, requestId, tidspunkt og hvilken API-sti du brukte. Utelat API-nøkler, filer og kundeopplysninger.
Fant du ikke svaret?
Kontakt support, så hjelper vi deg videre.