Facturen aanmaken via de API

Met dit endpoint maak je verkoopfacturen aan in NumNum. Zodra ze aangemaakt zijn kan je ze verzenden via e-mail, Peppol of per post.

ℹ️ Authenticatie (persoonlijke API-token + X-Company-Id), limieten en algemene foutcodes staan in het API-overzicht voor ontwikkelaars. Lees dat eerst.

Endpoint

POST https://app.numnum.be/api/v1/webhooks/create-invoice

Headers:

Authorization: Bearer <jouw-api-token>
X-Company-Id: <jouw-company-id>
Content-Type: application/json
Accept: application/json

Request body

De body is een JSON-array van factuurobjecten. Je kan één of meerdere facturen tegelijk aanmaken (max 50, atomair verwerkt).

Factuurvelden

payment_info

vat_shifted

Btw-verleggingsregime:

⚠️ Bij een andere waarde dan 0 moeten alle factuurlijnen vat_percentage: 0 hebben. De klant heeft doorgaans een geldig btw-nummer nodig (bv. voor intracommunautaire leveringen).

Klant-object

ℹ️ Het veld type is enkel verplicht voor bedrijven (company / bedrijf), niet voor particulieren.

Factuurlijnen (invoice_lines)

De totalen worden automatisch berekend:

• netto = unit_price × amount
• btw = netto × (vat_percentage / 100)
• totaal = netto + btw

Voorbeeld: factuur voor een bedrijf

curl -X POST https://app.numnum.be/api/v1/webhooks/create-invoice \
  -H "Authorization: Bearer <jouw-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
    {
      "language": "nl",
      "invoice_date": "2026-02-15",
      "expire_days": 30,
      "reference": "ORDER-2026-001",
      "intro": "Bedankt voor uw bestelling!",
      "remarks": "Gelieve binnen 30 dagen te betalen.",
      "payment_info": "yes",
      "vat_shifted": 0,
      "client": {
        "company_type": "company",
        "type": "bv",
        "email": "info@klant.be",
        "vat_country_code": "BE",
        "vat_id": "0123456789",
        "first_name": "Jan",
        "last_name": "Janssen",
        "address": "Kerkstraat 1",
        "address_zip": "1000",
        "address_city": "Brussel",
        "address_country": "BE",
        "telephone": "+32 2 123 45 67"
      },
      "invoice_lines": [
        { "description": "Website ontwikkeling", "unit_price": 1500.00, "amount": 1, "vat_percentage": 21 },
        { "description": "Hosting (12 maanden)", "unit_price": 15.00, "amount": 12, "vat_percentage": 21 }
      ]
    }
  ]'

Voorbeeld: particuliere klant

Voor een particulier zijn type en vat_id niet vereist:

[
  {
    "language": "nl",
    "invoice_date": "2026-02-20",
    "expire_days": 14,
    "client": {
      "company_type": "individual",
      "email": "john.doe@gmail.com",
      "first_name": "John",
      "last_name": "Doe",
      "address": "Dorpstraat 45",
      "address_zip": "9000",
      "address_city": "Gent",
      "address_country": "BE"
    },
    "invoice_lines": [
      { "description": "Grafisch ontwerp logo", "unit_price": 350.00, "amount": 1, "vat_percentage": 21 }
    ]
  }
]

Voorbeeld: btw verlegd (intracommunautair)

Bij verlegde btw gebruik je vat_shifted en vat_percentage: 0:

[
  {
    "language": "en",
    "invoice_date": "2026-02-25",
    "expire_days": 30,
    "vat_shifted": 4,
    "remarks": "Reverse charge - VAT to be accounted for by the customer",
    "client": {
      "company_type": "company",
      "type": "gmbh",
      "email": "info@deutschefirma.de",
      "vat_country_code": "DE",
      "vat_id": "123456789",
      "first_name": "Hans",
      "last_name": "Müller",
      "address": "Hauptstraße 10",
      "address_zip": "10115",
      "address_city": "Berlin",
      "address_country": "DE"
    },
    "invoice_lines": [
      { "description": "Consulting services", "unit_price": 2500.00, "amount": 1, "vat_percentage": 0 }
    ]
  }
]

Response

HTTP 201: Aangemaakt

{
  "invoices": [1234, 5678]
}

invoices is een lijst van interne database-ID’s in dezelfde volgorde als de input; dit zijn geen factuurnummers. De factuurnummers worden automatisch gegenereerd volgens je bedrijfsinstellingen.

Fouten

Zie de foutentabel in het API-overzicht. Een validatiefout ziet er zo uit:

{
  "error": "invalid_body",
  "errors": {
    "0.language": ["The language must be one of: nl, fr, en, de."],
    "0.client.email": ["The client email must be a valid email address."],
    "0.invoice_lines.0.unit_price": ["The unit price must be a number."]
  }
}

Klant-matching (dubbele klanten vermijden)

Voor elke factuur zoekt NumNum of de klant al bestaat, anders wordt hij aangemaakt:

• Met btw-nummer (vat_country_code + vat_id): match op je bedrijf + het genormaliseerde btw-nummer. Formattering maakt niet uit: 0123456789 en 0123.456.789 matchen op dezelfde klant.
• Zonder btw-nummer: terugval op de combinatie bedrijf + vat_id + email. Gebruik dan een consistent e-mailadres om duplicaten te vermijden.

⚠️ Bestaat de klant al (btw-match)? Dan wordt hij niet overschreven met de nieuwe gegevens (naam, adres, e-mail). Wijzig je klantgegevens in NumNum zelf.

Aandachtspunten

• Bedragen: gebruik een punt als decimaalteken (1234.56), geen komma en geen duizendtal­scheiding.
• Datums: formaat JJJJ-MM-DD met leading zeros (2026-02-05).
• Btw: numerieke waarde zonder %-teken (21, niet "21%" of 0.21).
• Atomair: faalt één factuur in de batch, dan wordt geen enkele aangemaakt.
• Automatische nummering: je kan geen eigen factuurnummer meesturen.

Entiteitstypes

Geldige waarden voor client.type (enkel verplicht bij bedrijven), o.a.: bv, nv, vzw, bvba, cvba, comm.v, comm.va, vof, eenmanszaak, sa, sarl, sas, srl, gmbh, ag, limited-ltd, limited-llc, natuurlijk-persoon, onbekend. Niet zeker? Gebruik onbekend.

Verouderd endpoint

Het oude endpoint POST /webhooks/create-invoice (zonder /api/v1) werkt nog voor bestaande integraties maar is verouderd: het geeft een kale lijst terug ([10232, 10233]) en gebruikt afwijkende foutcodes (406/401). Migreer naar POST /api/v1/webhooks/create-invoice.