API – 1. Aan de slag

Welkom! Met de Facturalia API kun je in je live-omgeving verkoopfacturen aanmaken via een HTTP-interface.

Wat heb je nodig?

Om de Facturalia API te kunnen gebruiken heb je een van deze abonnementen nodig.

• Facturalia Pro
• Facturalia Master
• Facturalia Kantoor

Heb je nog geen Facturalia abonnement, dan kan je dat hier aangaan. Heb je een ander abonnement, contacteer ons dan voor een upgrade.

Basis-URL (live)

https://www.facturalia.be/api/v1

Versiebeheer

• Pad-gebaseerd: /v1
• Breaking changes komen onder een nieuwe versie (bv. /v2). Kleine uitbreidingen kunnen binnen dezelfde versie verschijnen.

Authenticatie

• Type: Bearer API key (geen OAuth).
• Header: Authorization: Bearer <JOUW_API_KEY>
• Scopes (indien ingeschakeld): invoices:create.
• Beveiliging: Alleen HTTPS. Verzoeken via HTTP worden geweigerd.

Verzoek- en antwoordformaat

• Content-Type: application/json; charset=utf-8
• Antwoorden: JSON
• Datums: JJJJ-MM-DD (tijdzone Europe/Brussels)
• Valuta: standaard EUR

Duplicaten voorkomen (idempotency)

• Optioneel: header Idempotency-Key: <UUID of random token> Gebruik dezelfde sleutel bij een herpoging van dezelfde creatie: je krijgt dan het oorspronkelijke resultaat terug i.p.v. een dubbele factuur.
• Als je het factuurnummer zelf aanlevert (invoice.number), moet dit uniek zijn binnen je account; dit helpt eveneens duplicaten voorkomen.

Fouten

Fouten komen steeds in dit formaat terug:

{
  "error": {
    "code": "validation_error",
    "message": "…",
    "details": { "invoice.date": "…" }
  }
}

Veelvoorkomende statuscodes:
400 invalid_json, 401 unauthorized, 403 forbidden, 404 not_found, 405 method_not_allowed, 409 idempotency_conflict, 422 validation_error, 429 rate_limited, 500 server_error.

Snel starten (cURL)

curl -X POST https://www.facturalia.be/api/v1/invoices \
  -H "Authorization: Bearer <JOUW_API_KEY>" \
  -H "Content-Type: application/json" \
  # -H "Idempotency-Key: 3e5c8bde-6d4a-4f5f-922f-6a9c1b1b46d1" \  # optioneel
  -d '{
    "invoice": { "date": "2025-09-26", "due_days": 30, "language": "nl" },
    "customer": { "name": "ABCD BV" },
    "lines": [
      { "product_code": "CONS-001", "quantity": 1, "unit_price": 120.0, "vat_rate": 21 }
    ]
  }'

Succes: je krijgt 201 Created terug met een JSON-body van de nieuwe factuur en een download-URL van de nieuwe factuur.