Facturation électronique
Mettre une passerelle de facturation électronique en production : certification, hébergement, exploitation
par Paul Mantez, Co-fondateur & Développeur
On a déjà raconté comment on a intégré l'API d'une Plateforme Agréée et pourquoi on a choisi une architecture en pull depuis Salesforce. Ces deux articles s'arrêtent là où le code marche en sandbox. Celui-ci commence à cet endroit précis.
Le projet : une passerelle qui relie le Salesforce d'un groupe d'événementiel parisien à Sage Network, pour deux sociétés du groupe, donc deux SIREN et deux jeux de données distincts. Cinq phases de développement, bouclées en une semaine de mai. Puis quatre mois pour que la première vraie facture parte en production. Voici ce qui a rempli ces quatre mois.
Ce que « fini » voulait dire, et ce qu'il ne voulait pas dire
Début mai, le dépôt contenait tout ce qu'un cahier des charges aurait demandé. Un cœur indépendant du CRM avec une facture canonique et des ports d'entrée et de sortie. Un adaptateur Salesforce qui va chercher les factures éligibles par API, sans trigger ni message sortant côté org. Un générateur UBL 2.1 pour les factures et les avoirs, validé contre des fixtures de référence. Un adaptateur Sage Network pour déposer, suivre les statuts et recevoir. Un serveur de webhooks avec persistance SQLite et dispatcher. Deux cent quatre-vingt-quinze tests unitaires, mocks HTTP compris. Une première facture réelle, tirée de l'org de production, déposée sur la sandbox de la plateforme, avec les sept champs de retour écrits dans Salesforce.
Ce que ce « fini » ne couvrait pas : le droit d'utiliser la production de la plateforme, un endroit où faire tourner le service, quelqu'un pour l'opérer. Trois sujets qu'on avait notés en bas de la feuille de route, comme une formalité. Ce n'en était pas une.
La certification : 56 tests, des preuves, et un trou qu'on n'avait pas vu
Sage Network ne remet pas d'identifiants de production à un intégrateur sur parole. Le processus est cadré : préavis de go-live d'au moins quatre semaines, plan de tests soumis au moins deux semaines avant, tous les tests au vert une semaine avant, puis trente jours de bêta surveillée une fois en production.
Le plan de tests est un classeur de 56 cas répartis par famille : identité des entreprises, souscriptions aux notifications, envoi, erreurs, contrôles. Pour chacun, il faut une preuve : le journal brut des requêtes et réponses, une capture d'écran, un document. On a écrit un petit outil pour ça : chaque commande lancée sous un identifiant de test enregistre automatiquement tous ses échanges HTTP dans un dossier au format imposé. Sans cet outil, la constitution du dossier aurait pris plus longtemps que le développement de la fonctionnalité testée.
C'est un test classé critique qui nous a rattrapés. Notre serveur de webhooks vérifiait que l'identifiant de souscription présent dans le corps de la notification existait bien en base. Or cet identifiant n'est pas un secret. N'importe qui le connaissant pouvait nous envoyer de fausses notifications. La plateforme transmet dans un en-tête un jeton opaque signé, que nous ignorions. Le correctif tient en cinquante lignes : lire l'en-tête, vérifier la signature, refuser si le jeton ne correspond pas à la souscription annoncée dans le corps. Quatre tests de plus. Et un mail à la plateforme pour corriger une affirmation trop optimiste faite deux semaines plus tôt.
La revue est revenue avec 44 tests validés, zéro échec, et une liste de pièces manquantes : des captures de l'interface d'enrôlement, la preuve d'identité des deux sociétés au registre, la confirmation écrite du modèle de support avec les contacts d'escalade. En cherchant les avis de situation officiels, on a découvert que les SIRET cités dans nos fiches de test étaient faux. Les SIREN, eux, étaient justes, et seuls les SIREN circulent vers la plateforme. Aucune facture n'a été affectée. Mais l'erratum est allé dans le dossier, avec les pièces corrigées.
L'hébergement : chez le client, en code, avec un runbook
Pendant tout le développement, la passerelle tournait sur un poste de développeur, derrière un tunnel qui exposait le serveur de webhooks. Ce n'est pas une architecture de production, et ce n'est pas non plus la bonne réponse de la faire tourner chez l'intégrateur. Les secrets de la plateforme et du CRM appartiennent au client, ses factures aussi.
Le déploiement est donc parti dans le compte cloud du client, décrit intégralement en Terraform pour cohabiter dans son cluster existant. Deux services conteneurisés : un serveur de webhooks sans état, en deux instances derrière un répartiteur de charge, et une boucle d'envoi en instance unique qui interroge Salesforce à intervalle régulier. Les deux partagent un volume réseau qui porte la base SQLite. Six secrets dans un gestionnaire dédié, injectés au démarrage. Trois alarmes : plus de cinq factures en échec sur une heure, boucle d'envoi absente pendant deux minutes, erreurs serveur sur le répartiteur. Les erreurs applicatives partent vers Sentry.
Pourquoi SQLite et pas une base gérée ? Parce que le volume ne le justifie pas : quelques centaines de factures par mois pour deux entités. Le seuil de migration vers Postgres est écrit dans le document de conception, avec le chiffre. Le jour où le client s'en approche, la décision est déjà prise.
Le runbook est en français, écrit pour l'équipe informatique du client, pas pour nous. Déploiement initial, nouvelle version, retour arrière, lecture des journaux par identifiant de facture, rotation d'un secret, diagnostic d'un contrôle de santé en échec. Et une section sur les particularités de la plateforme : une suppression de souscription qui renvoie un refus, un point d'accès de statut inaccessible, des notifications qui arrivent dans un format différent de la documentation. Chaque cas est contourné dans le code et documenté, pour que l'équipe d'exploitation ne le redécouvre pas à deux heures du matin.
La passation : ce que Git ne transporte pas
Le développeur qui avait porté le projet a passé la main en juillet. C'est là qu'on a mesuré ce qu'un dépôt ne contient pas.
La base SQLite locale, d'abord. Elle porte l'état des sociétés enregistrées auprès de la plateforme, les souscriptions actives, l'historique des envois. La commande qui enregistre une société est idempotente, mais son idempotence repose sur cette base, pas sur une interrogation de la plateforme. Lancée sur une machine vierge, elle aurait créé un jeu de données en doublon et des souscriptions vers un tunnel mort. Règle écrite dans le document de passation : une seule machine porteuse d'état à la fois, jamais de commande d'enregistrement sans la base en place.
Le fichier de configuration, ensuite, avec les identifiants de la sandbox, de l'org Salesforce et le secret des webhooks. Ce dernier ne peut pas changer : les jetons des souscriptions existantes en dérivent.
Et tout le reste, qui n'est ni du code ni de la configuration : le dossier de certification à moitié clos, les mails en attente de la plateforme, les accès à transférer, la session de déploiement à planifier avec le client. On a tout mis dans un document de passation, en français, avec l'état exact au jour du transfert. Le repreneur n'a eu aucune question à poser sur le code. Toutes ses questions portaient sur ce document.
Ce qu'on referait, et ce qu'on chiffrerait autrement
L'architecture n'a pas bougé d'un cran entre la sandbox et la production, et c'est le point qu'on retient. Le cœur indépendant du CRM, les adaptateurs remplaçables, le modèle en pull sans code dans l'org : tout ça a permis de déployer chez le client sans toucher à Salesforce, et permettra de brancher un second outil source ou une seconde plateforme sans réécrire le centre.
Ce qu'on chiffrerait autrement, c'est le temps après le code. Sur ce projet, le développement a pesé moins de la moitié du calendrier. La certification, les preuves, le déploiement, la documentation d'exploitation et la passation ont occupé le reste, avec des délais imposés par la plateforme qu'aucune vélocité d'équipe ne raccourcit. Un devis de passerelle qui ne comporte pas une ligne « certification et mise en production » égale à la ligne « développement » est un devis incomplet.
On met votre passerelle en production, pas seulement en sandbox →
Questions fréquentes
Faut-il faire certifier sa passerelle par la Plateforme Agréée ?
Oui, dans la plupart des cas. Une Plateforme Agréée n'ouvre pas ses identifiants de production à un intégrateur sans avoir vérifié qu'il traite correctement les envois, les statuts, les erreurs et la sécurité des webhooks. Chez Sage Network, cela passe par un plan de tests d'intégration avec preuves : journaux de requêtes, captures, documents d'identité des entreprises raccordées.
Où héberger la passerelle : chez l'intégrateur ou chez le client ?
Chez le client, dès que la passerelle traite ses factures réelles. Les secrets de la Plateforme Agréée et du CRM lui appartiennent. Ses équipes doivent pouvoir redéployer, consulter les journaux et tourner les clés sans dépendre d'un prestataire. L'intégrateur livre une image conteneur, une infrastructure décrite en code et un runbook.
Combien de temps entre un code qui fonctionne en sandbox et une facture réelle émise en production ?
Comptez au moins autant que le développement lui-même. Sur notre projet, le code était complet début mai, et la certification, les preuves, le déploiement et la passation ont occupé les mois suivants. La Plateforme Agréée impose ses propres délais : préavis de go-live, soumission du plan de tests, période de bêta surveillée.