Integrer FakturaAPI

Base URL og autentisering

Alle private endepunkter bruker en kontoavgrenset bearer-token. Nøkler for sandkasse og produksjon kan ikke blandes.

Authorization: Bearer fakturaapi_sandbox_…
Content-Type: application/json

1. Sjekk mottakeren

Et oppslag validerer organisasjonsnummeret og kontrollerer støtte for fakturatypen FakturaAPI sender.

curl https://HOST/v1/recipients/987654325 \
  -H 'Authorization: Bearer fakturaapi_sandbox_…'

2. Opprett testavsender

Opprett avsenderen én gang og bruk den returnerte organisasjons-ID-en på fakturaer.

curl https://HOST/v1/organizations \
  -H 'Authorization: Bearer fakturaapi_sandbox_…' \
  -H 'Content-Type: application/json' \
  --data '{"orgnr":"923456783"}'

3. Send en faktura

Idempotency-Key er påkrevd. Et nytt forsøk med samme innhold returnerer samme faktura. Samme nøkkel med annet innhold avvises.

curl https://HOST/v1/invoices \
  -H 'Authorization: Bearer fakturaapi_sandbox_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: invoice-1042' \
  --data '{
    "sender": "ORG_ID",
    "recipient": "987654325",
    "number": "1042",
    "date": "2026-08-10",
    "due_date": "2026-08-24",
    "buyer_reference": "Andreas Flakstad",
    "lines": [{
      "description": "Konsulentarbeid",
      "quantity": 4,
      "unit": "hour",
      "unit_price": 1250,
      "vat": 25
    }]
  }'

4. Les status og originaldokument

GET /v1/invoices/{id}
GET /v1/invoices/{id}/original

Fakturaressursen inneholder beregnede linjer, MVA-grunnlag, summer og leveringsstatus. Original-endepunktet returnerer nøyaktig UBL/EHF som ble validert og lagret.

Feil og nye forsøk

Feil har en fast kode, en forklaring og en forespørsels-ID som kan brukes ved feilsøking. Feltfeil kan i tillegg inneholde detaljer.

{
  "error": {
    "code": "recipient_not_ehf_capable",
    "message": "Recipient cannot receive the supported invoice type."
  },
  "request_id": "req_…"
}

Rett 4xx-feil før du prøver igjen. Ved 429 følger du Retry-After. Ved midlertidige 5xx-feil bruker du samme Idempotency-Key og uendret innhold.

Gratis EHF-validering

Valider et eksisterende UBL-dokument uten API-nøkkel. Dokumentet lagres ikke, og vanlige regelbrudd får norsk forklaring og konkrete rettesteg.

curl --fail-with-body https://HOST/v1/tools/ehf-validation \
  -H 'Content-Type: application/xml' \
  --data-binary @invoice.xml

Webhooks

Opprett et HTTPS-endepunkt med POST /v1/webhook-endpoints. Hemmeligheten vises én gang. Kontroller HMAC-SHA256 over tidsstempel, punktum og de eksakte innholdsbytene før JSON tolkes.

X-FakturaAPI-Timestamp: 1786381200
X-FakturaAPI-Signature: t=1786381200,v1=<hex digest>

HMAC_SHA256(secret, timestamp + '.' + rawBody)

De offentlige hendelsene er invoice.delivered og invoice.failed. Ny utsending av en webhook sender samme hendelse uten å sende fakturaen på nytt.

Endepunkter