API pour développeurs

L’API de NumNum vous permet de créer des documents par programmation dans votre propre environnement NumNum. Une fois créés, vous pouvez envoyer ces documents par e-mail, Peppol ou courrier, exactement comme les documents que vous créez manuellement.

L’API est conçue pour des intégrations serveur à serveur, par exemple :

E-commerce : créer automatiquement une facture après une vente en ligne
ERP / CRM : créer des factures depuis votre système existant
Autofacturation (self-billing) : décomptes périodiques (bordereaux d’achat) pour vos fournisseurs, p. ex. coopératives ou producteurs
Flux personnalisés : intégrer la création de factures dans votre propre application

Que peut faire l’API ?

L’API est en écriture seule : elle sert à créer des documents. Il existe trois endpoints :

Quoi	Endpoint	Documentation
Créer des factures de vente	`POST /api/v1/webhooks/create-invoice`	Créer des factures
Créer un bordereau d’achat émis (autofacturation)	`POST /api/v1/webhooks/create-purchase-borderelle`	Autofacturation / bordereau d’achat
Créer une note de crédit sur un bordereau d’achat	`POST /api/v1/webhooks/create-purchase-borderelle-creditnote`	Autofacturation / bordereau d’achat

Ce qui n’est pas possible via l’API

Pour bien cadrer les attentes :

❌ Lire, modifier ou supprimer des documents n’est pas possible avec votre jeton API personnel. L’API sert uniquement à créer des documents.
❌ Fournir vos propres numéros de document n’est pas possible : NumNum numérote automatiquement selon vos paramètres d’entreprise (séquence ininterrompue légalement obligatoire).
❌ L’idempotence n’est pas intégrée : envoyer deux fois la même charge utile crée deux documents. Suivez vous-même ce que vous avez déjà soumis (p. ex. via le champ reference ou les identifiants renvoyés).

ℹ️ L’envoi via Peppol ou e-mail ne fait pas partie de cette API ; il se fait ensuite dans l’application ou votre flux d’envoi habituel.

Accès

Vous générez vous-même votre jeton API sur la page Mes API dans les paramètres de votre entreprise (voir Authentification). Vous ne voyez pas cette page ? Contactez le support (help@numnum.be).

Authentification

Chaque requête API nécessite deux en-têtes : votre jeton API personnel et l’entreprise pour laquelle vous travaillez.

1. Jeton API personnel

Connectez-vous à NumNum
Allez dans Paramètres → Connexions → Mes API (https://app.numnum.be/company/connection/myapi)
Cliquez sur Générer un jeton API

Quelques propriétés importantes :

Le jeton est une chaîne d’exactement 64 caractères (chiffres et lettres). Copiez toujours la valeur complète telle qu’affichée sur la page ; elle y reste visible tant que vous n’en générez pas un nouveau.
Le jeton appartient à votre utilisateur, pas à une seule entreprise. Le même jeton fonctionne pour toutes les entreprises auxquelles vous avez accès ; vous choisissez l’entreprise par requête via l’en-tête X-Company-Id.
Il n’y a pas de bouton « révoquer » distinct : cliquer à nouveau sur Générer un jeton API crée un nouveau jeton et invalide immédiatement le précédent.
Traitez le jeton comme un mot de passe : stockez-le dans une variable d’environnement / un gestionnaire de secrets, ne le partagez jamais par e-mail ou chat, et ne le validez jamais dans git.

2. Company ID

Votre X-Company-Id détermine dans quelle entreprise le document est créé. Vous le trouvez :

à côté de votre jeton sur la page Mes API, ou
dans l’URL de NumNum (p. ex. https://app.numnum.be/company/12345/... → Company ID = 12345).

URL de base & en-têtes

https://app.numnum.be/api/v1

En-tête	Requis	Exemple
`Authorization`	Oui	`Bearer <votre-jeton-api>`
`X-Company-Id`	Oui	`12345`
`Content-Type`	Oui	`application/json`
`Accept`	Recommandé	`application/json`

Attention à l’espace entre Bearer et le jeton.

Gestion des erreurs

Considérez seulement HTTP 201 comme un succès. Tout autre code signifie que le document n’a pas été créé ; mettez la requête en file d’attente et réessayez plus tard (avec un back-off exponentiel pour 429 et 5xx).

Statut	Signification	Corps de la réponse
`201 Created`	Document(s) créé(s)	`{ "invoices": [1234] }` (selon l’endpoint)
`400 Bad Request`	En-têtes manquants	`{ "error": "Required headers are missing." }`
`400 Bad Request`	Format `Authorization` incorrect	`{ "error": "Authorization header format is invalid." }`
`400 Bad Request`	Erreur de validation dans la charge utile	`{ "error": "invalid_body", "errors": { "0.client.email": ["..."] } }`
`401 Unauthorized`	Jeton API invalide	`{ "error": "Invalid API token." }`
`403 Forbidden`	Votre utilisateur n’a pas accès à cette entreprise	`{ "error": "Access to this company is forbidden." }`
`404 Not Found`	Company ID inconnu	`{ "error": "Invalid company ID." }`
`429 Too Many Requests`	Limite de débit ou limite mensuelle atteinte	`{ "error": "Monthly API document limit reached." }`
`500`	Erreur serveur inattendue	Contactez help@numnum.be

Pour les erreurs de validation (400 invalid_body), la clé pointe vers la position dans le tableau et le champ, p. ex. 0.client.email = premier document, champ client.email.

Limites & quotas

Lot (batch) : une requête contient un tableau de documents (max 50 par requête). Le traitement est atomique : si un document échoue, aucun document n’est créé.
Limite de débit (par entreprise) : 30 requêtes par minute et 2000 par jour.
Limite mensuelle : un nombre maximum de documents par mois s’applique (valeur indicative ± 200/mois). Un dépassement renvoie 429.
Limitez les requêtes parallèles (± 5 à la fois) pour ne pas surcharger le serveur.

Endpoint obsolète (legacy)

Un ancien endpoint, POST /webhooks/create-invoice (sans /api/v1), existe encore pour les intégrations existantes. Il utilise le même jeton mais renvoie une liste brute ([10232, 10233]) et d’autres codes d’erreur (406, 401). Cet endpoint est obsolète ; pour les nouvelles intégrations, utilisez toujours POST /api/v1/webhooks/create-invoice.

Étapes suivantes

Des questions ? Contactez help@numnum.be.