Intégration de l'API publique : clés, permissions, champs et recette
Connecter un ERP ou une caisse à l'API publique d'OrdoGrid : clés, identifiant d'intégration, permissions, prix TVAC, envoi Peppol, reprises sûres et recette.
- Mis à jour
- Responsable du contenu
- Équipe intégration
- Pour
- Ingénieurs d'intégration · Architectes de solutions · Responsables financiers d'une intégration
L’essentiel
Créez une clé par intégration, liée à une société, avec les permissions strictement nécessaires et un identifiant d'intégration stable ; faites correspondre les champs pour retrouver vos montants au cent près (prix TVAC compris) ; vérifiez chaque destinataire avant l'envoi Peppol ; validez les reprises, les règlements et la livraison sur de vraies factures avant la mise en production. Il n'existe pas de bac à sable : chaque appel agit sur des données réelles.
Avant de commencer
- Une offre Business incluant l’accès à l’API publique
- Le rôle Propriétaire ou Administrateur dans la société OrdoGrid pour laquelle l'intégration agira
- Une Autorisation Peppol signée pour le numéro de TVA belge de la société, si l'intégration envoie sur Peppol
- Un identifiant source stable pour chaque facture, note de crédit et paiement
- Les montants attendus pour des cas représentatifs, validés par votre contrôleur de gestion ou votre comptable
Résultats attendus
- Une clé aux permissions minimales et un identifiant d'intégration consigné
- Une correspondance des champs qui reproduit vos montants au cent près, arrondi compris
- Une recette réussie couvrant les reprises, la livraison Peppol et les règlements
Sur cette page
L'API publique d'OrdoGrid (/api/v1) permet à un ERP, à une caisse ou à un logiciel de facturation de créer des factures, des notes de crédit et des paiements dans une société OrdoGrid, puis de les envoyer sur Peppol. Ce guide vous mène de la clé à la mise en production : permissions, correspondance des champs au cent près, envoi Peppol, reprises sans doublon et tests à réussir d'abord.
Il s'adresse aux ingénieurs d'intégration et au responsable financier qui valide les montants. Chaque route est décrite dans la référence API, consultable sans connexion, avec son fichier OpenAPI. La politique de reprise et d'incident en production est traitée dans fiabilité des intégrations.
Ce que la loi impose, ce que nous recommandons, ce que fait OrdoGrid
Ce que la loi impose. Depuis le 1er janvier 2026, les entreprises établies en Belgique doivent émettre des factures électroniques structurées pour leurs livraisons et prestations à des clients professionnels identifiés à la TVA en Belgique, en principe au format Peppol BIS via le réseau Peppol (l'obligation en détail). Cette facture structurée est la facture légale ; une copie PDF est facultative. Une note de crédit qui corrige une facture structurée doit aussi passer par Peppol. Si le client ne peut pas recevoir, vous devez tout de même émettre la facture sous une autre forme, par exemple en PDF. Le SPF Finances rappelle que Peppol ne détecte pas les doublons : les éviter vous incombe.
Ce que fait OrdoGrid. L'API construit le XML UBL à partir des champs envoyés, le valide selon EN 16931 et Peppol BIS Billing 3.0.21 avant la livraison, et archive le XML et le PDF exacts transmis. OrdoGrid se connecte à Peppol via un point d'accès certifié, et seules les sociétés disposant d'un numéro de TVA belge (BE) peuvent envoyer. Il n'existe ni bac à sable, ni route qui transforme un PDF en facture, ni opération d'API qui envoie un document par e-mail.
Ce que nous recommandons. Une clé par intégration, les permissions minimales, une identité durable pour chaque événement commercial, une vérification du destinataire avant chaque envoi Peppol et des montants attendus validés avant la mise en production.
Choisir le schéma et les permissions
| Votre situation | Appels principaux | Permissions (scopes) |
|---|---|---|
| L'ERP émet des factures et les envoie sur Peppol | POST /api/v1/invoices, puis POST /api/v1/peppol/invoices/{id}/send ; ou un seul appel à POST /api/v1/peppol/send, avec votre propre pdf si vous en produisez un | invoices:write, peppol:send, peppol:read |
| Caisse avec acomptes, paiements ultérieurs et remboursements | POST /api/v1/invoices avec prepayments, puis .../payments et .../refunds | les précédentes, plus credit_notes:write et payments:write |
| Notes de crédit | POST /api/v1/credit-notes, puis POST /api/v1/peppol/credit-notes/{id}/send | credit_notes:write, peppol:send |
| Reporting ou rapprochement | GET /api/v1/invoices, GET .../payments, GET /api/v1/peppol/documents | invoices:read, peppol:read |
| Factures fournisseurs vers votre système | GET /api/v1/peppol/inbox, GET /api/v1/peppol/documents/{id}/xml | peppol:read |
- Une permission
writeinclutreadsur la même ressource, et rien d'autre :peppol:sendn'inclut paspeppol:read, nécessaire pour vérifier le destinataire, lire le statut de livraison et récupérer le XML échangé. POST /api/v1/peppol/sendexige à la foisinvoices:writeetpeppol:send. Lesprepaymentsd'une nouvelle facture exigent en pluspayments:write, sinon403 INSUFFICIENT_SCOPE.- L'historique des paiements et la recherche d'un mouvement exigent
invoices:read, paspayments:read. - La boîte de réception ne se remplit que si la société reçoit via OrdoGrid (Réception Peppol → Activer la réception).
Créer la clé et consigner son identifiant d'intégration
- Identifiant d'intégration
L'espace de noms d'une clé,
integration_iddans l'API. OrdoGrid enregistre chaqueexternal_idpar société, identifiant d'intégration et type de document : la recherche et la protection contre les doublons ne voient donc que les enregistrements créés sous le même identifiant. Il est fixé à la création, ne peut pas être modifié et survit au renouvellement de la clé.
- Dans le menu du profil, ouvrez Clés API et cliquez sur Créer une clé. Seul un Propriétaire ou un Administrateur peut le faire.
- Saisissez un Nom qui identifie le système, par exemple
Caisse Namur. - Dans Identifiant d'intégration, remplacez la valeur par défaut
defaultpar une valeur stable commepos-namur(1 à 80 lettres, chiffres,_,.ou-). - Cochez uniquement les Permissions du tableau ci-dessus. Laissez Expire le vide pour une clé sans expiration, ou alignez la date sur votre politique de renouvellement.
- Cliquez sur Créer une clé, copiez le secret affiché sous Copiez cette clé maintenant dans votre gestionnaire de secrets, puis cliquez sur Je l'ai enregistrée. Le secret commence par
ik_live_et n'est affiché qu'une fois. - Appelez
GET /api/v1/meet vérifiez le nom et le numéro de TVA de la société,api_key.integration_id,effective_scopes, les devises, les moyens de paiement etrate_limit_per_minute. Conservez la réponse expurgée avec votre correspondance des champs.
curl https://ordogrid.com/api/v1/me -H "Authorization: Bearer ik_live_..."
La clé fonctionne aussi dans l'en-tête X-Api-Key. Les cookies de session de l'application ne fonctionnent pas sur cette API, et c'est la clé elle-même qui identifie la société : il n'y a donc ni en-tête de société, ni moyen d'atteindre une autre société. La liste Clés API n'affiche plus l'identifiant d'intégration après la création, et la page n'offre aucune modification : pour changer les permissions, créez une nouvelle clé avec le même identifiant d'intégration, basculez le connecteur, puis révoquez l'ancienne avec Révoquer.
| Situation | Ce que fait OrdoGrid | Identifiant d'intégration | Ce que vous faites |
|---|---|---|---|
| Renouveler | Nouveau secret avec le même nom, les mêmes permissions, la même expiration et le même identifiant ; l'ancien secret cesse immédiatement de fonctionner | Conservé | Déployez le nouveau secret sans attendre |
| Révoquer, puis Créer une clé | L'ancienne clé s'arrête immédiatement | default, sauf si vous le ressaisissez | Ressaisissez exactement le même identifiant |
| Badge Expirée ou Révoquée | Les appels renvoient 401 API_KEY_EXPIRED ou 401 API_KEY_REVOKED | Reste sur l'ancienne clé | Créez une nouvelle clé avec le même identifiant ; Renouveler conserve une date d'expiration dépassée |
Faire correspondre chaque champ explicitement
| Donnée commerciale | Champ API | Règle |
|---|---|---|
| Votre numéro de commande, de ticket ou de contrat | external_id | 1 à 200 caractères ; jamais réutilisé pour un autre événement commercial |
| Client | client (en ligne) ou client_id | L'un des deux ; pour Peppol, vat_number et une address complète |
| Adresse | street, city, postal_code, country | Les quatre sont nécessaires. Préférez un code ISO à deux lettres, comme BE. Les noms de pays connus en français, néerlandais, anglais ou allemand sont normalisés en ce code ; une valeur inconnue est refusée à la création avec 400 INVALID_COUNTRY |
| Numéro de facture | number | Omettez-le : OrdoGrid attribue le numéro suivant de la série de la société ; un numéro déjà utilisé renvoie 409 DOCUMENT_NUMBER_TAKEN |
| Numéro de commande du client | purchase_order | Devient le BuyerReference UBL |
| Référence de paiement | communication | Devient le PaymentID UBL, et le BuyerReference à défaut de numéro de commande |
| Lignes | items[] : description, quantity, unit_price, vat_rate, vat_type, unit, discount | unit_price est un prix hors TVA |
| Prix TVAC | price_basis: "gross", source_unit_price | Voir ci-dessous |
| Régime de TVA | items[].vat_type, par ligne | standard, reverse_charge, cocontractant, intracommunity, exempt (franchise des petites entreprises), exempt_art44 (exonération de l'art. 44), zero_rated, export, margin ; toute autre valeur renvoie UNKNOWN_VAT_TYPE, et un vat_type au niveau du document est refusé comme champ inconnu |
| Argent reçu à la création | prepayments[] | Factures uniquement ; exige payments:write |
| Votre propre PDF | pdf sur POST /api/v1/peppol/send, ou PUT /api/v1/invoices/{id}/pdf | Envoyé octet pour octet : il doit donc montrer les mêmes montants que les données |
| Facture créditée (notes de crédit) | credit_for_invoice_id, ou credit_for_invoice_number pour une facture émise hors d'OrdoGrid | Obligatoire sur POST /api/v1/credit-notes ; relie la note de crédit à la facture qu'elle corrige |
Comme le BuyerReference se rabat sur la référence de paiement puis sur le numéro de facture, la règle Peppol qui exige une référence acheteur ou une référence de commande (PEPPOL-EN16931-R003) est toujours respectée ; envoyez quand même le numéro de commande du client lorsque vous l'avez. L'API ne choisit pas le régime de TVA : c'est votre système source ou votre comptable qui le fait, selon les régimes de TVA en facturation.
- N'envoyez que les champs prévus. Les champs inconnus, y compris dans
client,addressetitems, sont refusés par un400qui les nomme : un200ou un201signifie donc que tout ce que vous avez envoyé a été appliqué. - Les montants sont des chaînes décimales. EUR, USD et GBP prennent deux décimales, JPY aucune. Une précision excessive sur un mouvement est refusée (
INVALID_AMOUNT_PRECISION), jamais tronquée. Les prix unitaires et les quantités gardent leur précision. - Les heures portent un fuseau.
occurred_atexige un décalage ISO 8601, comme2026-10-02T10:15:00+02:00, sinon l'appel renvoieINVALID_OCCURRENCE_TIME. La Belgique est à UTC+2 jusqu'au 25 octobre 2026, puis à UTC+1. Les réponses écrivent chaque horodatage en UTC, avec millisecondes etZ: ce paiement revient avec2026-10-02T08:15:00.000Z. Convertissez à l'heure locale pour l'affichage ; les jours (issue_date,due_date) restentAAAA-MM-JJ. - Aucune conversion de devise. Un mouvement doit être dans la devise de la facture (
CURRENCY_MISMATCH). Les règles belges de TVA exigent le total de TVA en euros, même sur une facture dans une autre devise : convenez de l'approche avec votre comptable avant d'automatiser ces factures. - Un paiement est un mouvement, pas une étiquette. Un statut payé sans mouvement correspondant est refusé avec
PAYMENT_MOVEMENT_REQUIRED.
Prix TVAC : envoyez le prix que le client a vu
unit_price désigne toujours un prix hors TVA, et prices_include_vat ne change que l'affichage des prix. Une caisse qui envoie "unit_price": "12.50" avec "prices_include_vat": true facture donc 12,50 € plus 21 % de TVA.
Envoyez plutôt "price_basis": "gross" et "source_unit_price": "12.50" ; unit_price n'est alors qu'une valeur de remplissage qui ne remplace pas la source. OrdoGrid calcule le montant net de chaque ligne comme quantité × prix TVAC ÷ (1 + taux de TVA), arrondi au cent, puis la TVA une seule fois par taux sur le total net. L'écart entre votre total TVAC et le net plus la TVA forme totals.rounding, transmis sur Peppol comme montant d'arrondi (BT-114). totals.gross reste le net plus la TVA ; totals.payable est ce que le client doit avant acomptes. Les remises fixes acceptent amount_basis: "net" (par défaut) ou "gross". Les réponses détaillent les remises hors TVA : totals.line_discounts, totals.global_discount et leur somme totals.discounts, le total des réductions imprimé sur le PDF ; global_discount renvoie la remise globale saisie. Sur les lignes à 0 % (autoliquidation, livraisons intracommunautaires, exportations), le prix TVAC égale le prix hors TVA : envoyez-y des prix hors TVA. Détails : prix TVAC, remises et arrondis.
Envoyer sur Peppol : vérifier, envoyer, lire le résultat
Un utilisateur doit d'abord signer l'Autorisation Peppol pour le numéro de TVA de la société, dans le menu Peppol (configurer Peppol dans OrdoGrid) ; sinon, les envois renvoient 403 PEPPOL_APPROVAL_REQUIRED. Les envois sont décomptés du quota Peppol mensuel de l'abonnement (403 PEPPOL_LIMIT_REACHED, compteur et limite dans details). La réception via OrdoGrid n'est pas nécessaire pour envoyer, mais la loi belge exige aussi que votre société puisse recevoir des factures Peppol, via OrdoGrid ou un autre prestataire.
- Vérifiez le destinataire.
GET /api/v1/peppol/participants/BE0123456749renvoieregisteredet, s'il est trouvé, unparticipant_idcomme0208:0123456749. Les sociétés belges sont inscrites sous leur numéro d'entreprise (schéma 0208) : ne demandez pas d'identifiant Peppol distinct à vos clients.registered: falsesignifie qu'aucune inscription n'a pu être confirmée, soit parce que le client n'est pas inscrit sur Peppol, soit parce que la recherche a échoué ; recommencez-la et, au besoin, cherchez0208:suivi du numéro d'entreprise sur lookup.peppol.org. - Envoyez avec
POST /api/v1/peppol/invoices/{id}/send. Facultatif :include_pdf(par défauttrue),attachments(nouveaux fichiers en base64),attachment_ids(fichiers déjà joints à la facture). - Conservez
peppol_document_idde la réponse, à côté dedocument_idet detransmission_state. - Lisez le résultat avec
GET /api/v1/peppol/invoices/{id}/status(status,lifecycle,transmission_state). Dans l'application, le document apparaît dans Peppol → Outbox, où le badge Traité signifie une livraison sur le réseau, pas une acceptation. La plupart des documents arrivent en quelques minutes à quelques heures ; au-delà d'un jour ouvrable, contactez le support OrdoGrid. - Archivez l'UBL échangé avec
GET /api/v1/peppol/documents/{peppol_document_id}/xmlet le PDF transmis avec.../pdf. L'identifiant de facture n'y fonctionne pas.
Si le client n'est pas sur Peppol, créez la facture avec POST /api/v1/invoices, récupérez son PDF avec GET /api/v1/invoices/{id}/pdf et remettez-le par votre propre canal, ou laissez un utilisateur l'envoyer avec Envoyer dans l'application. Une fois le client capable de recevoir, ne renvoyez pas les anciennes factures sur Peppol ; voir client absent de Peppol.
| Route | Usage | Point d'attention |
|---|---|---|
POST /api/v1/peppol/send | Créer et envoyer en un appel | "send": false crée une vraie facture numérotée sans l'envoyer, et exige quand même l'autorisation et un quota disponible |
POST /api/v1/peppol/invoices/{id}/send | Envoyer une facture existante | Un identifiant de note de crédit renvoie 404 |
POST /api/v1/peppol/credit-notes/{id}/send | Envoyer une note de crédit | Part comme CreditNote UBL (type 381) ; un identifiant de facture renvoie 404 |
| Devis, reçus | Aucune | Ce ne sont pas des documents Peppol |
Peppol BIS accepte six types d'annexes : PDF, PNG, JPEG, CSV, XLSX et ODS, et le SPF Finances précise que les annexes voyagent avec la facture, pas séparément par e-mail. Reprenez les attachment_ids dans attachments[] de GET /api/v1/invoices/{id} ; omettez le champ pour joindre tous les fichiers, envoyez [] pour n'en joindre aucun. Un identifiant qui ne correspond à rien est ignoré sans message.
Sécuriser les reprises
| Mécanisme | Portée | Durée | Reprise identique | Contenu différent |
|---|---|---|---|---|
En-tête Idempotency-Key | Une clé API ; les opérations POST qui le documentent | 24 heures | Réponse d'origine, en-tête Idempotent-Replay: true | 409 IDEMPOTENCY_KEY_REUSED |
external_id des factures et notes de crédit | Société, identifiant d'intégration, type de document | Sans expiration ; survit au renouvellement | Première réponse complète | 409 EXTERNAL_ID_REUSED |
external_id des acomptes, paiements, remboursements | Société et identifiant d'intégration, toutes factures confondues | Sans expiration ; survit au renouvellement | Mouvement d'origine, 200, "replayed": true | 409 EXTERNAL_ID_REUSED |
Utilisez les deux. PATCH, PUT et DELETE ne rejouent pas la réponse. Pour les documents, OrdoGrid calcule l'empreinte du corps de création entier, tel qu'envoyé : une note ou une adresse e-mail modifiée, un champ facultatif ajouté, ou 8 au lieu de "8" constituent un contenu différent. Conservez donc le corps envoyé et rejouez-le sans le modifier. Pour les mouvements, ce sont le montant, la devise, le moyen, occurred_at (comparé en UTC) et reference qui comptent.
Après un délai dépassé ou une réponse perdue :
- Cherchez l'identité avec
GET /api/v1/invoices/lookup?external_id=...,GET /api/v1/credit-notes/lookup?external_id=...ouGET /api/v1/invoices/payments/lookup?external_id=.... - Trouvée : utilisez cet enregistrement.
404: rejouez le corps identique. 409 EXTERNAL_OPERATION_IN_PROGRESS: une autre requête est en train de la créer ; attendez, puis rejouez le corps identique (le verrou d'une tentative interrompue expire après deux minutes).502 DOCUMENT_CREATED: le document est enregistré, mais son PDF ou ses annexes n'ont pas été finalisés ; rejouez le mêmeexternal_idet le même corps.- Ne passez jamais à un nouvel
external_idparce qu'une réponse s'est perdue.
PEPPOL_TRANSMISSION_UNCERTAIN signifie qu'OrdoGrid ne peut pas confirmer si le document est parti : lisez son statut et vérifiez la situation avec le support OrdoGrid avant tout nouvel envoi, car un délai dépassé ne prouve pas l'échec et Peppol ne signale pas une seconde copie comme doublon, si bien que le logiciel du client risque de la comptabiliser deux fois.
Les limites de débit s'appliquent par clé et par minute : lisez X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset, et sur 429 RATE_LIMITED, attendez le délai de Retry-After. Parcourez les listes avec limit (100 au maximum) et offset jusqu'à la dernière ligne. Basez votre logique sur le code d'erreur, jamais sur message.
Exemple chiffré : une vente au comptoir avec acompte par carte
Bureau Plus SRL, papeterie de bureau à Namur, connecte sa caisse avec la clé Caisse Namur (identifiant d'intégration pos-namur). Le vendredi 2 octobre 2026 à 10 h 15, le Cabinet Lemaire SRL, fiduciaire identifiée à la TVA sous BE0123456749, emporte 8 cartouches d'encre à 12,50 € TVAC pièce (TVA 21 %), paie 40,00 € par carte et réglera le solde par virement.
1. GET /api/v1/peppol/participants/BE0123456749 renvoie "registered": true et "participant_id": "0208:0123456749".
2. La caisse crée la facture avec le ticket comme identité :
POST /api/v1/invoices
Authorization: Bearer ik_live_...
Idempotency-Key: pos-ticket-2026-0187-create
Content-Type: application/json
{
"external_id": "pos-ticket-2026-0187",
"client": {"name": "Cabinet Lemaire SRL", "vat_number": "BE0123456749",
"address": {"street": "Rue de Fer 12", "city": "Namur", "postal_code": "5000", "country": "BE"}},
"currency": "EUR", "issue_date": "2026-10-02", "due_date": "2026-11-02",
"purchase_order": "LEM-2026-118",
"items": [{"description": "Cartouche d'encre XL noire", "quantity": "8", "unit_price": "0",
"price_basis": "gross", "source_unit_price": "12.50", "vat_rate": 21}],
"prepayments": [{"external_id": "pos-tender-2026-0187-1", "amount": "40.00", "currency": "EUR",
"method": "card", "occurred_at": "2026-10-02T10:15:00+02:00", "reference": "Caisse 2 / ticket 0187"}]
}
3. OrdoGrid calcule :
| Étape | Calcul | Résultat |
|---|---|---|
| Montant convenu | 8 × 12,50 € | 100,00 € |
| Montant net | 100,00 € ÷ 1,21 = 82,6446… €, arrondi | 82,64 € |
| TVA à 21 % | 82,64 € × 21 % = 17,3544 €, arrondi | 17,35 € |
Total légal (totals.gross) | 82,64 € + 17,35 € | 99,99 € |
Arrondi (totals.rounding, BT-114) | 100,00 € − 99,99 € | +0,01 € |
Dû avant acompte (totals.payable, document_total) | 99,99 € + 0,01 € | 100,00 € |
Montant à payer (BT-115, outstanding) | 99,99 € − 40,00 € + 0,01 € | 60,00 € |
La réponse 201 contient le numéro attribué, par exemple F-2026-0412, et :
{
"external_id": "pos-ticket-2026-0187", "integration_id": "pos-namur",
"totals": {"net": 82.64, "vat": 17.35, "gross": 99.99, "rounding": 0.01, "payable": 100.0},
"settlement": {"document_total": "100.00", "prepayments": "40.00", "payments": "40.00",
"credits": "0.00", "outstanding": "60.00", "refund_due": "0.00", "status": "partial"}
}
Les totals sont des nombres JSON et les valeurs de settlement des chaînes décimales : comparez-les tous comme des décimaux. L'acompte est déjà compris dans payments ; n'y ajoutez jamais prepayments. Dans l'application, le panneau Règlement affiche Total de la facture 100,00 €, Acomptes 40,00 €, Paiements (acomptes inclus) 40,00 € et Solde à payer 60,00 €. Les cartouches sont remises à la caisse : les 40,00 € sont donc un paiement partiel. Un acompte perçu avant la livraison rend la TVA exigible à l'encaissement et doit être facturé au plus tard le 15 du mois suivant (facture d'acompte).
4. POST /api/v1/peppol/invoices/{id}/send avec un corps vide. L'UBL porte 0,01 € comme arrondi (BT-114) et 60,00 € comme montant à payer (BT-115), comme l'exige la règle BR-CO-16. Bureau Plus conserve le peppol_document_id.
5. Le lundi 12 octobre 2026, la banque montre 60,00 € reçus du Cabinet Lemaire. POST /api/v1/invoices/{id}/payments avec external_id bank-2026-10-12-07, amount "60.00", method bank_transfer, occurred_at 2026-10-12T09:30:00+02:00 renvoie 201, outstanding "0.00" et status "settled".
6. La caisse, de nouveau en ligne, renvoie l'acompte pos-tender-2026-0187-1 avec des champs identiques à la même route de paiements : OrdoGrid renvoie l'acompte d'origine avec 200 et "replayed": true, et payments reste à "100.00".
| Erreur dans cette vente | Résultat | Correction |
|---|---|---|
"unit_price": "12.50" avec "prices_include_vat": true, sans price_basis | 100,00 € HTVA + 21,00 € de TVA = 121,00 €, soit 21,00 € de trop | Envoyez price_basis et source_unit_price |
Acompte "40.004", ou occurred_at sans décalage | INVALID_AMOUNT_PRECISION, INVALID_OCCURRENCE_TIME | Arrondissez au cent ; ajoutez +02:00 |
| Virement de 60,50 € enregistré en entier | OVERPAYMENT, rien n'est enregistré | Enregistrez 60,00 € ; réglez les 0,50 € en dehors de cette facture |
Reprise reconstruite avec "quantity": 8 au lieu de "8" | 409 EXTERNAL_ID_REUSED | Rejouez le corps conservé |
Préparer un cahier de recette avant la mise en production
Chaque appel crée de vrais documents numérotés et chaque envoi atteint le vrai réseau. Menez la recette sur de vraies transactions avec un client pilote informé, gardez des montants modestes et corrigez les erreurs par note de crédit, via Peppol lorsque la facture est passée par Peppol.
| N° | Cas | Résultat attendu |
|---|---|---|
| 1 | Prix hors TVA à chaque taux que vous utilisez | Net, TVA et total identiques à votre source au cent près ; numéro dans la série de la société |
| 2 | Prix TVAC (l'exemple chiffré) | rounding 0,01 et payable 100,00 |
| 3 | Arrondi négatif : 10 × 12,50 € TVAC à 21 % | Net 103,31 €, TVA 21,70 €, total légal 125,01 €, arrondi −0,01 €, à payer 125,00 € |
| 4 | Note de crédit partielle | Envoyée comme CreditNote UBL ; outstanding diminue ; créditer plus que le solde renvoie CREDIT_CAPACITY_EXCEEDED |
| 5 | Note de crédit sur une facture payée, puis remboursement | refund_due apparaît, puis revient à zéro |
| 6 | Acompte, paiement, acompte rejoué | L'acompte n'est jamais compté deux fois |
| 7 | Création rejouée avant et après 24 heures ; réponse perdue après validation | Même facture et même numéro à chaque fois ; la recherche la retrouve |
| 8 | Corps modifié sous un external_id existant | 409 EXTERNAL_ID_REUSED ; rien n'est créé |
| 9 | Client absent de Peppol | registered: false ; canal de repli utilisé ; aucune tentative Peppol |
| 10 | Livraison et preuves | Statut lu jusqu'à la livraison ; XML récupéré avec peppol_document_id |
| 11 | Clé remplacée avec le même identifiant d'intégration | La recherche retrouve les factures antérieures |
| 12 | Permission manquante, adresse partielle, champ inconnu | 403 INSUFFICIENT_SCOPE ; 400 qui nomme le champ |
Faites valider les montants attendus par le contrôleur de gestion avant la recette et ne lancez la production que lorsque chaque écart est expliqué.
Cas particuliers et erreurs fréquentes
| Erreur | Conséquence | Action correcte |
|---|---|---|
Numéros de paiement de la caisse qui repartent de 1 chaque jour, utilisés comme external_id | 409 EXTERNAL_ID_REUSED dès le deuxième jour, car les identifiants de mouvement sont uniques toutes factures confondues | Construisez des identifiants qui ne se répètent jamais, par exemple année plus numéro de ticket, comme dans l'exemple |
Numéros de l'ERP envoyés dans number alors que des utilisateurs créent aussi des factures dans l'application | Trous ou 409 DOCUMENT_NUMBER_TAKEN dans la même série | Confiez la série de factures à un seul système ; omettez number |
Montants modifiés par PATCH après un paiement ou un envoi Peppol | DOCUMENT_FINANCIAL_CONTENTS_LOCKED | Note de crédit et, au besoin, nouvelle facture |
| Note de crédit d'une facture Peppol envoyée uniquement en PDF | Ce n'est pas le format structuré exigé par la loi | Envoyez-la avec POST /api/v1/peppol/credit-notes/{id}/send |
| Traité ou « livré » compris comme une acceptation | Relance d'une facture que l'acheteur a rejetée | Suivez les Invoice Responses sur la page Peppol ; elles n'arrivent dans OrdoGrid que si la société y reçoit (Activer la réception), et l'acheteur n'est pas tenu d'en envoyer |
| PDF envoyé par e-mail en plus de l'envoi Peppol | Le client risque de comptabiliser la facture deux fois | Peppol seul lorsque le client y reçoit ; les prestataires de services Peppol belges recommandent d'éviter le double envoi |
Preuves à conserver
- Registre des clés : nom, identifiant d'intégration, permissions, responsable, dates de création et de renouvellement ; jamais le secret.
- Instantané du contrat : la réponse
/meexpurgée, avec sa date etcontract_version, plus la correspondance des champs versionnée et les montants attendus validés. - Par transaction :
external_id,idet numéro OrdoGrid,peppol_document_id, le corps exact envoyé, le code de réponse et lecodede tout refus. - Catalogue des refus : pour chaque code rencontré pendant la recette, une requête expurgée, le
codeet la reprise choisie. Après une modification de la correspondance des champs, rejouez les cas de reprise : un nouveau champ modifie le corps des documents encore en attente de reprise. - Documents et encaissements : le XML et le PDF échangés, le PDF émis (
GET /api/v1/invoices/{id}/pdf?view=original), un relevé daté au besoin (?view=current) et l'historique des mouvements (GET /api/v1/invoices/{id}/payments).
La loi belge impose de conserver les factures pendant 7 ans à compter du 1er janvier de l'année qui suit leur émission (art. 60 du Code de la TVA, modifié par la loi du 18 décembre 2025), et le SPF Finances recommande vivement de garder le XML d'origine. OrdoGrid archive le XML et le PDF exacts de chaque transmission avec leurs empreintes, mais n'est pas un service d'archivage légal : conservez vos propres copies.
Questions fréquentes
Existe-t-il un bac à sable ou un mode test ?
Non. Chaque appel agit sur les données réelles de la société et chaque envoi atteint le vrai réseau Peppol ; "send": false crée tout de même une vraie facture numérotée. Testez sur de vraies transactions avec un client pilote et corrigez les erreurs par note de crédit.
Que devient mon intégration quand je renouvelle une clé ?
L'ancien secret cesse immédiatement de fonctionner : déployez le nouveau sans attendre. Le renouvellement conserve l'identifiant d'intégration, les permissions et la date d'expiration, si bien que la recherche et la protection contre les doublons continuent de fonctionner.
Pourquoi reçois-je EXTERNAL_ID_REUSED alors que je n'ai changé qu'une note ?
OrdoGrid calcule l'empreinte du corps de création entier, pas seulement des montants. Rejouez le corps conservé. Si l'événement commercial a réellement changé, traitez-le comme une correction : une note de crédit et, au besoin, une nouvelle facture avec un nouvel external_id.
L'API peut-elle envoyer par e-mail une facture à un client absent de Peppol ?
Non, l'API publique n'a pas d'opération d'e-mail. Récupérez le PDF avec GET /api/v1/invoices/{id}/pdf et envoyez-le par votre propre canal, ou laissez un utilisateur l'envoyer depuis l'application avec Envoyer.
Un statut livré signifie-t-il que le client a accepté la facture ?
Non, il signifie une livraison sur le réseau. L'acceptation ou le rejet n'arrive que par une Invoice Response, que l'acheteur n'est pas tenu d'envoyer, et le paiement uniquement par un mouvement enregistré.
Mon système peut-il recevoir les factures fournisseurs par l'API ?
Oui, avec peppol:read, via GET /api/v1/peppol/inbox et la route XML, à condition que la société reçoive via OrdoGrid. OrdoGrid ne comptabilise ni n'approuve les factures fournisseurs : cela reste dans votre logiciel comptable.
Sources et références
- OrdoGrid – Référence de l'API publique
- OpenPeppol – Peppol BIS Billing 3.0
- SPF Finances – FAQ Questions générales sur Peppol (identifiant 0208, recherche, délais)
- SPF Finances – FAQ Questions générales sur l'obligation B2B (client pas prêt, PDF, annexes)
- SPF Finances – FAQ Questions spécifiques sur l'e-facturation (notes de crédit, doublons)
- SPF Finances – Comment conserver les factures reçues par facturation électronique ?