API – 7. Endpoints

POST `/invoices`

Maak een nieuwe verkoopfactuur aan.

Doel

Een factuur creëren in je live-account op basis van klant- en regellijnen. Je krijgt de aangemaakte resource terug (incl. totalen en links).

URL

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

Headers

Authorization: Bearer <JOUW_API_KEY>
Content-Type: application/json
Idempotency-Key: <uuid>             # optioneel, zie Idempotency

Request body

Structuur (compacte referentie)

external_id (string, optioneel) — eigen unieke referentie; helpt duplicaten voorkomen.
invoice(object, verplicht)
- number (string, optioneel) — stuur mee om je eigen nummering te overnemen; moet uniek zijn binnen je account. Laat weg om te hernummeren door Facturalia.
- date (string, verplicht) — JJJJ-MM-DD.
- due_days (integer, optioneel, ≥0) — vervaltermijn in dagen.
- due_days_after (nf/em, optioneel) — Na factuurdatum (default) of Einde maand
- language (string, optioneel) — nl/fr/en.
- note (string, optioneel)
- reference (string, optioneel) — Bvb. het ordernummer
- delivery_address_line_1 (string, optioneel) — Straat huisnummer
- delivery_address_line_2 (string, optioneel) — Postcode gemeente
- delivery_address_line_3 (string, optioneel)
- is_paid (0/1, optioneel)
- vat_exemption_code (integer ≥0 of null, optioneel)
- layout (integer, optioneel) — lay-out ID voor de PDF.
- autosend (0/1, optioneel) — automatisch verzenden na aanmaak.
- email_tpl (integer, optioneel) — e-mailtemplate ID (alleen gebruikt bij e-mailroute).
- discount_amount(number, optioneel) — niet in combinatie met discount_percent.
- discount_percent (number, optioneel) — niet in combinatie met discount_amount.
customer(object, verplicht) — minimaal één van: customer_id, vat_number of name.
- customer_id (integer, optioneel)
- vat_number, name, street, postal_code, city, country(ISO-2), email, phone, external_customer_no (allen optioneel; gebruikt bij opzoeking/aanmaak klant; indien klant al bestaat worden de gegevens die al in Facturalia zitten gebruikt voor de factuur)
lines(array, verplicht, ≥1) — factuurlijnen
- per item (object, verplicht):
  - product_code (string, verplicht) — verwijst naar bestaand product; indien product al bestaat worden de productgegevens die al in Facturalia zitten gebruikt voor de factuur
  - quantity (number, verplicht, >0)
  - unit_price (number, verplicht, ≥0) — excl. btw
  - vat_rate (number, verplicht) — 0/6/12/21. *
  - unit (string, optioneel, default: ‘stuks’) — de exacte eenheid zoals je die vindt via Menu > Basisgegevens > Eenheden *
  - product_name (string, optioneel) *
  - product_group (string, optioneel) — de exacte productgroep zoals je die vindt via Menu > Basisgegevens > Productgroepen *
  - detail (string, optioneel)

* Wordt enkel gebruikt als product met de opgegeven product_code nog niet bestaat en het product wordt angemaakt.

Businessregels & validatie staan in hoofdstuk 6; validatiefouten geven 422 met details per veld.

Voorbeeldverzoek

{
  "external_id": "order-12345",
  "invoice": {
    "number": "2025-00123",
    "date": "2025-09-26",
    "due_days": 30,
    "language": "nl",
    "note": "Opmerking bij de factuur",
    "reference": "Ordernummer 123",
    "delivery_address_line_1": "Marktplein 100",
    "delivery_address_line_2": "1000 Brussel",
    "delivery_address_line_3": "",
    "is_paid": 1,
    "vat_exemption_code": 0,
    "layout": 111,
    "autosend": 0,
    "email_tpl": 655,
    "discount_percent": 10
  },
  "customer": {
    "vat_number": "BE0123456789",
    "name": "ABCD BV",
    "street": "Kerkstraat 1",
    "postal_code": "1000",
    "city": "Brussel",
    "country": "BE",
    "email": "facturatie@abcd.be",
    "phone": "+32 2 123 45 67",
    "external_customer_no": "CUST-7788"
  },
  "lines": [
    {
      "product_code": "CONS-001",
      "quantity": 1,
      "unit_price": 120.0,
      "vat_rate": 21,
      "unit": "uur",
      "product_name": "Snoeiwerk",
      "product_group": "Werkuren",
      "detail": ""
    },
    {
      "product_code": "CONS-002",
      "quantity": 3,
      "unit_price": 35.0,
      "vat_rate": 21,
      "unit": "stuks",
      "product_name": "Buxus",
      "product_group": "Struiken",
      "detail": ""
    }
  ]
}

Succesrespons

Status: 201 Created
Headers:

Location: https://www.facturalia.be/api/v1/invoices/98765
Content-Type: application/json; charset=utf-8
Idempotency-Status: stored|replayed       # indien van toepassing
X-RateLimit-Limit / Remaining / Reset     # indien ingeschakeld

Body (voorbeeld):

{
  "id": 98765,
  "number": "2025-00123",
  "customer_created": false,
  "products_created": [],
  "currency": "EUR",
  "totals": {
    "total_excl_vat": 225.00,
    "total_incl_vat": 272.25
  },
  "autosend": {
    "autosend_status": "SENT",          // SENT, NOT_SENT, SENDING_ERROR, SENDING_PENDING
    "autosend_channelused": "EMAIL",    // NONE | EMAIL | PEPPOL
    "autosend_error": ""                // enkel gevuld bij status SENDING_ERROR
  },
  "links": {
    "pdf": "https://www.facturalia.be/invoices/98765.pdf",
    "ubl": "https://www.facturalia.be/invoices/98765.xml",
  }
}

Foutresponses (samenvatting)

400 invalid_json — body geen geldige JSON
401 unauthorized — ontbrekende/ongeldige API key
403 forbidden — scope ontbreekt (invoices:create)
405 method_not_allowed — gebruik POST
409 idempotency_conflict — zelfde external_id/Idempotency-Key/invoice.number met andere payload
415 unsupported_media_type — verkeerde Content-Type
422 validation_error — veldfouten (met details)
429 rate_limited — limiet overschreden
500 server_error — onverwachte fout

Voor het volledige foutformaat en voorbeelden, zie hoofdstuk 5) Fouten.

Voorbeelden (cURL & Postman)

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" \
  -d '{
    "external_id": "order-12345",
    "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 }]
  }'

Postman

Methode POST, URL https://www.facturalia.be/api/v1/invoices
Authorization: Bearer Token → plak je key
Headers: Content-Type: application/json (+ optioneel Idempotency-Key)
Body: raw → JSON (payload zoals hierboven)

Notities

PDF-link kan enkele seconden na creatie beschikbaar worden (asynchrone generatie).
Idempotency: zie hoofdstuk 3 voor volledige uitleg en keuze tussen external_id en Idempotency-Key.
Rate limiting & daggebruik: zie hoofdstuk 4.

GET `/auth/verify`

Doel

Dit endpoint valideert een API-key en geeft informatie terug over de gekoppelde gebruiker en bijhorende rechten (scopes).
Het is bedoeld voor integraties zoals de WooCommerce-plugin, die bij activatie de ingevoerde API-key wil controleren, of integraties door derden.

Methode

GET /api/v1/auth/verify

Headers

Naam	Verplicht	Waarde	Uitleg
`Authorization`	✔	`Bearer <JOUW_API_KEY>`	De API-key van de gebruiker
`Content-Type`	–	`application/json`	Optioneel

Request body

Er is geen body of payload nodig.
Alle authenticatie gebeurt via de Authorization-header.

Response (200 OK)

Bij een geldige API-key ontvang je de gekoppelde account- en key-informatie.

{
  "account": {
    "id": 123,
    "bedrijf": "ABCD BV"
  },
  "key": {
    "id": 45,
    "name": "WooCommerce",
    "prefix": "fac_live_3xxxxx",
    "created": "2025-09-20 10:23:11"
  },
  "scopes": ["invoices:create"]
  },
  "rate_limit": {
    "limit_per_min": 60
  }
}

Mogelijke foutcodes

Code	Omschrijving
401 Unauthorized	Ongeldige of ontbrekende API-key.
403 Forbidden	De API-key is geldig maar mist de vereiste scope(s).
405 Method Not Allowed	Gebruik een andere HTTP-methode dan GET.
500 Server Error	Interne fout (bv. database niet bereikbaar).

Gebruik

Je kunt dit endpoint veilig gebruiken in setup-wizards of integratiecontroles; het heeft geen invloed op data in Facturalia.

Andere endpoints

In de nabije toekomst voorzien we een verdere uitbreiding van onze API met extra endpoints

Abonnement & facturatie

Functionaliteiten

Partners

Algemeen

API

API – 7. Endpoints

POST `/invoices`

Doel

URL

Headers

Request body

Structuur (compacte referentie)

Voorbeeldverzoek

Succesrespons

Foutresponses (samenvatting)

Voorbeelden (cURL & Postman)

Notities

GET `/auth/verify`

Doel

Methode

Headers

Request body

Response (200 OK)

Mogelijke foutcodes

Gebruik

Andere endpoints

Start vandaag nog met e-factureren

menu

Abonnement & facturatie

Functionaliteiten

Partners

Algemeen

API

API – 7. Endpoints

POST /invoices

Doel

URL

Headers

Request body

Structuur (compacte referentie)

Voorbeeldverzoek

Succesrespons

Foutresponses (samenvatting)

Voorbeelden (cURL & Postman)

Notities

GET /auth/verify

Doel

Methode

Headers

Request body

Response (200 OK)

Mogelijke foutcodes

Gebruik

Andere endpoints

Start vandaag nog met e-factureren

menu

POST `/invoices`

GET `/auth/verify`