Intégrations fiables : reprises, envois incertains et rapprochement
Relancer un appel API OrdoGrid sans doublon de facture ni de paiement : external_id stable, identifiant d'intégration, Idempotency-Key, envoi Peppol incertain.
- Mis à jour
- Responsable du contenu
- Exploitation intégration
- Pour
- Développeurs d'intégration · Exploitation des intégrations · Contrôleurs financiers
L’essentiel
Donnez à chaque événement métier un external_id stable sous un identifiant d'intégration fixe, classez chaque réponse d'après son code avant toute nouvelle tentative et recherchez l'événement après tout délai dépassé. Après une réponse perdue, ne créez jamais de nouvel identifiant, et suspendez tout envoi Peppol incertain jusqu'à ce qu'OrdoGrid en ait confirmé l'issue.
Avant de commencer
- Une offre Business incluant l’accès à l’API publique
- Une clé API OrdoGrid limitée aux permissions nécessaires, avec un identifiant d'intégration connu
- Un système source capable de dériver un identifiant stable par facture, note de crédit et paiement
- Des journaux de requêtes et réponses expurgés, et un responsable désigné pour la file de reprise
Résultats attendus
- Une politique de reprise pilotée par les codes d'erreur, avec des limites et des délais testés
- Aucun doublon de facture, de note de crédit ou de paiement après un délai dépassé, un plantage ou un renouvellement de clé
- Une file surveillée où chaque élément suspendu a un responsable et une décision
Sur cette page
Une intégration est fiable lorsqu'elle sait retrouver une transaction métier après une réponse HTTP perdue, un traitement interrompu ou une remise Peppol au résultat flou, sans créer une deuxième facture, un deuxième paiement ou une deuxième transmission. « Réessayer trois fois » ne suffit pas : certaines requêtes sont refusées avant toute écriture, d'autres échouent alors qu'OrdoGrid a déjà numéroté la facture ou enregistré l'encaissement. Cette procédure indique quelles identités conserver, comment classer chaque réponse, quand réessayer, quand suspendre et que surveiller.
Elle s'adresse aux développeurs et aux exploitants de connecteurs bâtis sur l'API publique d'OrdoGrid (/api/v1). Les clés, les permissions et la correspondance des données sont traitées dans Intégration API publique ; la coordination d'un incident en cours dans Incident de facturation ; le sens des badges dans Statut de livraison Peppol. Le contrat complet figure dans la référence de l'API.
Pourquoi un doublon coûte cher
| Ce qui s'applique | |
|---|---|
| La loi | Chaque facture porte un numéro séquentiel unique et est inscrite au journal des sorties (arrêté royal n° 1, art. 5, §1er, 1°) ; elle est émise au plus tard le 15 du mois qui suit le fait générateur (art. 4, §1er). Un document qui rectifie une facture structurée est émis dans le même format (art. 53, §2bis du Code de la TVA) : un doublon envoyé sur Peppol se corrige donc par une note de crédit sur Peppol (FAQ, Q5), et non par une suppression. |
| SPF Finances | Peppol ne reconnaît pas les doublons ; les détecter incombe à l'utilisateur et à son logiciel (FAQ questions spécifiques, Q4). La livraison prend en général de quelques minutes à quelques heures ; un retard de plus d'un jour ouvrable se signale au fournisseur du logiciel (FAQ Peppol, Q9). |
| OrdoGrid | Des identités external_id durables, un rejeu Idempotency-Key de 24 heures, une seule transmission sortante par facture et un blocage de tout renvoi tant que l'issue reste floue. Ces garde-fous ne fonctionnent que si votre connecteur conserve les mêmes identités. |
| Notre recommandation | Le registre, les limites de reprise, les suspensions et les alertes ci-dessous : des suggestions à adapter à vos volumes, pas des engagements de service d'OrdoGrid. |
Quatre garde-fous et leurs limites
| Garde-fou | Portée et durée | Empêche | N'empêche pas |
|---|---|---|---|
En-tête Idempotency-Key | La clé API appelante ; 24 heures | Une deuxième exécution du même POST : une répétition identique renvoie le succès enregistré avec Idempotent-Replay: true | Un autre contenu sous la même clé (409 IDEMPOTENCY_KEY_REUSED) ; une nouvelle exécution après un appel en échec (la clé est libérée) ; PATCH, PUT, DELETE ; une répétition sous une clé renouvelée |
external_id de document | Société, Identifiant d'intégration et type de document ; sans expiration, survit au renouvellement | Une deuxième facture ou note de crédit pour la même transaction source | Un nouvel identifiant ; un autre Identifiant d'intégration ; toute modification du contenu de création (409 EXTERNAL_ID_REUSED) |
external_id de mouvement | Société et Identifiant d'intégration, toutes factures et tous types de mouvements confondus ; sans expiration | Compter deux fois le même encaissement : une répétition renvoie l'original avec replayed: true | Un changement de montant, de devise, de mode de paiement, de date et heure de l'opération ou de référence, ou le même identifiant sur une autre facture (EXTERNAL_ID_REUSED) |
| Garde-fou de transmission Peppol | Une transmission par facture ou note de crédit | Une deuxième transmission : un envoi accepté revient avec replayed: true, un envoi incertain est refusé | Une nouvelle facture pour la même vente ; un PDF envoyé par e-mail |
Utilisez les deux : Idempotency-Key rend une répétition immédiate peu coûteuse, external_id permet de reprendre après 24 heures ou après un changement de clé. L'API accepte des documents sans external_id, mais considérez-le comme obligatoire ; pour les mouvements, il l'est.
- Identifiant d'intégration
- L'espace de noms d'une clé API (
integration_iddans l'API, Identifiant d'intégration sur la page Clés API). Chaqueexternal_idest recherché dans l'espace de noms de la clé appelante. Jusqu'à 80 lettres, chiffres,_,.ou-; fixé à la création ; le champ vautdefaultpar défaut.
Tenir un registre des identités
Tenez une ligne par événement métier, pas par requête HTTP : événement source et external_id (SO-58213), identifiant d'intégration (erp-prod), type de document, contenu exact envoyé ou son empreinte SHA-256, Idempotency-Key, id, number et peppol_document_id OrdoGrid, chaque mouvement avec tous ses champs, le dernier résultat avec heure UTC et code, l'état dans la file et son responsable.
- Dérivez l'identifiant de l'événement métier (1 à 200 caractères). Un UUID par requête désactive tous les garde-fous ci-dessus.
- Figez le contenu lors du premier envoi et renvoyez-le tel quel. OrdoGrid calcule l'empreinte de tout le contenu de création : un ERP qui reconstruit la requête avec une adresse e-mail ou une échéance corrigée déclenche
EXTERNAL_ID_REUSED. - Omettez
numberpour que la série de la société l'attribue. Vos propres numéros, combinés à une répétition sansexternal_id, donnent409 DOCUMENT_NUMBER_TAKEN. - Placez une référence source lisible dans le champ
referencede chaque mouvement ; la comptabilité la voit dans l'Historique des mouvements du panneau Règlement de la facture. Gardez-la identique à chaque répétition. - Protégez le registre. Une correction est une nouvelle ligne qui renvoie à l'ancienne, jamais un identifiant modifié.
Garder l'espace de noms lors d'un changement de clé
Sur la page Clés API (propriétaires et administrateurs) :
- Renouveler crée une nouvelle clé avec le même nom, les mêmes Permissions, la même date d'expiration et le même Identifiant d'intégration ; l'ancienne clé cesse immédiatement de fonctionner. Copiez le nouveau secret sous Copiez cette clé maintenant : il n'est affiché qu'une fois.
- Une clé de remplacement créée avec Créer une clé doit recevoir exactement l'ancien Identifiant d'intégration. Si elle reste à
default, ses recherches répondent404et les répétitions créent de nouvelles factures ou de nouveaux paiements. - La liste des clés n'affiche pas l'identifiant d'intégration : appelez
GET /api/v1/meet comparezapi_key.integration_idavec votre registre avant de redémarrer. - Les enregistrements de rejeu HTTP appartiennent à l'ancienne clé ; après un renouvellement, reprenez par la recherche sur
external_id.
Classer chaque résultat avant de réessayer
Basez-vous sur le code d'erreur, jamais sur le texte du message. Tout cas absent de ces tableaux : considérez l'issue comme inconnue et recherchez l'événement.
Documents et mouvements de trésorerie
| Réponse | Enregistré ? | Action |
|---|---|---|
201 ; ou Idempotent-Replay: true ou replayed: true (200 pour les mouvements) | Oui | Enregistrez id et number. Un rejeu redonne le premier résultat : ce n'est ni une nouvelle vente ni un nouveau paiement |
Délai dépassé, connexion coupée, 5xx sans code repris ici | Inconnu | Recherchez par external_id avant toute autre chose : GET /api/v1/invoices/lookup ou /api/v1/credit-notes/lookup pour les documents, GET /api/v1/invoices/payments/lookup pour les mouvements |
400 VALIDATION_ERROR, UNKNOWN_FIELD, INVALID_AMOUNT_PRECISION, CURRENCY_MISMATCH, INVALID_OCCURRENCE_TIME, UNKNOWN_VAT_TYPE | Non | Corrigez la correspondance ; renvoyez le contenu corrigé sous le même external_id (s'il revient EXTERNAL_ID_REUSED, voir les cas particuliers). Pas de reprise automatique |
401 API_KEY_EXPIRED, API_KEY_REVOKED, INVALID_API_KEY ; 403 INSUFFICIENT_SCOPE | Non | Arrêtez la file. INVALID_API_KEY : vérifiez le secret configuré. Clé révoquée par Renouveler : installez le nouveau secret. Clé expirée ou révoquée pour une autre raison, ou Permissions insuffisantes : Renouveler ne sert à rien (cette action conserve les permissions et la date d'expiration, et n'est pas proposée pour une clé expirée ou révoquée) ; créez donc une nouvelle clé avec Créer une clé, saisissez exactement l'ancien Identifiant d'intégration, vérifiez-le avec GET /api/v1/me, puis reprenez avec les mêmes identités |
429 RATE_LIMITED | Non | Attendez Retry-After secondes ; ralentissez |
409 IDEMPOTENT_REQUEST_IN_PROGRESS | Premier appel toujours en cours | Attendez quelques secondes ; réessayez avec la même clé et le même contenu |
409 EXTERNAL_OPERATION_IN_PROGRESS | Un autre appel détient l'identité | Attendez plus de deux minutes (le verrou d'exécution), puis recherchez |
409 IDEMPOTENCY_KEY_REUSED ou EXTERNAL_ID_REUSED | Première version existante ou réservée | Suspendez ; comparez le contenu enregistré et le nouveau ; ne contournez jamais par une nouvelle clé ou un nouvel identifiant |
409 SETTLEMENT_CONFLICT | Non | Modification simultanée de la facture ; réessayez avec le même external_id après une temporisation |
409 OVERPAYMENT, OVER_REFUND | Non | Ne réessayez pas ; vérifiez si l'encaissement a déjà été enregistré sous un autre identifiant |
409 DOCUMENT_FINANCIAL_CONTENTS_LOCKED lors d'une modification | Non | Un paiement est enregistré, la facture est préparée pour Peppol ou envoyée sur Peppol, ou le document est une note de crédit enregistrée : ne modifiez pas ; corrigez par une nouvelle note de crédit ou une nouvelle facture |
502 DOCUMENT_CREATED | Oui, PDF ou pièces jointes inachevés | Renvoyez le contenu identique sous le même external_id pour l'achever ; sans external_id, utilisez details.document_id et ne créez plus jamais |
Les limites de débit s'appliquent par clé et par minute (120 par défaut) ; lisez X-RateLimit-Remaining et X-RateLimit-Reset (en secondes) plutôt que de coder ce chiffre en dur.
Envois Peppol
Lisez GET /api/v1/peppol/invoices/{id}/status (ou l'équivalent pour les notes de crédit) avec la permission peppol:read. transmission_state décrit la remise d'OrdoGrid à son point d'accès ; status suit la livraison et correspond aux badges de Peppol → Outbox (processed correspond à Traité).
Code ou transmission_state | Signification | Action |
|---|---|---|
403 PEPPOL_APPROVAL_REQUIRED, PEPPOL_LIMIT_REACHED | Rien n'a été créé ni envoyé | Signez l'Autorisation Peppol ou changez de plan dans Facturation & Abonnement ; renvoyez la même requête |
PEPPOL_CLIENT_NOT_FOUND | Rien n'est transmis ; avec POST /api/v1/peppol/send, la facture existe déjà | Vérifiez le numéro de TVA avec GET /api/v1/peppol/participants/{vat_number}, puis envoyez la facture existante ; si le client ne peut pas recevoir sur Peppol, transmettez cette même facture autrement |
preparing, 409 PEPPOL_TRANSMISSION_IN_PROGRESS | XML en cours de construction et d'archivage | Attendez au moins cinq minutes, puis relisez le statut |
prepared, preparation_failed | Pas encore remis | Corrigez la cause éventuelle (par exemple un PDF manquant) et renvoyez la même facture |
accepted | Le point d'accès a pris le message ; ce n'est pas l'acceptation de l'acheteur | Suivez status jusqu'à processed |
rejected, PEPPOL_TRANSMISSION_REJECTED | Refus explicite | Trouvez la cause ; une nouvelle tentative renvoie les mêmes octets archivés. Contenu erroné : Corriger un envoi Peppol en échec ou une facture Peppol refusée |
sending, uncertain, PEPPOL_TRANSMISSION_UNCERTAIN | Le message est peut-être déjà sur le réseau | Suspendez : ni nouvelle facture, ni copie par e-mail ; faites rapprocher l'issue par le support OrdoGrid |
409 PEPPOL_HISTORY_RECONCILIATION_REQUIRED | D'anciennes transmissions en double existent | Contactez le support OrdoGrid |
PEPPOL_ARCHIVE_HASH_MISMATCH, XML_NOT_AVAILABLE, PDF_NOT_AVAILABLE | Le fichier archivé ne peut pas être servi tel qu'enregistré | Escaladez ; ne présentez jamais un fichier régénéré comme l'original |
La spécification Invoice Response d'OpenPeppol distingue les accusés de transport de la décision commerciale de l'acheteur, et l'acheteur n'est pas tenu de répondre. Conservez l'état de transmission, la réponse du client et le règlement dans des champs distincts : livré ne veut dire ni accepté ni payé.
La boucle de reprise
Nos valeurs de départ suggérées, et non des limites du produit : temporisation de 1, 2, 4, 8, 16 et 32 secondes, plafonnée à 60, avec une variation aléatoire de ±20 % ; six tentatives par événement, puis suspension motivée. Les attentes dues à un 429 ne comptent pas. Gardez une Idempotency-Key par opération métier (SO-58213-create) pour toutes les tentatives ; ne modifiez le contenu qu'après un 4xx, quand OrdoGrid a libéré la clé.
tant que tentatives < 6 :
r = POST /api/v1/invoices (contenu figé, même Idempotency-Key)
2xx -> terminé(r.id, r.number)
429 -> attendre Retry-After ; continuer
4xx définitif ou *_REUSED -> suspendre(code) ; arrêter
502 DOCUMENT_CREATED -> tentatives += 1 ; continuer (un renvoi identique l'achève)
EXTERNAL_OPERATION_IN_PROGRESS -> attendre 150 s
l = GET /api/v1/invoices/lookup?external_id=...
200 -> terminé(l.id, l.number) 409 -> attendre 150 s 404 -> réessayer
tentatives += 1 ; attendre temporisation(tentatives)
suspendre("budget de reprise épuisé")
Après 24 heures, l'Idempotency-Key expire ; une répétition identique reste protégée par external_id. PATCH, PUT et DELETE n'ont pas de rejeu : après une réponse perdue, relisez le document par GET et comparez avant de réappliquer la modification.
Exemple chiffré : délai dépassé, renouvellement de clé, virement
Verhaeghe Technics BV (Courtrai) facture depuis son ERP avec une clé nommée « ERP production », Identifiant d'intégration erp-prod. La commande SO-58213 concerne la Brasserie Lambert SRL (Namur), qui reçoit sur Peppol : 8 h d'entretien de machines × 95,00 € = 760,00 € et une pompe mobile à 1 240,00 € (aucun travail immobilier, donc pas d'autoliquidation), soit 2 000,00 € HTVA + 420,00 € de TVA à 21 % = 2 420,00 €.
12 octobre 2026, 14 h 02 UTC (16 h 02 à Bruxelles). POST /api/v1/peppol/send avec l'external_id SO-58213 et l'Idempotency-Key SO-58213-send expire après 30 secondes.
- Classer. Issue inconnue : pas de renvoi.
- Rechercher.
GET /api/v1/invoices/lookup?external_id=SO-58213répond200: la facture F-2026-0418 existe (cette route crée la facture avant de l'envoyer). - Lire la transmission. Le statut indique
transmission_stateuncertain,transmitted: false. La ligne du registre est suspendue ; responsable Anke Peeters ; prochain contrôle à 15 h UTC. - Résoudre. À 15 h, l'état est
accepted; à 15 h 20,statusvautprocessed(Traité dans Peppol → Outbox). Une facture, une transmission, 2 420,00 € à recevoir.
Un connecteur naïf qui aurait réessayé trois fois avec un nouvel UUID à chaque fois aurait créé et envoyé F-2026-0419 à F-2026-0421 : 3 × 2 420,00 € = 7 260,00 € de créances en trop, dont 1 260,00 € de TVA, que Peppol ne signale pas comme doublons. Chacune exige sa propre note de crédit sur Peppol (NC-2026-0031 à NC-2026-0033) et un appel au client.
20 octobre. L'administrateur clique sur Renouveler ; GET /api/v1/me affiche toujours erp-prod. À 9 h 15 UTC, le flux bancaire enregistre le premier virement :
{"external_id":"bank-20261020-0144","amount":"1000.00","currency":"EUR","method":"bank_transfer","occurred_at":"2026-10-20T09:12:00Z","reference":"Extrait 203 ligne 14"}
La réponse se perd. Le contenu enregistré est renvoyé avec la même Idempotency-Key : le 201 d'origine revient, marqué Idempotent-Replay: true (sans l'en-tête, ou après 24 heures, c'est l'identité durable qui répond : 200 avec replayed: true). Dans les deux cas, outstanding vaut "1420.00". Une référence reconstruite, par exemple « Extr. 203/14 », aurait provoqué 409 EXTERNAL_ID_REUSED.
Si, entre la réponse perdue et la répétition, le connecteur était passé à une clé créée avec Créer une clé et laissée à default, cette répétition aurait enregistré un deuxième paiement de 1 000,00 € : outstanding à 420,00 € alors que le client doit encore 1 420,00 €, ce qui ne serait apparu que le 3 novembre, au refus du vrai paiement de 1 420,00 € pour OVERPAYMENT. Ici, le paiement bank-20261103-0029 ramène outstanding à "0.00" et settlement.status à settled.
Cas particuliers et erreurs fréquentes
| Situation | Bonne réaction |
|---|---|
La recherche répond 404 après un délai dépassé | Vérifiez d'abord l'espace de noms avec GET /api/v1/me, puis renvoyez le contenu identique sous le même external_id ; jamais un nouvel identifiant « puisqu'elle n'existe pas » |
EXTERNAL_ID_REUSED après une modification de la commande dans l'ERP | La comptabilité décide de la bonne version ; une facture existante erronée reçoit une note de crédit et une nouvelle facture. N'ajoutez pas -v2 |
Un contenu corrigé revient EXTERNAL_ID_REUSED après un refus survenu pendant la création (comme OVERPAYMENT sur des acomptes de création ou DOCUMENT_NUMBER_TAKEN) | L'identité reste liée au contenu refusé. Si la recherche répond encore 409 EXTERNAL_OPERATION_IN_PROGRESS bien après deux minutes, rien n'a été enregistré : faites-le confirmer par le support OrdoGrid, puis utilisez un nouvel identifiant et reliez les deux dans le registre |
IDEMPOTENT_REQUEST_IN_PROGRESS pendant plus de quelques minutes | Recherchez ; si l'événement est absent, renvoyez le contenu identique avec une nouvelle Idempotency-Key ; l'external_id empêche toujours le doublon |
| Un virement qui règle deux factures | Les identifiants de mouvement sont uniques toutes factures confondues : bank-20261020-0144-a et -b |
| Montant erroné enregistré | Une contre-passation annule toujours le mouvement entier : contre-passez-le, puis enregistrez le bon montant sous un nouvel identifiant |
| Le client ne trouve pas une facture marquée Traité | Elle a été livrée à son prestataire Peppol : le client vérifie chez lui. Ne la renvoyez pas et ne l'envoyez pas par e-mail |
Surveiller les résultats métier, pas seulement la disponibilité
| Indicateur | Alerte suggérée | Responsable |
|---|---|---|
| Plus ancien événement non soumis | Plus de 30 minutes pendant les heures de bureau | Exploitation |
| Plus ancien élément suspendu | Plus d'un jour ouvrable | Responsable de la file |
Envois en sending ou uncertain | Tout envoi de plus de 4 heures | Exploitation des intégrations |
| Événements non facturés dont l'échéance du 15 du mois suivant tombe dans 5 jours ouvrables ou moins | Tout cas | Comptabilité |
Refus 4xx par jour et par code | Un nouveau code, ou un doublement d'un jour à l'autre | Développeur d'intégration |
| Réponses rejouées / requêtes | Plus de 5 % pendant une heure | Développeur d'intégration |
Totaux source du jour comparés à document_total et payments | Tout écart autre que 0,00 € | Contrôleur financier |
Comptez les requêtes séparément des événements métier : un rejeu n'est pas un nouveau chiffre d'affaires. Journalisez codes, identifiants et heures UTC, jamais le secret (ik_live_…) ni l'en-tête Authorization. Lisez toutes les pages des listes (limit jusqu'à 100, offset) avec des filtres stables et notez la fenêtre d'extraction ; voir Clôture mensuelle.
Prouver la reprise avant la mise en production
OrdoGrid n'a ni environnement de test ni mode de test Peppol : chaque appel agit sur des données réelles, et "send": false crée tout de même une facture numérotée. Si possible, testez dans une société distincte réservée à la recette (Créer une nouvelle entreprise) avec sa propre clé ; à défaut, prévoyez une note de crédit par facture de test. Simulez les envois incertains ou refusés avec des réponses enregistrées dans votre propre client HTTP.
| Scénario | Résultat attendu |
|---|---|
| Création, puis répétition identique avec la même clé, puis avec une nouvelle clé | 201, puis deux fois 201 avec Idempotent-Replay: true ; une seule facture |
| Même clé, autre contenu | 409 IDEMPOTENCY_KEY_REUSED ; élément suspendu |
Même external_id, autre contenu | 409 EXTERNAL_ID_REUSED ; élément suspendu, comptabilité alertée |
| Deux traitements, même événement | Un 201 ; l'autre un 409 « en cours » ou un rejeu |
| Paiement, puis répétition identique avec une nouvelle clé | 201, puis 200 avec replayed: true ; solde réduit une seule fois |
Paiement supérieur à outstanding | 409 OVERPAYMENT ; pas de reprise |
| Rafale au-delà de la limite | 429 avec Retry-After ; rien n'est perdu |
| Renouveler, puis rejouer des événements antérieurs | Rejeux uniquement ; /me affiche le même identifiant d'intégration |
La recette est acquise lorsque chaque événement a une seule identité OrdoGrid, que le règlement correspond à la source, qu'aucun envoi incertain n'a été répété et qu'un suppléant peut traiter la file des suspensions à partir du seul registre. Remettez les tableaux de décision, le responsable de la clé, l'identifiant d'intégration, l'emplacement du registre, les seuils et le contact du support. Après un incident, rapprochez toute la population concernée avant de déclarer la reprise (Incident de facturation).
Preuves à conserver
- Le registre : contenus figés ou leurs empreintes, valeurs d'
Idempotency-Key, chaque résultat avec heure UTC etcode. - Pour chaque envoi Peppol :
peppol_document_id, l'historique detransmission_stateet le XML échangé viaGET /api/v1/peppol/documents/{id}/xml(identifiant du document Peppol, pas de la facture ;peppol:read), ainsi que/pdf. OrdoGrid contrôle les deux par rapport aux empreintes SHA-256 detransmission_snapshot. - Les changements de clé (qui, quand, identifiant d'intégration avant et après) et, pour chaque élément suspendu, le motif, les contrôles, la personne qui l'a libéré et les échanges avec le support.
- Les factures se conservent sept ans à compter du 1er janvier de l'année qui suit leur émission ; OrdoGrid n'offre aucune garantie d'archivage légal, gardez donc votre propre copie (Archivage des factures en Belgique).
Questions fréquentes
Combien de temps attendre avant de réessayer après un délai dépassé ?
Recherchez d'abord au lieu d'attendre. Si le document existe, consignez-le dans le registre ; si un autre appel détient l'identité, attendez plus de deux minutes ; si la recherche répond 404, renvoyez le contenu identique avec temporisation.
Peut-on réutiliser la même Idempotency-Key après une erreur ?
Oui. OrdoGrid n'enregistre que les réponses réussies et libère la clé après un échec : elle peut donc porter un contenu corrigé après un 4xx. Dans les 24 heures qui suivent un succès, un autre contenu sous cette clé est refusé.
Pourquoi reçoit-on EXTERNAL_ID_REUSED alors que seule la description a changé ?
Pour les documents, tout le contenu de création compte, y compris les descriptions, les adresses e-mail et les échéances. Pour les mouvements comptent le montant, la devise, le mode de paiement, la date et l'heure de l'opération, et la référence. Renvoyez le contenu enregistré ou laissez la comptabilité trancher.
Peut-on relancer sans risque l'envoi Peppol de la même facture ?
Oui, si l'appel vise bien la même facture : la route d'envoi de cette facture, ou POST /api/v1/peppol/send répété avec le même external_id (sans external_id, cette route crée une nouvelle facture). Une transmission acceptée n'est pas réexpédiée (la réponse porte replayed à true), une transmission refusée repart avec les mêmes octets archivés, une transmission incertaine est refusée. Une nouvelle facture pour la même vente ou une copie par e-mail, elle, n'est pas sans risque.
Renouveler une clé API casse-t-il la protection contre les doublons ?
Pas avec Renouveler, qui conserve l'identifiant d'intégration. Seul le rejeu Idempotency-Key de 24 heures reste lié à l'ancienne clé. Une clé créée avec Créer une clé doit recevoir à la main le même identifiant d'intégration.
Peut-on tester les reprises dans un environnement de test ?
Non. Il n'existe ni environnement de test ni mode de test Peppol. Utilisez si possible une société de recette distincte, et simulez les issues Peppol avec des réponses enregistrées.
Sources et références
- Référence de l'API publique OrdoGrid : idempotence, recherche externe et codes d'erreur
- Peppol BIS Invoice Response 3.2 : accusés de transport et réponses métier
- SPF Finances, FAQ facturation électronique : questions spécifiques (Q4 doublons, Q5 notes de crédit)
- SPF Finances, FAQ Peppol : délais de livraison (Q9)
- Loi du 6 février 2024, art. 53, §2bis du Code de la TVA : documents rectificatifs dans le même format structuré (Moniteur belge, 20.02.2024)
- Arrêté royal n° 1, art. 4 et 5 : délai d'émission et numérotation séquentielle (Justel, version coordonnée)