NumNum Webhook

Met de NumNum API Webhook kan je automatisch facturen aanmaken in je eigen NumNum-omgeving. Zodra de facturen aangemaakt zijn, kan je ze vanuit NumNum eenvoudig verzenden via e-mail, Peppol of per post.

Deze functionaliteit laat toe om een eigen integratie op te zetten waarmee je Peppol-facturen kan versturen via NumNum.

⚠️ Opgelet: Deze functie is uitsluitend beschikbaar voor Trilly-gebruikers.

Request headers

• Authorization: <token>
• X-Company-Id: <your_company_id>

Request body

Factuur

• language: string[2] - 2-letterige ISO-code voor de documenttaal, beschikbare opties: nl, en, fr, de
• invoice_date: string[10] - factuurdatum in formaat JJJJ-MM-DD
• expire_days: int - Vervaldatum van de factuur, in “dagen na de factuurdatum”. Geldige waarden: 0…365
• reference: string[200] (optioneel) - Extra referentie voor de factuur, zichtbaar in factuuroverzicht
• intro: text (optioneel) - Introductietekst die boven de factuurlijnen verschijnt op de PDF
• remarks: text (optioneel) - Voettekst onder de factuurlijnen op de PDF
• private_notes: text (optioneel) - Privétekst op de factuur, zichtbaar voor gebruiker maar nooit voor eindklant
• vat_shifted: int (optioneel) - Is verlegde btw van toepassing op de factuur. Let op: alle lijnen moeten vat_percentage=0 gebruiken als dit veld een andere waarde heeft dan 0. Beschikbare waarden:
  • 0: Nee (= standaard)
  • 2: Medecontractant
  • 4: Intracommunautaire diensten
  • 8: Intracommunautaire goederen
  • 32: Margeregeling
  • 64: Import export
  • 128: Buiten EU
• client: client - De klant die aan de factuur moet gekoppeld worden
• lines: array<invoice_line> - Lijst van factuurlijnen die aan de factuur moeten worden gekoppeld

Klant

• company_type: string - Beschikbare waarden: “bedrijf”, “particulier”
• type: string - als company_type=bedrijf --> Juridische vorm van het bedrijf. Beschikbare waarden: onbekend, bvba, bv, eenmanszaak, nv, sbvba, ebvba, cvba, cvba-vso, cvoa, cvoa-vso, vof, gcv, comm.v, comm.va, esv, lv, vzw, vvzrl, tv, natuurlijk-persoon, limited-ltd, limited-llc, incorporated, srl, scri, sa, sas, sarl, sarl-s, gmbh, ag, srl, spa, doo, sl, sc, asbl, vme, feitelijke-vereniging
• title: string[255] - De bedrijfsnaam als company_type=bedrijf. Niet verplicht indien particulier
• email: string[150]
  • vat_country_code: string[2] - 2-letterige ISO-landcode voor het btw-nummer, bijv. ‘BE’
• vat_id: string[30] - Aanvullende waarden van het btw-nummer, bijv. “0663.642.920”
• first_name: string[255], verplicht indien company_type=particulier
• last_name: string[255], verplicht indien company_type=particulier
• address: string[200], facturatieadres (straat + nummer)
• address_zip: string[12] postcode van het facturatieadres
• address_city: string[150] stad/locatie van het facturatieadres
• address_country: string[2] 2-letterige ISO-code van het land van het facturatieadres
• telephone: string[100] - optioneel

Factuurlijn

• description: text - Tekst voor de factuurlijn
• unit_price: double - Eenheidsprijs per artikel
• amount: double - Aantal artikelen
• vat_percentage: double- bijv. 21.00

Voorbeeld van request payload

[
  {
    "language": "nl",
    "invoice_date": "2025-01-10",
    "expire_days": 14,
    "reference": "Webshop #111",
    "intro": "",
    "remarks": "",
    "private_notes": "Webshop #111",
    "vat_shifted": 0,
    "client": {
      "company_type": "bedrijf",
      "type": "onbekend",
      "title": "NumNumTest",
      "email": "info@numnum.be",
      "vat_country_code": null,
      "vat_id": null,
      "first_name": "Wim",
      "last_name": "De Bakker",
      "address": "Markt 1",
      "address_zip": "8000",
      "address_city": "Brugge",
      "address_country": "BE",
      "telephone": ""
    },
    "invoice_lines": [
      {
        "description": "Line 1",
        "unit_price": 10.00,
        "amount": 2.5,
        "vat_percentage": 21.00
      },
      {
        "description": "Line 2",
        "unit_price": 20.00,
        "amount": 5,
        "vat_percentage": 21.00
      },
      {
        "description": "Shipping",
        "unit_price": 20.00,
        "amount": 5,
        "vat_percentage": 21.00
      }
    ]
  }
]

Resultaat

De API zal HTTP 201 teruggeven als de resource succesvol is aangemaakt; behandel alle andere statuscodes (200, 403, 500, …) als een mislukking en plaats de factuur in een wachtrij voor later opnieuw proberen.

HTTP 201 - Factuur aangemaakt

Geeft een lijst van ID’s terug van de aangemaakte factuur/facturen in NumNum

[10232,10233]

HTTP 403 - Geweigerd

Probleem met validatie van de Authorization-token in de header van het verzoek

{exception: "Information..."}

HTTP 406 - Mislukt, validatieprobleem

Wordt teruggegeven als er een probleem is met de payload-validatie

{exception: "Information..."}

HTTP 500 - Onverwacht probleem

HTTP 200 - Onverwacht probleem

Reguliere HTTP-code. Deze moet echter moet behandeld worden als “opnieuw proberen” omdat de API enkel HTTP 201 geeft bij effectieve creatie

Postman

📥 Download via deze link een postman voorbeeld van de webhook.