API pour développeurs

L’API de Sage Cloud Demat Invoicing vous permet de créer des documents par programmation dans votre propre environnement Sage Cloud Demat Invoicing. 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 : Sage Cloud Demat Invoicing 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@clouddematinvoicing.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 à Sage Cloud Demat Invoicing
Allez dans Paramètres → Connexions → Mes API (https://www.clouddematinvoicing.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 Sage Cloud Demat Invoicing (p. ex. https://www.clouddematinvoicing.be/company/12345/... → Company ID = 12345).

URL de base & en-têtes

https://www.clouddematinvoicing.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@clouddematinvoicing.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@clouddematinvoicing.be.