Créer des factures via l’API

Cet endpoint crée des factures de vente dans NumNum. Une fois créées, vous pouvez les envoyer par e-mail, Peppol ou courrier.

ℹ️ 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. Lisez-le d’abord.

Endpoint

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

En-têtes :

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

Corps de la requête

Le corps est un tableau JSON d’objets facture. Vous pouvez créer une ou plusieurs factures à la fois (max 50, traitées de façon atomique).

Champs de la facture

payment_info

vat_shifted

Régime d’autoliquidation de TVA :

⚠️ Pour toute valeur autre que 0, toutes les lignes de facture doivent avoir vat_percentage: 0. Le client a généralement besoin d’un numéro de TVA valide (p. ex. pour les livraisons intracommunautaires).

Objet client

ℹ️ Le champ type n’est requis que pour les entreprises (company / bedrijf), pas pour les particuliers.

Lignes de facture (invoice_lines)

Les totaux sont calculés automatiquement :

• net = unit_price × amount
• tva = net × (vat_percentage / 100)
• total = net + tva

Exemple : facture pour une entreprise

curl -X POST https://app.numnum.be/api/v1/webhooks/create-invoice \
  -H "Authorization: Bearer <votre-jeton-api>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
    {
      "language": "fr",
      "invoice_date": "2026-02-15",
      "expire_days": 30,
      "reference": "ORDER-2026-001",
      "intro": "Merci pour votre commande !",
      "remarks": "Merci de payer dans les 30 jours.",
      "payment_info": "yes",
      "vat_shifted": 0,
      "client": {
        "company_type": "company",
        "type": "bv",
        "email": "info@client.be",
        "vat_country_code": "BE",
        "vat_id": "0123456789",
        "first_name": "Jan",
        "last_name": "Janssen",
        "address": "Kerkstraat 1",
        "address_zip": "1000",
        "address_city": "Bruxelles",
        "address_country": "BE",
        "telephone": "+32 2 123 45 67"
      },
      "invoice_lines": [
        { "description": "Développement de site web", "unit_price": 1500.00, "amount": 1, "vat_percentage": 21 },
        { "description": "Hébergement (12 mois)", "unit_price": 15.00, "amount": 12, "vat_percentage": 21 }
      ]
    }
  ]'

Exemple : client particulier

Pour un particulier, type et vat_id ne sont pas requis :

[
  {
    "language": "fr",
    "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": "Gand",
      "address_country": "BE"
    },
    "invoice_lines": [
      { "description": "Conception graphique de logo", "unit_price": 350.00, "amount": 1, "vat_percentage": 21 }
    ]
  }
]

Exemple : autoliquidation de TVA (intracommunautaire)

Pour l’autoliquidation, utilisez vat_shifted et 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 }
    ]
  }
]

Réponse

HTTP 201 : Créée

{
  "invoices": [1234, 5678]
}

invoices est une liste d’identifiants internes de base de données dans le même ordre que l’entrée ; ce ne sont pas des numéros de facture. Les numéros de facture sont générés automatiquement selon vos paramètres d’entreprise.

Erreurs

Voir le tableau des erreurs dans l’aperçu de l’API. Une erreur de validation ressemble à ceci :

{
  "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."]
  }
}

Correspondance client (éviter les doublons)

Pour chaque facture, NumNum vérifie si le client existe déjà, sinon il le crée :

• Avec un numéro de TVA (vat_country_code + vat_id) : correspondance sur votre entreprise + le numéro de TVA normalisé. Le formatage n’a pas d’importance : 0123456789 et 0123.456.789 correspondent au même client.
• Sans numéro de TVA : repli sur la combinaison entreprise + vat_id + email. Utilisez une adresse e-mail cohérente pour éviter les doublons.

⚠️ Si le client existe déjà (correspondance TVA), il n’est pas écrasé par les nouvelles données (nom, adresse, e-mail). Modifiez les données client dans NumNum même.

Points d’attention

• Montants : utilisez un point comme séparateur décimal (1234.56), sans virgule ni séparateur de milliers.
• Dates : format AAAA-MM-JJ avec zéros initiaux (2026-02-05).
• TVA : valeur numérique sans signe % (21, pas "21%" ni 0.21).
• Atomique : si une facture du lot échoue, aucune n’est créée.
• Numérotation automatique : vous ne pouvez pas fournir votre propre numéro de facture.

Types d’entité

Valeurs valides pour client.type (requis uniquement pour les entreprises), notamment : bv, nv, vzw, bvba, cvba, comm.v, comm.va, vof, eenmanszaak, sa, sarl, sas, srl, gmbh, ag, limited-ltd, limited-llc, natuurlijk-persoon, onbekend. Pas sûr ? Utilisez onbekend.

Endpoint obsolète

L’ancien endpoint POST /webhooks/create-invoice (sans /api/v1) fonctionne encore pour les intégrations existantes mais est obsolète : il renvoie une liste brute ([10232, 10233]) et utilise d’autres codes d’erreur (406/401). Migrez vers POST /api/v1/webhooks/create-invoice.