Self-billing (aankoopborderel) via de API

Met deze endpoints maak je uitgegeven aankoopborderellen aan, in het Belgische btw-jargon self-billed invoices. Dat is een document dat jouw bedrijf opstelt namens een leverancier (bv. een melkgeldafrekening die een zuivelbedrijf opstelt voor een melkveehouder).

Typische gebruikers: producenten en coöperaties die periodiek afrekeningen opstellen voor hun leveranciers, of externe systemen die afrekeningen genereren en in NumNum willen aanleveren met behoud van hun eigen PDF-layout.

ℹ️ Authenticatie (persoonlijke API-token + X-Company-Id), limieten en algemene foutcodes staan in het API-overzicht voor ontwikkelaars. De headers en klant-matching zijn identiek aan de Facturen-API.

Endpoints

POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle
POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle-creditnote

Request body: aankoopborderel

Een JSON-array van borderellen (atomair verwerkt). De structuur lijkt op de Facturen-API, met enkele verschillen.

Regels (lines)

"lines": [
  { "description": "Melklevering 1–15 mei (liter)", "unit_price": 0.45, "amount": 12500, "vat_percentage": 6 }
]

Zelfde velden als een factuurlijn: description, unit_price, amount, vat_percentage. amount mag decimaal zijn (bv. liter/kg). Totalen worden server-side berekend.

Eigen PDF meesturen (attachment_pdf)

Wil je je eigen PDF-layout behouden? Stuur een base64-gecodeerde PDF mee. Die wordt als bijlage bewaard bij het document en meegenomen bij Peppol-verzending. NumNum genereert daarnaast nog steeds een standaard-PDF op basis van de documentdata.

• Max grootte ± 15 MB (base64). Blijf hier ruim onder.
• Ontbreekt attachment_pdf_filename, dan wordt <borderel-nr>.pdf gebruikt.
• Stuur enkel echte PDF’s; het content-type wordt geforceerd op application/pdf.

// Node.js
const fs = require('fs')
const pdfBase64 = fs.readFileSync('./melkgeld-mei-2026.pdf').toString('base64')

Request body: creditnota

Vrijwel identiek aan een borderel, met deze verschillen:

Alle andere velden gedragen zich identiek. Gebruik negatieve of corrigerende bedragen naargelang je correctie.

Voorbeeld: melkgeldafrekening

curl -X POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle \
  -H "Authorization: Bearer <jouw-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
    {
      "language": "nl",
      "purchase_borderelle_date": "2026-05-20",
      "expire_days": 30,
      "reference": "Melkgeld mei 2026",
      "payment_info": "no",
      "client": {
        "company_type": "company",
        "type": "onbekend",
        "email": "boer@example.be",
        "first_name": "Jan",
        "last_name": "De Boer",
        "vat_country_code": "BE",
        "vat_id": "0123456789",
        "address": "Boerderijstraat 1",
        "address_zip": "9800",
        "address_city": "Deinze",
        "address_country": "BE"
      },
      "lines": [
        { "description": "Melklevering 1–15 mei (liter)", "unit_price": 0.45, "amount": 12500, "vat_percentage": 6 },
        { "description": "Melklevering 16–31 mei (liter)", "unit_price": 0.46, "amount": 13200, "vat_percentage": 6 }
      ]
    }
  ]'

Voorbeeld: creditnota op een borderel

curl -X POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle-creditnote \
  -H "Authorization: Bearer <jouw-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "language": "nl",
      "purchase_borderelle_creditnote_date": "2026-05-21",
      "purchase_borderelle_uuid": "9c1a2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "reference": "Correctie melkgeld mei",
      "client": { "company_type": "company", "type": "onbekend", "email": "boer@example.be", "first_name": "Jan", "last_name": "De Boer", "vat_country_code": "BE", "vat_id": "0123456789", "address": "Boerderijstraat 1", "address_zip": "9800", "address_city": "Deinze", "address_country": "BE" },
      "lines": [
        { "description": "Correctie kwaliteitspremie", "unit_price": -50.00, "amount": 1, "vat_percentage": 6 }
      ]
    }
  ]'

Response

HTTP 201: Aangemaakt

Aankoopborderel:

{ "purchase_borderelles": [1234, 1235] }

Creditnota:

{ "purchase_borderelle_creditnotes": [987] }

De array bevat de interne database-ID’s in dezelfde volgorde als de input.

Fouten

Zie de foutentabel in het API-overzicht. Validatiefouten volgen hetzelfde invalid_body-formaat als de Facturen-API, geïndexeerd per positie (0.client.email, 1.lines.0.unit_price, …). Een purchase_borderelle_uuid van een ander bedrijf geeft 404.

Verschil met de Facturen-API

Aandachtspunten

• Nummering: het borderelnummer wordt automatisch gegenereerd (typisch met AB-prefix). Je kan geen eigen nummer meesturen.
• Niet idempotent: dezelfde payload tweemaal versturen maakt tweemaal een document aan.
• Ontvangen aankoopborderellen (van een leverancier) komen binnen via Peppol; dat is geen use-case voor deze API.