Procédure24 min de lecture

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 situationAppels principauxPermissions (scopes)
L'ERP émet des factures et les envoie sur PeppolPOST /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 uninvoices:write, peppol:send, peppol:read
Caisse avec acomptes, paiements ultérieurs et remboursementsPOST /api/v1/invoices avec prepayments, puis .../payments et .../refundsles précédentes, plus credit_notes:write et payments:write
Notes de créditPOST /api/v1/credit-notes, puis POST /api/v1/peppol/credit-notes/{id}/sendcredit_notes:write, peppol:send
Reporting ou rapprochementGET /api/v1/invoices, GET .../payments, GET /api/v1/peppol/documentsinvoices:read, peppol:read
Factures fournisseurs vers votre systèmeGET /api/v1/peppol/inbox, GET /api/v1/peppol/documents/{id}/xmlpeppol:read
  • Une permission write inclut read sur la même ressource, et rien d'autre : peppol:send n'inclut pas peppol:read, nécessaire pour vérifier le destinataire, lire le statut de livraison et récupérer le XML échangé.
  • POST /api/v1/peppol/send exige à la fois invoices:write et peppol:send. Les prepayments d'une nouvelle facture exigent en plus payments:write, sinon 403 INSUFFICIENT_SCOPE.
  • L'historique des paiements et la recherche d'un mouvement exigent invoices:read, pas payments: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_id dans l'API. OrdoGrid enregistre chaque external_id par 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é.

  1. 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.
  2. Saisissez un Nom qui identifie le système, par exemple Caisse Namur.
  3. Dans Identifiant d'intégration, remplacez la valeur par défaut default par une valeur stable comme pos-namur (1 à 80 lettres, chiffres, _, . ou -).
  4. 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.
  5. 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.
  6. Appelez GET /api/v1/me et 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 et rate_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.

SituationCe que fait OrdoGridIdentifiant d'intégrationCe que vous faites
RenouvelerNouveau 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 fonctionnerConservéDéployez le nouveau secret sans attendre
Révoquer, puis Créer une cléL'ancienne clé s'arrête immédiatementdefault, sauf si vous le ressaisissezRessaisissez exactement le même identifiant
Badge Expirée ou RévoquéeLes appels renvoient 401 API_KEY_EXPIRED ou 401 API_KEY_REVOKEDReste 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 commercialeChamp APIRègle
Votre numéro de commande, de ticket ou de contratexternal_id1 à 200 caractères ; jamais réutilisé pour un autre événement commercial
Clientclient (en ligne) ou client_idL'un des deux ; pour Peppol, vat_number et une address complète
Adressestreet, city, postal_code, countryLes 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 facturenumberOmettez-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 clientpurchase_orderDevient le BuyerReference UBL
Référence de paiementcommunicationDevient le PaymentID UBL, et le BuyerReference à défaut de numéro de commande
Lignesitems[] : description, quantity, unit_price, vat_rate, vat_type, unit, discountunit_price est un prix hors TVA
Prix TVACprice_basis: "gross", source_unit_priceVoir ci-dessous
Régime de TVAitems[].vat_type, par lignestandard, 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éationprepayments[]Factures uniquement ; exige payments:write
Votre propre PDFpdf sur POST /api/v1/peppol/send, ou PUT /api/v1/invoices/{id}/pdfEnvoyé 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'OrdoGridObligatoire 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, address et items, sont refusés par un 400 qui les nomme : un 200 ou un 201 signifie 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_at exige un décalage ISO 8601, comme 2026-10-02T10:15:00+02:00, sinon l'appel renvoie INVALID_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 et Z : ce paiement revient avec 2026-10-02T08:15:00.000Z. Convertissez à l'heure locale pour l'affichage ; les jours (issue_date, due_date) restent AAAA-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.

  1. Vérifiez le destinataire. GET /api/v1/peppol/participants/BE0123456749 renvoie registered et, s'il est trouvé, un participant_id comme 0208: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: false signifie 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, cherchez 0208: suivi du numéro d'entreprise sur lookup.peppol.org.
  2. Envoyez avec POST /api/v1/peppol/invoices/{id}/send. Facultatif : include_pdf (par défaut true), attachments (nouveaux fichiers en base64), attachment_ids (fichiers déjà joints à la facture).
  3. Conservez peppol_document_id de la réponse, à côté de document_id et de transmission_state.
  4. 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.
  5. Archivez l'UBL échangé avec GET /api/v1/peppol/documents/{peppol_document_id}/xml et 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.

RouteUsagePoint d'attention
POST /api/v1/peppol/sendCré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}/sendEnvoyer une facture existanteUn identifiant de note de crédit renvoie 404
POST /api/v1/peppol/credit-notes/{id}/sendEnvoyer une note de créditPart comme CreditNote UBL (type 381) ; un identifiant de facture renvoie 404
Devis, reçusAucuneCe 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écanismePortéeDuréeReprise identiqueContenu différent
En-tête Idempotency-KeyUne clé API ; les opérations POST qui le documentent24 heuresRéponse d'origine, en-tête Idempotent-Replay: true409 IDEMPOTENCY_KEY_REUSED
external_id des factures et notes de créditSociété, identifiant d'intégration, type de documentSans expiration ; survit au renouvellementPremière réponse complète409 EXTERNAL_ID_REUSED
external_id des acomptes, paiements, remboursementsSociété et identifiant d'intégration, toutes factures confonduesSans expiration ; survit au renouvellementMouvement d'origine, 200, "replayed": true409 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 :

  1. Cherchez l'identité avec GET /api/v1/invoices/lookup?external_id=..., GET /api/v1/credit-notes/lookup?external_id=... ou GET /api/v1/invoices/payments/lookup?external_id=....
  2. Trouvée : utilisez cet enregistrement. 404 : rejouez le corps identique.
  3. 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).
  4. 502 DOCUMENT_CREATED : le document est enregistré, mais son PDF ou ses annexes n'ont pas été finalisés ; rejouez le même external_id et le même corps.
  5. Ne passez jamais à un nouvel external_id parce 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 :

ÉtapeCalculRésultat
Montant convenu8 × 12,50 €100,00 €
Montant net100,00 € ÷ 1,21 = 82,6446… €, arrondi82,64 €
TVA à 21 %82,64 € × 21 % = 17,3544 €, arrondi17,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 venteRésultatCorrection
"unit_price": "12.50" avec "prices_include_vat": true, sans price_basis100,00 € HTVA + 21,00 € de TVA = 121,00 €, soit 21,00 € de tropEnvoyez price_basis et source_unit_price
Acompte "40.004", ou occurred_at sans décalageINVALID_AMOUNT_PRECISION, INVALID_OCCURRENCE_TIMEArrondissez au cent ; ajoutez +02:00
Virement de 60,50 € enregistré en entierOVERPAYMENT, 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_REUSEDRejouez 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°CasRésultat attendu
1Prix hors TVA à chaque taux que vous utilisezNet, TVA et total identiques à votre source au cent près ; numéro dans la série de la société
2Prix TVAC (l'exemple chiffré)rounding 0,01 et payable 100,00
3Arrondi négatif : 10 × 12,50 € TVAC à 21 %Net 103,31 €, TVA 21,70 €, total légal 125,01 €, arrondi −0,01 €, à payer 125,00 €
4Note de crédit partielleEnvoyée comme CreditNote UBL ; outstanding diminue ; créditer plus que le solde renvoie CREDIT_CAPACITY_EXCEEDED
5Note de crédit sur une facture payée, puis remboursementrefund_due apparaît, puis revient à zéro
6Acompte, paiement, acompte rejouéL'acompte n'est jamais compté deux fois
7Création rejouée avant et après 24 heures ; réponse perdue après validationMême facture et même numéro à chaque fois ; la recherche la retrouve
8Corps modifié sous un external_id existant409 EXTERNAL_ID_REUSED ; rien n'est créé
9Client absent de Peppolregistered: false ; canal de repli utilisé ; aucune tentative Peppol
10Livraison et preuvesStatut lu jusqu'à la livraison ; XML récupéré avec peppol_document_id
11Clé remplacée avec le même identifiant d'intégrationLa recherche retrouve les factures antérieures
12Permission manquante, adresse partielle, champ inconnu403 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

ErreurConséquenceAction correcte
Numéros de paiement de la caisse qui repartent de 1 chaque jour, utilisés comme external_id409 EXTERNAL_ID_REUSED dès le deuxième jour, car les identifiants de mouvement sont uniques toutes factures confonduesConstruisez 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'applicationTrous ou 409 DOCUMENT_NUMBER_TAKEN dans la même sérieConfiez la série de factures à un seul système ; omettez number
Montants modifiés par PATCH après un paiement ou un envoi PeppolDOCUMENT_FINANCIAL_CONTENTS_LOCKEDNote de crédit et, au besoin, nouvelle facture
Note de crédit d'une facture Peppol envoyée uniquement en PDFCe n'est pas le format structuré exigé par la loiEnvoyez-la avec POST /api/v1/peppol/credit-notes/{id}/send
Traité ou « livré » compris comme une acceptationRelance d'une facture que l'acheteur a rejetéeSuivez 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 PeppolLe client risque de comptabiliser la facture deux foisPeppol 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 /me expurgée, avec sa date et contract_version, plus la correspondance des champs versionnée et les montants attendus validés.
  • Par transaction : external_id, id et numéro OrdoGrid, peppol_document_id, le corps exact envoyé, le code de réponse et le code de tout refus.
  • Catalogue des refus : pour chaque code rencontré pendant la recette, une requête expurgée, le code et 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