Fiabilité des intégrations : reprises et transmissions incertaines
Préserver les identités financières, interpréter les refus, gérer les limites, rapprocher les résultats ambigus et exploiter un backlog traçable.
- Mis à jour
- Responsable du contenu
- Exploitation intégration
- Pour
- Exploitation intégration · Ingénieurs backend · Responsables de service
L’essentiel
Gardez les identités durables, classez le résultat avant nouvelle tentative et rapprochez une livraison ambiguë avant réémission.
Avant de commencer
- Des identités externes stables pour documents et mouvements
- L'accès au contrat et aux échanges expurgés
- Un responsable de file et un contact finance
Résultats attendus
- Une politique de reprise fondée sur le résultat réel
- Des réponses perdues sans doublon financier
- Un backlog attribué avec rapprochement financier et réseau
Sur cette page
Une intégration fiable retrouve la transaction métier lorsqu'une réponse HTTP, un traitement ou un accusé réseau manque. « Réessayer trois fois » ne constitue pas une stratégie financière. Certains échecs refusent la demande ; d'autres surviennent après création d'une facture numérotée ou d'un mouvement.
Préserver un registre d'identités
Conservez transaction source, espace d'intégration, type, empreinte du contenu, identifiant/numéro produit et dernier résultat. Pour l'argent, conservez identité du paiement/remboursement et facture liée. Modifier un identifiant après un délai dépassé contourne la protection contre les doublons.
L'identité de document est limitée par société, intégration et type. Les identités de mouvements sont uniques dans société/intégration, entre factures et types de mouvements. Rotation ou remplacement de clé ne les libère pas ; gardez l'espace d'intégration.
| Contrôle | Responsable | Vérification |
|---|---|---|
| Génération d'identité | Développeur | Même événement, même identifiant |
| Reprise et interprétation | Ingénieur service | Réponse perdue et répétition |
| File et limitation | Exploitation | Ancienneté et gestion des en-têtes |
| Rapprochement financier | Contrôleur | Pont source/règlement |
| Ambiguïté réseau | Contact fournisseur | Preuve avant réémission |
Utiliser les deux protections
Envoyez Idempotency-Key sur les écritures susceptibles d'être répétées. Une répétition identique retrouve la réponse conservée ; un autre contenu sous la même clé est refusé. La durée de 24 heures et la portée par clé API ne remplacent pas external_id.
Une répétition durable de document retrouve la première réponse terminée. Celle d'un mouvement retrouve le mouvement initial avec règlement actuel et replayed: true. Utilisez ces identités après expiration de la réponse HTTP ou remplacement des credentials. Ne changez pas l'identité financière à chaque tentative.
Classer avant de réessayer
| Résultat | Action |
|---|---|
| Champ, devise ou précision invalide | Corriger la correspondance |
| Permission ou approbation absente | Solliciter son propriétaire |
| 429 | Respecter Retry-After et remise à zéro |
EXTERNAL_OPERATION_IN_PROGRESS | Garder l'identité, attendre puis rapprocher |
| Réponse de création/mouvement perdue | Chercher par identité, rejouer à l'identique si nécessaire |
EXTERNAL_ID_REUSED | Examiner le contenu et la correction |
PEPPOL_TRANSMISSION_UNCERTAIN | Bloquer la réémission, rapprocher avec fournisseur |
| Empreinte d'archive incohérente | Escalader et préserver la preuve |
Le délai d'exécution d'un traitement peut expirer tandis que l'identité comptable demeure. La reprise récupère le même événement, elle n'en crée pas un nouveau.
Prévoyez dans votre client des délais progressifs bornés et un décalage aléatoire pour contention ou indisponibilité récupérable. Budget de répétition et ancienneté maximale sont vos décisions d'exploitation, pas des garanties produit.
Séparer persistance et réseau
Un envoi peut créer la facture puis rencontrer une erreur réseau. Recherchez l'écriture et vérifiez la transmission séparément. Un rejet connu peut permettre une nouvelle tentative avec les octets émis d'origine. Un résultat ambigu peut avoir atteint le réseau : toute réémission automatique reste suspendue.
OpenPeppol distingue accusé réseau et réponse acheteur. Une livraison ne prouve ni acceptation ni encaissement. Stockez règlement, transport et réponse client dans des champs de suivi distincts.
Exemple : réponse perdue puis rotation
L'ERP crée order-4711 dans l'espace erp, mais perd la réponse. La clé est ensuite remplacée. Le connecteur commence par /me, confirme société et espace, puis cherche order-4711. Il récupère la facture numérotée existante.
La synchronisation ultérieure de l'acompte utilise la même identité de paiement. Elle retrouve le mouvement initial sans ajouter un deuxième acompte. Un nouvel espace d'intégration et un nouvel identifiant de facture auraient supprimé cette continuité.
Observer les événements métier
Suivez transactions non exécutées, plus ancien cas bloqué, persistances réussies, refus permanents, envois incertains et écarts financiers. Les demandes HTTP et événements métier sont deux compteurs différents : une répétition ne crée pas de revenu.
Journalisez codes, identifiants et heures expurgés, jamais les secrets. Lisez toutes les pages et rapprochez les changements tardifs lorsque les extractions chevauchent des écritures. Attribuez alertes et escalades selon votre processus réel.
Accepter la reprise et transmettre
Testez réponse perdue, création concurrente, expiration du cache HTTP, rotation, rejet connu et envoi ambigu. La recette exige une identité financière par événement, le règlement attendu, aucune répétition réseau ambiguë et une procédure utilisable par un suppléant.
Après incident, rapprochez toute la population avant de déclarer la reprise. Fournissez table de décision, propriétaire de clé, registre, procédure et contact fournisseur. Finance reçoit les cas commerciaux résiduels avec impact et action. La gestion des incidents coordonne la réponse ; l'intégration API définit le contrat initial.