API – 7. Endpoints

POST `/uploads/`

Upload een bijlage, die je wil toevoegen aan je factuur

Doel

Het uploaden van een bijlage. De stored_name die je terugkrijgt kan je je gebruiken in het endpoint /invoices om deze bijlage toe te voegen aan een nieuwe factuur.

URL

POST https://www.facturalia.be/api/v1.1/uploads/

Headers

Authorization: Bearer <JOUW_API_KEY>

Voorbeeldverzoek (curl)

curl -X POST “https://facturalia.be/api/v1.1/uploads” \
-H “Authorization: Bearer JOUW_API_KEY” \
-F “file=@C:/docs/orderdetails.pdf”

Succesrespons

Status: 201 Created
Headers:

Content-Type: application/json; charset=utf-8

Body (voorbeeld):

{
    "ok": true,
    "file": {
        "stored_name": "a02ff33b645a4dc2_orderdetails.pdf",
        "original_name": "orderdetails.pdf",
        "mime": "application/pdf",
        "size": 286789,
    }
}

Foutresponses (samenvatting)

401 unauthorized — ontbrekende/ongeldige API key
405 method_not_allowed — gebruik POST
422 validation_error — Bestand ontbreekt / Bestandsgrootte moet tussen 1 byte en 5 MB liggen / Bestandstype niet toegestaan
500 server_error — onverwachte fout

Toegestane bestandstypes: pdf, doc, docx, xls, xlsx, jpg, gif, png

Notities

Er kunnen maximaal 2 attachments worden toegevoegd aan een nieuwe factuur
Wil je steeds dezelfde bijlage toevoegen aan een factuur (bvb. algemene voorwaarden) voeg die dan eenmalig toe in Facturalia.

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.1/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)
- attachment1 (string, optioneel) – waarde van stored_name van endpoint /uploads
- attachment2 (string, optioneel) – waarde van stored_name van endpoint /uploads
- 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)
- is_sent (0/1, optioneel)
- vat_exemption_code (integer ≥0 of null, optioneel)
- layout (integer, optioneel) — lay-out ID voor de PDF.
- autosend (0/1, optioneel, default 0) — 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.
- update_customer (0/1, optioneel, default 0) — waarde 1 zorgt ervoor dat de klantgegevens zullen worden aangepast in Facturalia als de klant al bestaat
- update_products (0/1, optioneel, default 0) — waarde 1 zorgt ervoor dat de productgegevens zullen worden aangepast in Facturalia als het product al bestaat
customer(object, verplicht) — minimaal één van: customer_id, vat_number of name.
- customer_id (integer, optioneel) — (klant ID in de bron) hier wordt momenteel nog niets met gedaan in Facturalia
- external_customer_no (integer, optioneel) — ( = Facturalia-klantnummer).
- vat_number, name, street, postal_code, city, country(ISO-2), email, phone (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, max 200 karakters)
  - detail_long (string, optioneel, max 5000 karakters)

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",
    "attachment1": "a02ff33b645a4dc2_orderdetails.pdf",
    "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": "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:

Content-Type: application/json; charset=utf-8

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.1/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.1/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.

POST `/creditnotes/`

Maak een nieuwe creditnota aan.

Doel

Een creditnota 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.1/creditnotes/

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.
creditnote(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.
- language (string, optioneel) — nl/fr/en.
- note (string, optioneel)
- attachment1 (string, optioneel) – waarde van stored_name van endpoint /uploads
- reference (string, optioneel) — Bvb. het ordernummer
- is_paid (0/1, optioneel)
- is_sent (0/1, optioneel)
- vat_exemption_code (integer ≥0 of null, optioneel)
- layout (integer, optioneel) — lay-out ID voor de PDF.
- autosend (0/1, optioneel, default 0) — 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.
- update_customer (0/1, optioneel, default 0) — waarde 1 zorgt ervoor dat de klantgegevens zullen worden aangepast in Facturalia als de klant al bestaat
- update_products (0/1, optioneel, default 0) — waarde 1 zorgt ervoor dat de productgegevens zullen worden aangepast in Facturalia als het product al bestaat
customer(object, verplicht) — minimaal één van: customer_id, vat_number of name.
- customer_id (integer, optioneel) — (klant ID in de bron) hier wordt momenteel nog niets met gedaan in Facturalia
- external_customer_no (integer, optioneel) — ( = Facturalia-klantnummer).
- vat_number, name, street, postal_code, city, country(ISO-2), email, phone (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, max 200 karakters)
  - detail_long (string, optioneel, max 5000 karakters)

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

Voorbeeldverzoek

{
  "external_id": "order-12345",
  "creditnote": {
    "number": "2025-00123",
    "date": "2025-09-26",
    "language": "nl",
    "note": "Opmerking bij de factuur",
    "attachment1": "a02ff33b645a4dc2_orderdetails.pdf",
    "reference": "Ordernummer 123",
    "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": "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:

Content-Type: application/json; charset=utf-8

Body (voorbeeld):

{
  "id": 98765,
  "number": "CN20260001",
  "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/creditnota/CN20260001.pdf",
    "ubl": "https://www.facturalia.be/creditnota/CN20260001.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.1/creditnotes \
  -H "Authorization: Bearer <JOUW_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3e5c8bde-6d4a-4f5f-922f-6a9c1b1b46d1" \
  -d '{
    "external_id": "order-12345",
    "creditnote": { "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.1/creditnotes
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 `/invoices/status`

Doel

Via dit endpoint kan je de verzend- en betaalstatus van een factuur ophalen.

Methode

GET /api/v1.1/invoices/status

Headers

Naam	Verplicht	Waarde	Uitleg
`Authorization`	✔	`Bearer <JOUW_API_KEY>`	De API-key van de gebruiker
`Content-Type`	–	`-`
Query parameter	✔	number	Het factuurnummer

Query Parameter

number: het factuurnummer waarvan je de statussen wil opvragen.

Voorbeeld: GET /api/v1.1/invoices/status?number=VF20260215

Response (200 OK)

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

{
    "ok": true,
    "invoice_number": "VF20260215",
    "is_paid": 1,
    "is_sent": 1
}

Mogelijke foutcodes

Code	Omschrijving
401 Unauthorized	Ongeldige of ontbrekende API-key.
404 Not found	Factuur niet gevonden voor deze account en dit nummer.
405 Method Not Allowed	Gebruik GET op dit endpoint.
409 Ambiguous Invoice Number	Meerdere facturen gevonden met dit nummer voor deze account.
422 Validation Error	Query parameter “number” is verplicht.
500 Server Error	Interne fout (bv. database niet bereikbaar).

GET `/creditnotes/status`

Doel

Via dit endpoint kan je de betaalstatus van een creditnota ophalen.

Methode

GET /api/v1.1/creditnotes/status

Headers

Naam	Verplicht	Waarde	Uitleg
`Authorization`	✔	`Bearer <JOUW_API_KEY>`	De API-key van de gebruiker
`Content-Type`	–	`-`
Query parameter	✔	number	Het creditnotanummer

Query Parameter

number: het creditnotanummer waarvan je de status wil opvragen.

Voorbeeld: GET /api/v1.1/creditnotes/status?number=CN20260215

Response (200 OK)

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

{
    "ok": true,
    "creditnote_number": "CN20260215",
    "is_paid": 1
}

Mogelijke foutcodes

Code	Omschrijving
401 Unauthorized	Ongeldige of ontbrekende API-key.
404 Not found	Creditnota niet gevonden voor deze account en dit nummer.
405 Method Not Allowed	Gebruik GET op dit endpoint.
409 Ambiguous Invoice Number	Meerdere creditnota’s gevonden met dit nummer voor deze account.
422 Validation Error	Query parameter “number” is verplicht.
500 Server Error	Interne fout (bv. database niet bereikbaar).

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.1/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.

Abonnement & facturatie

Functionaliteiten

Partners

Algemeen

API

API – 7. Endpoints

POST /uploads/

Doel

URL

Headers

Voorbeeldverzoek (curl)

Succesrespons

Foutresponses (samenvatting)

Notities

POST /invoices/

Doel

URL

Headers

Request body

Structuur (compacte referentie)

Voorbeeldverzoek

Succesrespons

Foutresponses (samenvatting)

Voorbeelden (cURL & Postman)

Notities

POST /creditnotes/

Doel

URL

Headers

Request body

Structuur (compacte referentie)

Voorbeeldverzoek

Succesrespons

Foutresponses (samenvatting)

Voorbeelden (cURL & Postman)

Notities

GET /invoices/status

Doel

Methode

Headers

Query Parameter

Response (200 OK)

Mogelijke foutcodes

GET /creditnotes/status

Doel

Methode

Headers

Query Parameter

Response (200 OK)

Mogelijke foutcodes

GET /auth/verify

Doel

Methode

Headers

Request body

Response (200 OK)

Mogelijke foutcodes

Gebruik

Start vandaag nog met e-factureren

menu

POST `/uploads/`

POST `/invoices/`

POST `/creditnotes/`

GET `/invoices/status`

GET `/creditnotes/status`

GET `/auth/verify`