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

Den maskinlesbare kontrakten er tilgjengelig som OpenAPI 3.1 JSON.

1. Sjekk mottakeren

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

curl https://fakturaapi.no/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://fakturaapi.no/v1/organizations \
  -H 'Authorization: Bearer fakturaapi_sandbox_…' \
  -H 'Content-Type: application/json' \
  --data '{"organization_number":"923456783"}'

3. Send en faktura

Forespørselen bruker fakturanummer, datoer, referanse, fakturalinjer, MVA og valgfri KID. Merknad, leveringsdato, fakturaperiode, prosjekt- og kontraktsreferanse kan legges til med de samme vanlige fakturabegrepene. Idempotency-Key er påkrevd. Et nytt forsøk med samme innhold returnerer samme faktura. Samme nøkkel med annet innhold avvises.

curl https://fakturaapi.no/v1/invoices \
  -H 'Authorization: Bearer fakturaapi_sandbox_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: invoice-1042' \
  --data '{
    "sender_organization_id": "ORG_ID",
    "recipient_organization_number": "987654325",
    "number": "1042",
    "date": "2026-08-10",
    "due_date": "2026-08-24",
    "references": {"buyer": "Andreas Flakstad"},
    "kid": "12345678903",
    "lines": [{
      "description": "Konsulentarbeid",
      "quantity": 4,
      "unit": "hour",
      "unit_price": 1250,
      "vat_rate": 25
    }]
  }'

4. Legg ved dokumentasjon

Last opp vedlegget som rå fil én gang. Bruk vedleggs-ID-en i attachment_ids på fakturaen eller kreditnotaen. Filen bygges inn i EHF-dokumentet.

curl https://fakturaapi.no/v1/attachments \
  -H 'Authorization: Bearer fakturaapi_sandbox_…' \
  -H 'Idempotency-Key: attachment-1042-report' \
  -H 'Content-Type: application/pdf' \
  -H 'X-FakturaAPI-Filename: rapport.pdf' \
  --data-binary @rapport.pdf

# Bruk ID-en fra svaret i fakturaen:
"attachment_ids": ["att_…"]

5. Send en kreditnota

Kreditnota bruker de samme avsender-, mottaker-, referanse-, linje- og MVA-begrepene. Oppgi fakturaen som krediteres; beløp og antall sendes som positive verdier.

POST /v1/credit-notes

{
  "sender_organization_id": "ORG_ID",
  "recipient_organization_number": "987654325",
  "number": "KN-1042",
  "date": "2026-08-12",
  "references": {"buyer": "Andreas Flakstad"},
  "credited_invoice": {"number": "1042", "date": "2026-08-10"},
  "note": "Korrigert antall",
  "lines": [{
    "description": "Konsulentarbeid",
    "quantity": 1,
    "unit": "hour",
    "unit_price": 1250,
    "vat_rate": 25
  }]
}

6. Les status og originaldokument

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

GET /v1/invoices?status=delivered&limit=25
GET /v1/credit-notes?credited_invoice_number=1042

Bruk tilsvarende ruter under /v1/credit-notes for kreditnota. Listeendepunktene kan filtreres på nummer, status, avsender og mottaker og bruker markørbasert sideinndeling. Ressursen 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": "invalid_payment_reference",
    "message": "KID must have a valid MOD10 or MOD11 check digit."
  },
  "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://fakturaapi.no/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, invoice.failed, credit_note.delivered og credit_note.failed. Ny utsending av en webhook sender samme hendelse uten å sende dokumentet på nytt.

Endepunkter