Rapport de démonstration. Ce document montre la méthode et le niveau de détail d'un audit d'intégration HANDICODE. L'entreprise est anonymisée et les situations décrites illustrent des défauts réellement rencontrés sur des chaînes comparables ; elles ne sont pas le relevé d'une mission chez un client identifiable.

Dossier B-2026-031 · Audit d'intégration

Chaîne de facturation d'un négociant en matériel

Diagnostic de l'échange entre l'outil métier de gestion commerciale et le logiciel comptable. Deux systèmes qui parlaient déjà, mais qui perdaient des écritures sans que personne ne puisse dire lesquelles.

Secteur · Négoce B2B, 34 salariés Volume · ~1 400 factures / mois Outil métier · ERP propriétaire, PHP 8.1 Comptabilité · Logiciel tiers, API REST Observation · 14 au 28 septembre 2026 Méthode · Journaux, rejeu, instrumentation

Périmètre et méthode
Le constat d'entrée : des écritures manquent
La chaîne telle qu'elle fonctionne
Où se perdent les écritures
Le doublon et son contraire
Secrets, droits et traçabilité
L'architecture proposée
Préconisations détaillées
Plan d'intervention et arbitrage
Annexe : ce qui n'a pas été mesuré
Transparence : coût, temps, accompagnement

Section 1Périmètre et méthode

L'audit porte sur le flux qui part d'une facture validée dans l'outil métier et qui doit produire une écriture dans le logiciel comptable. Deux semaines d'observation, sans modifier le code en production.

Source	Période	Volume	Ce qu'on en tire
Journaux applicatifs	30 j	41 200 lignes	Appels sortants, codes de retour
Journaux du serveur web	30 j	188 000 lignes	Délais, rejets, codes HTTP
Table des factures	90 j	4 180 lignes	Ce qui aurait dû partir
Export comptable	90 j	4 102 lignes	Ce qui est réellement arrivé
Rejeu en bac à sable	—	240 appels	Comportement aux limites

Le rapprochement est la mesure la plus utile du dossier. Comparer ce que l'outil métier croit avoir envoyé et ce que la comptabilité a réellement reçu donne un chiffre que personne ne contestait : 78 écritures manquantes sur 90 jours.

Section 2Le constat d'entrée : des écritures manquent

Trois mois, 4 180 factures émises, 4 102 écritures arrivées. L'écart ne ressemble pas à un incident : il est régulier, ce qui oriente vers un défaut structurel plutôt que vers une panne.

critiqueUn échec d'envoi ne laisse aucune trace exploitable

Quand l'appel vers la comptabilité échoue, l'exception est capturée et le traitement continue. La facture reste marquée « envoyée » dans l'outil métier. Personne ne sait qu'une écriture manque, et le rapprochement ne se fait qu'à la clôture, trois mois plus tard.

// Le code en place, simplifié. Le problème n'est pas le try/catch : // c'est que l'échec ne change rien à l'état de la facture. try { $compta->creerEcriture($facture); } catch (\Throwable $e) { Log::error('Export compta : ' . $e->getMessage()); } $facture->update(['exportee' => true]); // ← exécuté même après l'échec

Section 3La chaîne telle qu'elle fonctionne

L'appel part depuis la requête web de l'utilisateur, en direct. Rien ne se place entre les deux systèmes : ni file, ni journal d'échanges, ni reprise.

Section 4Où se perdent les écritures

Les 78 écarts se répartissent en quatre causes, toutes identifiées par le rejeu des appels en bac à sable.

Cause	Cas	Mécanisme	Gravité
Quota de l'API dépassé	41	60 appels/min, saturés en fin de mois	haute
Délai d'attente du serveur	22	30 s côté PHP, l'API répond parfois en 34 s	haute
Validation refusée	11	Code analytique absent, rejet silencieux	moyenne
Jeton expiré en cours de lot	4	Renouvellement non géré au milieu d'un traitement	moyenne

Le quota, et pourquoi il frappe en fin de mois

L'API comptable limite à 60 appels par minute. La facturation est groupée le dernier jour ouvré : 400 à 600 factures partent en quelques minutes. Le dépassement renvoie un code 429, qui n'est pas traité différemment d'une autre erreur.

// Ce que renvoie l'API quand le quota est atteint : HTTP/1.1 429 Too Many Requests Retry-After: 37 X-RateLimit-Remaining: 0 // L'en-tête Retry-After dit exactement combien de temps attendre. // Il n'est pas lu : l'appel est abandonné comme une erreur ordinaire.

Le correctif : une attente qui respecte ce que le serveur annonce

Une temporisation exponentielle qui lit l'en-tête Retry-After suffit à absorber le pic de fin de mois. Sur les 41 cas rejoués en bac à sable, 41 passent avec cette seule correction.

$reponse = Http::retry(5, 0, function ($exception, $requete) { // Le serveur dit combien de temps attendre : on l'écoute, // au lieu de deviner. $attente = (int) $exception->response?->header('Retry-After') ?: 2; sleep(min($attente, 60)); return true; }, throw: false)->timeout(45)->post($url, $charge);

Section 5Le doublon et son contraire

Un flux qui réessaie crée un risque nouveau : envoyer deux fois la même écriture. Le rejeu a confirmé que l'API accepte deux appels identiques sans protester, et crée deux écritures.

critiqueRien n'empêche aujourd'hui un double envoi

Un double clic sur « Valider » produit deux écritures. Le cas s'est produit 6 fois sur 90 jours, détecté à la clôture par le comptable, corrigé à la main.

La protection ne doit pas reposer sur une fenêtre de temps. Une clé d'idempotence dérivée de la facture elle-même rend l'opération rejouable sans risque, quel que soit le délai.

// Une référence stable, dérivée de la facture et non de l'instant : // le même envoi rejoué dans six mois reste le même envoi. $cle = 'fact-' . $facture->id . '-' . $facture->updated_at->timestamp; Http::withHeaders(['Idempotency-Key' => $cle])->post($url, $charge);

Le piège à éviter. Une clé fondée sur une fenêtre de temps (« un envoi par facture toutes les 10 minutes ») laisse passer le doublon au-delà de la fenêtre, et bloque une correction légitime à l'intérieur. La règle est : une référence, une action, pour toujours.

Section 6Secrets, droits et traçabilité

Point	État	Risque
Jeton d'API	en dur dans le dépôt	Lisible par tout l'historique Git
Droits du jeton	tous droits	Lecture et écriture sur toute la comptabilité
Rotation	jamais effectuée	Jeton créé il y a 3 ans
Journal des échanges	absent	Impossible de rejouer ou d'expliquer
Alerte sur échec	absente	Découverte à la clôture
Transport	TLS 1.3	—

critiqueLe jeton est dans l'historique du dépôt

Le retirer du fichier ne suffit pas : il reste lisible dans tous les commits antérieurs. La seule mesure efficace est de révoquer le jeton chez le fournisseur et d'en émettre un nouveau, avec des droits réduits à ce dont l'intégration a besoin.

Ce qu'un journal d'échanges aurait changé

Sans journal, la question « pourquoi cette écriture manque-t-elle ? » n'a pas de réponse. Avec un journal qui conserve la requête, la réponse et le résultat, elle devient une recherche de trois minutes.

// Une ligne par échange, conservée 13 mois (exercice + report). // Les données personnelles et le jeton n'y figurent jamais. Schema::create('echanges_compta', function (Blueprint $t) { $t->id(); $t->foreignId('facture_id')->index(); $t->string('cle_idempotence', 80)->unique(); $t->unsignedSmallInteger('code_http')->nullable(); $t->unsignedTinyInteger('tentatives')->default(0); $t->json('reponse')->nullable(); // sans en-tête d'autorisation $t->string('etat', 20)->index(); // en_attente | envoye | echoue $t->timestamps(); });

Section 7L'architecture proposée

L'appel sort de la requête web : l'utilisateur n'attend plus l'API. Chaque échange laisse une trace, et un échec définitif prévient quelqu'un le jour même au lieu d'être découvert à la clôture.

Propriété	Aujourd'hui	Cible
Appel	dans la requête web	en file, hors requête
Échec	journalisé puis oublié	repris 5 fois, puis alerte
Doublon	possible	clé d'idempotence
Quota	ignoré	Retry-After respecté
Traçabilité	aucune	journal 13 mois
Attente utilisateur	2 à 34 s	< 200 ms

Section 8Préconisations détaillées

Chaque préconisation porte son critère d'acceptation : la mesure qui dira, après intervention, si elle a produit l'effet attendu. Une recommandation sans critère vérifiable n'est qu'un avis.

P-01 · priorité 1 · sécurité

Révoquer le jeton, en émettre un aux droits réduits

Constat: Le jeton d'API figure en clair dans le dépôt, tous droits, jamais renouvelé depuis trois ans. Il donne accès en lecture et en écriture à toute la comptabilité.
Préconisation: Révoquer le jeton chez le fournisseur, en émettre un nouveau limité aux écritures de vente, et le stocker hors du dépôt. Planifier un renouvellement annuel.
Mise en œuvre: Le retirer du fichier ne suffit pas : il reste lisible dans tout l'historique du dépôt. Seule la révocation chez le fournisseur ferme réellement l'accès.
Critère d'acceptation: L'ancien jeton renvoie 401 sur un appel d'essai. Le nouveau échoue sur une écriture d'achat et réussit sur une écriture de vente, preuve que ses droits sont bien restreints.
Risque de régression: Interruption du flux si le nouveau jeton n'est pas en place avant la révocation. Poser le nouveau d'abord, vérifier un envoi, révoquer ensuite.
Effort · Gain: 0,5 jour · ferme un accès total à la comptabilité

P-02 · priorité 1 · traçabilité

Journaliser chaque échange et rapprocher tous les jours

Constat: Aucune trace des échanges. La question « pourquoi cette écriture manque-t-elle ? » reste sans réponse, et l'écart ne se découvre qu'à la clôture, trois mois plus tard.
Préconisation: Une table d'échanges conservant la clé d'idempotence, le code de retour, le nombre de tentatives et l'état. Un rapprochement quotidien automatique qui compte les factures émises et les écritures reçues.
Mise en œuvre: Ni l'en-tête d'autorisation ni les données personnelles ne sont journalisés. Conservation 13 mois, soit l'exercice plus le report.
Critère d'acceptation: Pour toute facture des 30 derniers jours, une ligne d'échange existe. L'écart quotidien entre factures et écritures est connu avant 9 heures le lendemain.
Risque de régression: Faible. Surveiller la croissance de la table : 1 400 lignes par mois, soit environ 18 000 sur la durée de conservation.
Effort · Gain: 2 jours · l'écart se voit le jour même au lieu de trois mois après

P-03 · priorité 1 · architecture

Sortir l'appel de la requête web

Constat: L'appel part depuis la requête de l'utilisateur, avec un délai de 30 secondes côté serveur alors que l'API répond parfois en 34. Vingt-deux écritures ont été perdues ainsi.
Préconisation: Déposer un travail en file à la validation de la facture. Un exécutant traite la file hors de la requête web, avec un délai porté à 45 secondes.
Mise en œuvre: L'utilisateur n'attend plus l'API : la validation lui rend la main immédiatement. Le traitement se fait dans la seconde qui suit, sans qu'il le voie.
Critère d'acceptation: Temps de réponse de la validation inférieur à 200 ms au 95^e centile. Zéro perte par dépassement de délai sur un mois d'observation.
Risque de régression: Modéré. L'exécutant doit être surveillé : une file qui ne tourne plus accumule les travaux en silence. L'alerte du lot P-05 couvre ce cas.
Effort · Gain: 3 jours · 22 pertes évitées, attente utilisateur de 34 s à moins de 0,2 s

P-04 · priorité 1 · fiabilité

Respecter le quota annoncé et rendre l'envoi rejouable

Constat: Quarante et une pertes par dépassement du quota de 60 appels par minute. Le serveur annonce pourtant le délai d'attente dans l'en-tête Retry-After, qui n'est pas lu.
Préconisation: Une temporisation qui lit cet en-tête, cinq tentatives au plus. Une clé d'idempotence dérivée de la facture et de sa date de modification, pour qu'un rejeu ne crée jamais de doublon.
Mise en œuvre: La clé ne doit pas reposer sur une fenêtre de temps : une fenêtre laisse passer le doublon au-delà et bloque une correction légitime en deçà. Une référence, une action, pour toujours.
Critère d'acceptation: Les 41 cas rejoués en bac à sable passent. Deux envois successifs de la même facture ne produisent qu'une écriture, vérifié en recette.
Risque de régression: Faible, mais à vérifier : une facture modifiée doit produire une nouvelle clé, sinon la correction serait ignorée comme un doublon.
Effort · Gain: 2 jours · 41 pertes évitées, 6 doublons annuels supprimés

P-05 · priorité 2 · exploitation

Alerter après échec définitif, et donner un écran de suivi

Constat: Un échec ne prévient personne. Il se découvre à la clôture, quand la correction coûte le plus cher.
Préconisation: Après cinq tentatives infructueuses, une alerte nommant la facture et la cause. Un écran listant les échanges en échec, avec un bouton de rejeu unitaire.
Mise en œuvre: L'alerte doit nommer la facture et le code de retour, pas seulement signaler une erreur : une alerte qu'on ne peut pas traiter finit par être ignorée.
Critère d'acceptation: Un échec simulé en recette déclenche l'alerte en moins de cinq minutes. Le rejeu depuis l'écran produit l'écriture sans doublon.
Risque de régression: Le bruit. Si l'alerte se déclenche pour des échecs transitoires déjà repris, elle perdra son sens. Elle ne part qu'après épuisement des tentatives.
Effort · Gain: 1,5 jour · délai de détection de 3 mois à moins d'une heure

P-06 · priorité 3 · régularisation

Rejouer les 78 écritures manquantes, après contrôle

Constat: 78 écritures manquent sur 90 jours. Quatre relèvent d'un code analytique absent dans l'outil métier, les 74 autres d'un défaut technique corrigé par les lots précédents.
Préconisation: Rejouer les 74 après validation du comptable, exercice par exercice. Traiter les 4 restantes à la main, après correction du code analytique à la source.
Mise en œuvre: Le rejeu ne doit pas précéder la clé d'idempotence, sinon il risque de créer des doublons sur les écritures déjà passées.
Critère d'acceptation: Écart entre factures et écritures ramené à zéro sur les 90 jours. Contrôle du comptable sur un échantillon de dix écritures rejouées.
Risque de régression: Réel si un exercice est clos : une écriture passée après clôture demande un traitement comptable particulier. À arbitrer avec l'expert-comptable avant tout rejeu.
Effort · Gain: 1 jour · régularisation de l'existant

Section 9Plan d'intervention et arbitrage

Lot	Contenu	Effort	Ce que ça règle
1 · Immédiat	Révoquer le jeton, en émettre un à droits réduits, le sortir du dépôt	0,5 j	Exposition du secret
2 · Semaine 1	Journal des échanges et rapprochement quotidien automatique	2 j	Savoir ce qui manque, le jour même
3 · Semaine 2	File de travaux, l'appel sort de la requête web	3 j	Délais d'attente, attente utilisateur
4 · Semaine 2	Reprise avec Retry-After et clé d'idempotence	2 j	Quota et doublons
5 · Semaine 3	Alerte après échec définitif, écran de suivi	1,5 j	Découverte à la clôture
6 · Semaine 4	Rejeu des 78 écritures manquantes, après contrôle	1 j	Régularisation de l'existant

Effet attendu, mesuré par rejeu en bac à sable

Sur les 78 écarts constatés, 74 passent après les lots 3 et 4. Les 4 restants relèvent d'un code analytique absent dans l'outil métier : un défaut de saisie, que le lot 5 rendra visible le jour même au lieu de trois mois plus tard.

Ce que je ne recommande pas

Un connecteur du marché a été évoqué. Il traiterait le transport, mais pas la cause : le code analytique absent, le quota de fin de mois et l'absence de rapprochement resteraient. Un intermédiaire de plus ajouterait un jeton de plus à surveiller, pour un problème qui se règle dans le code existant en neuf jours.

Section 10Annexe : ce qui n'a pas été mesuré

La conformité comptable des écritures. L'audit vérifie qu'elles arrivent, pas qu'elles sont justes. Le contrôle du plan comptable relève de l'expert-comptable.
Les performances de l'ERP lui-même. Hors périmètre : seul le flux sortant a été observé.
La sécurité applicative de l'outil métier. Aucun test actif, aucune revue d'authentification.
Les autres flux. L'ERP échange aussi avec un transporteur et une plateforme de paiement. Ils n'ont pas été examinés, mais les mêmes défauts s'y retrouvent souvent.
Le coût réel des corrections manuelles. Estimé par le client à « deux jours par clôture », non vérifié par un relevé de temps.

PrestationTransparence : ce que coûte cette intervention

Nous publions le détail de nos prestations parce qu'un audit dont on ne connaît ni le temps ni le prix se juge mal. Les montants ci-dessous sont des ordres de grandeur indicatifs pour une intervention de ce calibre ; seul un devis nominatif engage.

Poste	Temps	Ce qui est fait	Montant indicatif HT
Audit et diagnostic	4 j	Relevés sur 2 semaines, rapprochements, entretiens, rédaction du présent rapport	1 920 €
Mise en œuvre	10 j	Les lots du plan d'intervention, du premier au dernier, avec leurs critères d'acceptation	4 800 €
Accompagnement et transfert	1,5 j	Ateliers, documentation, formation de l'équipe, reprise en main sans nous	720 €
Total	15,5 j	Taux journalier unique de 480 € HT, sans forfait caché ni frais de dossier	7 440 €

Ce qui est compris, et ce qui ne l'est pas

Compris dans le montant	Hors prestation
Le rapport complet, remis en main propre et commenté	Hébergement, noms de domaine, abonnements tiers, facturés au réel par le fournisseur
Les ateliers et la formation de l'équipe	Licences logicielles et services d'intelligence artificielle, à la consommation
La documentation et les procédures laissées en place	Création de contenu éditorial, photographies, traductions
Les points de suivi : 3 points de 45 min sur le premier trimestre, inclus	Demandes hors périmètre, chiffrées séparément avant d'être engagées
Les correctifs sur ce que nous avons livré, sans limite de durée	Évolutions fonctionnelles nouvelles, qui font l'objet d'un devis

Accompagnement, pédagogie et ressources

Pédagogie

Deux séances de 2 h avec le développeur en place : lecture des journaux, rejeu d'un échange en erreur. Notre critère de réussite est que l'équipe sache faire sans nous : un client qui dépend de son prestataire pour comprendre son propre outil a été mal servi.

Ressources mises à disposition

Environnement de recette dédié, jeu de 40 cas d'échange documentés, tableau de bord des rejets. Tout cela reste au client, dans un format lisible et sans nous.

Rendu

Rapport de 20 pages, 1 atelier technique, documentation de l'intégration, jeu de tests rejouable. Chaque chiffre du rapport renvoie à son relevé horodaté, et chaque préconisation porte son critère d'acceptation : vous pouvez vérifier vous-même que le travail est fait, y compris contre nous.

Ce que nous ne promettons pas

Les gains annoncés par préconisation sont des hypothèses sauf mention contraire explicite, et ils sont présentés comme telles. Nous nous engageons sur les critères d'acceptation, qui sont vérifiables, pas sur un résultat commercial qui dépend aussi de ce que fait le marché.