Autofacturation (bordereau d’achat) via l’API

Ces endpoints créent des bordereaux d’achat émis, en jargon TVA belge des factures d’autofacturation (self-billing). Il s’agit d’un document que votre entreprise établit au nom d’un fournisseur (p. ex. un décompte de « prix du lait » qu’une laiterie établit pour un éleveur laitier).

Utilisateurs typiques : producteurs et coopératives qui établissent périodiquement des décomptes pour leurs fournisseurs, ou systèmes externes qui génèrent des décomptes et souhaitent les transmettre à NumNum tout en conservant leur propre mise en page PDF.

ℹ️ L’authentification (jeton API personnel + X-Company-Id), les limites et les codes d’erreur généraux figurent dans l’Aperçu de l’API pour développeurs. Les en-têtes et la correspondance client sont identiques à l’API Factures.

Endpoints

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

Corps de la requête : bordereau d’achat

Un tableau JSON de bordereaux (traités de façon atomique). La structure ressemble à l’API Factures, avec quelques différences.

Lignes (lines)

"lines": [
  { "description": "Livraison de lait 1–15 mai (litre)", "unit_price": 0.45, "amount": 12500, "vat_percentage": 6 }
]

Mêmes champs qu’une ligne de facture : description, unit_price, amount, vat_percentage. amount peut être décimal (p. ex. litre/kg). Les totaux sont calculés côté serveur.

Joindre votre propre PDF (attachment_pdf)

Vous voulez conserver votre propre mise en page PDF ? Envoyez un PDF encodé en base64. Il est stocké comme pièce jointe sur le document et inclus lors de l’envoi Peppol. NumNum génère malgré tout un PDF standard à partir des données du document.

• Taille max ± 15 Mo (base64). Restez bien en dessous.
• Si attachment_pdf_filename est absent, <n°-bordereau>.pdf est utilisé.
• N’envoyez que de vrais PDF ; le type de contenu est forcé à application/pdf.

// Node.js
const fs = require('fs')
const pdfBase64 = fs.readFileSync('./prix-du-lait-mai-2026.pdf').toString('base64')

Corps de la requête : note de crédit

Presque identique à un bordereau, avec ces différences :

Tous les autres champs se comportent de manière identique. Utilisez des montants négatifs ou correctifs selon votre correction.

Exemple : décompte « prix du lait »

curl -X POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle \
  -H "Authorization: Bearer <votre-jeton-api>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
    {
      "language": "fr",
      "purchase_borderelle_date": "2026-05-20",
      "expire_days": 30,
      "reference": "Prix du lait mai 2026",
      "payment_info": "no",
      "client": {
        "company_type": "company",
        "type": "onbekend",
        "email": "eleveur@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": "Livraison de lait 1–15 mai (litre)", "unit_price": 0.45, "amount": 12500, "vat_percentage": 6 },
        { "description": "Livraison de lait 16–31 mai (litre)", "unit_price": 0.46, "amount": 13200, "vat_percentage": 6 }
      ]
    }
  ]'

Exemple : note de crédit sur un bordereau

curl -X POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle-creditnote \
  -H "Authorization: Bearer <votre-jeton-api>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "language": "fr",
      "purchase_borderelle_creditnote_date": "2026-05-21",
      "purchase_borderelle_uuid": "9c1a2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "reference": "Correction prix du lait mai",
      "client": { "company_type": "company", "type": "onbekend", "email": "eleveur@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": "Correction prime de qualité", "unit_price": -50.00, "amount": 1, "vat_percentage": 6 }
      ]
    }
  ]'

Réponse

HTTP 201 : Créé

Bordereau d’achat :

{ "purchase_borderelles": [1234, 1235] }

Note de crédit :

{ "purchase_borderelle_creditnotes": [987] }

Le tableau contient les identifiants internes de base de données dans le même ordre que l’entrée.

Erreurs

Voir le tableau des erreurs dans l’aperçu de l’API. Les erreurs de validation suivent le même format invalid_body que l’API Factures, indexées par position (0.client.email, 1.lines.0.unit_price, …). Un purchase_borderelle_uuid d’une autre entreprise renvoie 404.

Différence avec l’API Factures

Points d’attention

• Numérotation : le numéro de bordereau est généré automatiquement (généralement avec un préfixe AB). Vous ne pouvez pas fournir votre propre numéro.
• Non idempotent : envoyer deux fois la même charge utile crée deux documents.
• Les bordereaux d’achat reçus (d’un fournisseur) arrivent via Peppol ; ce n’est pas un cas d’usage de cette API.