Facturen uitgeven via de API

POST /invoices met Idempotency-Key, btw in percentages, plus lijst, creditnota en betaald markeren.

Je eerste factuur in 6 stappen

Stuur POST /v1/invoices met een buyer-object en minstens één regel in lines.
Voeg de Idempotency-Key-header toe — die is verplicht, één sleutel per logische bewerking.
Stuur vat_rate als percentage (21) en unit_price als NETTO-eenheidsprijs.
De 201-respons bevat id, number, series, de totalen netto/btw/bruto en de metadata die u hebt meegestuurd.
Haal het document op met GET /v1/invoices/{id}/pdf of de UBL-XML met GET /v1/invoices/{id}/xml.

Alle endpoints

Methode	Endpoint	Scope	Idempotency-Key	Verzoeken / minuut
POST	/invoices Een factuur of proforma uitgeven	invoices:write	verplicht	30
GET	/invoices Facturen weergeven (cursorpaginering)	invoices:read	—	120
POST	/invoices/preview-totals Totalen berekenen zonder iets aan te maken	invoices:read	—	120
GET	/invoices/{invoice_id} Eén factuur ophalen	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf De PDF van de factuur downloaden	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Een creditnota uitgeven die deze factuur tenietdoet	invoices:write	verplicht	30
POST	/invoices/{invoice_id}/payments De factuur als betaald markeren	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments De factuur als onbetaald markeren	invoices:write	—	30

Wat de 4invoices-API is

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{
    "buyer": {
      "name": "Exemplu Comert SRL",
      "tax_id": "RO12345678",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

bash
# Cursorpaginering: volg next_cursor tot has_more false is.
curl -sS "https://api.4invoices.net/v1/invoices?limit=50&status=issued&issued_from=2026-07-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"object":"list","data":[...],"has_more":true,"next_cursor":"inv_01J..."}

curl -sS "https://api.4invoices.net/v1/invoices?limit=50&cursor=inv_01J..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/storno \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: storno-inv_01J7ABC-1'

# De creditnota krijgt een EIGEN fiscaal nummer; het nummer van het origineel wordt nooit hergebruikt.

bash
# Markeer als betaald
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Ongedaan maken
curl -sS -X DELETE https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Fouten

Status	Type	Code
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Veelgemaakte fouten

Het opvragen van lijsten werkt met een cursor: volg next_cursor tot has_more false is. Filters zijn onder meer status, document_kind, buyer_tax_id, issued_from, issued_to en q.
Een creditering (storno) is POST /v1/invoices/{id}/storno en krijgt een eigen fiscaal nummer — het oorspronkelijke nummer wordt nooit hergebruikt.
Een proforma (document_kind proforma) verbruikt geen fiscaal nummer en kan niet bij het nationale e-factureringssysteem worden ingediend.
metadata wordt bij leesbewerkingen teruggegeven: zet daar uw order-id in en u hebt geen aparte koppeltabel meer nodig.
POST /v1/invoices/preview-totals voert dezelfde berekening uit zonder neveneffecten — handig om totalen in uw eigen winkelwagen te tonen.

Vragen en antwoorden voor ontwikkelaars

Hoeveel regels kan één factuur hebben?

Tussen 1 en 400. description is beperkt tot 1024 tekens en quantity moet strikt positief zijn.

Wat gebeurt er als ik hetzelfde request na een time-out opnieuw stuur?

Met dezelfde Idempotency-Key krijgt u de oorspronkelijke factuur plus een Idempotency-Replayed: true-header. Er wordt geen tweede document uitgegeven.

Hoe markeer ik een factuur als betaald?

POST /v1/invoices/{id}/payments markeert haar als betaald en DELETE op hetzelfde pad maakt dat ongedaan. Beide vereisen de scope invoices:write.

Zie ook