API voor ontwikkelaars

Met de API van NumNum maak je programmatisch documenten aan in je eigen NumNum-omgeving. Eenmaal aangemaakt kan je die documenten gewoon verzenden via e-mail, Peppol of per post, precies zoals documenten die je manueel aanmaakt.

De API is bedoeld voor server-to-server integraties, bijvoorbeeld:

E-commerce: automatisch een factuur aanmaken na een online verkoop
ERP / CRM: facturen aanmaken vanuit je bestaande systeem
Self-billing: periodieke afrekeningen (aankoopborderellen) voor je leveranciers, bv. coöperaties of producenten
Eigen workflows: factuurcreatie inbouwen in je eigen applicatie

Wat kan je met de API?

De API is write-only: je maakt er documenten mee aan. Er zijn drie endpoints:

Wat	Endpoint	Documentatie
Verkoopfacturen aanmaken	`POST /api/v1/webhooks/create-invoice`	Facturen aanmaken
Uitgegeven aankoopborderel (self-billing) aanmaken	`POST /api/v1/webhooks/create-purchase-borderelle`	Self-billing / aankoopborderel
Creditnota op een aankoopborderel aanmaken	`POST /api/v1/webhooks/create-purchase-borderelle-creditnote`	Self-billing / aankoopborderel

Wat kan (nog) niet via de API

Om verwachtingen scherp te zetten:

❌ Documenten uitlezen, wijzigen of verwijderen kan niet met je persoonlijke API-token. De API dient enkel om documenten aan te maken.
❌ Eigen documentnummers meesturen kan niet: NumNum nummert automatisch volgens je bedrijfsinstellingen (wettelijk verplichte ononderbroken nummerreeks).
❌ Idempotentie is er niet: dezelfde payload tweemaal versturen maakt tweemaal een document aan. Hou zelf bij welke documenten je al aanleverde (bv. via het reference-veld of de teruggegeven ID’s).

ℹ️ Verzenden via Peppol of e-mail zit niet in deze API; dat doe je nadien in de app of via je gewone verzendflow.

Toegang

Je genereert je API-token zelf op de pagina Mijn API’s in je bedrijfsinstellingen (zie Authenticatie). Zie je die pagina niet? Neem dan contact op met support (help@numnum.be).

Authenticatie

Elke API-request heeft twee headers nodig: je persoonlijke API-token en het bedrijf waarvoor je werkt.

1. Persoonlijke API-token

Log in op NumNum
Ga naar Instellingen → Koppelingen → Mijn API’s (https://app.numnum.be/company/connection/myapi)
Klik op Genereer API token

Enkele belangrijke eigenschappen:

De token is een reeks van exact 64 tekens (cijfers en letters). Kopieer steeds de volledige waarde zoals ze op de pagina staat; ze blijft daar zichtbaar zolang je geen nieuwe genereert.
De token hangt aan jouw gebruiker, niet aan één bedrijf. Dezelfde token werkt voor alle bedrijven waartoe je toegang hebt; je kiest het bedrijf per request via de X-Company-Id header.
Er is geen aparte “intrekken”-knop: opnieuw op Genereer API token klikken maakt een nieuwe token aan en maakt de vorige meteen ongeldig.
Behandel de token als een wachtwoord: bewaar ze in een omgevingsvariabele / secrets manager, deel ze nooit via e-mail of chat en commit ze niet naar git.

2. Company ID

Je X-Company-Id bepaalt in welk bedrijf het document wordt aangemaakt. Je vindt het:

naast je token op de pagina Mijn API’s, of
in de URL van NumNum (bv. https://app.numnum.be/company/12345/... → Company ID = 12345).

Base URL & headers

https://app.numnum.be/api/v1

Header	Verplicht	Voorbeeld
`Authorization`	Ja	`Bearer <jouw-api-token>`
`X-Company-Id`	Ja	`12345`
`Content-Type`	Ja	`application/json`
`Accept`	Aanbevolen	`application/json`

Let op de spatie tussen Bearer en de token.

Foutafhandeling

Behandel enkel HTTP 201 als succes. Alle andere statuscodes betekenen dat het document niet is aangemaakt; zet de request in een wachtrij en probeer later opnieuw (met exponentiële back-off bij 429 en 5xx).

Status	Betekenis	Response body
`201 Created`	Document(en) aangemaakt	`{ "invoices": [1234] }` (afhankelijk van endpoint)
`400 Bad Request`	Headers ontbreken	`{ "error": "Required headers are missing." }`
`400 Bad Request`	Verkeerd `Authorization`-formaat	`{ "error": "Authorization header format is invalid." }`
`400 Bad Request`	Validatiefout in de payload	`{ "error": "invalid_body", "errors": { "0.client.email": ["..."] } }`
`401 Unauthorized`	Ongeldige API-token	`{ "error": "Invalid API token." }`
`403 Forbidden`	Je gebruiker heeft geen toegang tot dit bedrijf	`{ "error": "Access to this company is forbidden." }`
`404 Not Found`	Onbekend Company ID	`{ "error": "Invalid company ID." }`
`429 Too Many Requests`	Rate limit of maandlimiet bereikt	`{ "error": "Monthly API document limit reached." }`
`500`	Onverwachte serverfout	Neem contact op met help@numnum.be

Bij validatiefouten (400 invalid_body) verwijst de sleutel naar de positie in de array en het veld, bv. 0.client.email = eerste document, veld client.email.

Limieten & quota

Batch: één request bevat een array van documenten (max 50 per request). De verwerking is atomair: als één document faalt, wordt géén enkel document aangemaakt.
Rate limit (per bedrijf): 30 requests per minuut en 2000 per dag.
Maandelijkse limiet: er geldt een maximum aantal documenten per maand (richtwaarde ± 200/maand). Bij overschrijding krijg je 429.
Hou parallelle verzoeken beperkt (± 5 gelijktijdig) om de server niet te overbelasten.

Verouderd endpoint (legacy)

Een ouder endpoint, POST /webhooks/create-invoice (zónder /api/v1), bestaat nog voor bestaande integraties. Het gebruikt dezelfde token maar geeft een kale lijst terug ([10232, 10233]) en andere foutcodes (406, 401). Dit endpoint is verouderd; gebruik voor nieuwe integraties altijd POST /api/v1/webhooks/create-invoice.

Volgende stappen

Vragen? Contacteer help@numnum.be.