Comment nous avons construit YeloInvoice : un SaaS de facturation conforme construit avec des agents IA
YeloInvoice est une plateforme de facturation et de point de vente pour les petites et moyennes entreprises en Tunisie : factures conformes, avoirs, paiements, stock, achats, rapports comptables et un centre d’e-facturation, en français, en arabe et en anglais. OHY Labs l’a construite avec des agents de code IA travaillant à partir de spécifications écrites, et a façonné son API pour que les agents IA puissent s’y connecter via MCP à l’étape suivante. Voici comment cela a été fait.
Le cahier des charges : une facturation qui survit à un contrôle fiscal
Un logiciel de facturation ne pardonne rien. La numérotation doit être sans trou, les totaux doivent respecter les règles fiscales au centime près, un avoir doit référencer le document qu’il corrige, et une facture émise ne doit jamais changer. Ajoutez l’accès multi-utilisateur, plusieurs exercices fiscaux et trois langues dont une de droite à gauche, et la surface pour des bugs subtils devient énorme.
L’objectif était un produit auquel un comptable ferait confiance, livré par une petite équipe à vitesse de startup. Cette combinaison est exactement là où l’ingénierie assistée par IA rapporte, à condition que le processus soit discipliné.
- Brouillon, émission et impression de factures, avec une numérotation sans trou par série et par exercice.
- Avoirs totaux et partiels, enregistrement des paiements et statut de paiement calculé.
- Point de vente, achats, stock, trésorerie, rapports comptables et effets de commerce.
- Un centre d’e-facturation préparé pour le flux national de facturation électronique.
- Rôles propriétaire, commercial, comptable et lecteur, avec isolation des tenants à chaque couche.
Architecture : un seul moteur de taxes, partagé partout
YeloInvoice est un monorepo pnpm. L’API est en NestJS avec Prisma sur Postgres et Redis. L’application web est en Next.js avec l’App Router et Tailwind, en français par défaut, en arabe avec des mises en page de droite à gauche, et en anglais. Un package partagé contient les schémas Zod, les enums du domaine et un moteur pur de montants et de taxes, sans dépendance à la base de données ni au framework.
Parce que le moteur de taxes est pur et partagé, l’éditeur de facture affiche dans le navigateur des totaux en direct identiques à ce que l’API va enregistrer, et le même code est testé unitairement de façon isolée. L’émission d’une facture est protégée par une clé d’idempotence et produit un hash d’intégrité, pour qu’un double clic ou une nouvelle tentative ne crée jamais deux documents.
La concurrence est testée, pas supposée
La suite de bout en bout envoie délibérément des requêtes concurrentes vers la même instance Postgres pour la numérotation, les paiements et les avoirs. Les conditions de concurrence en facturation ne sont pas théoriques, et les attraper en CI coûte moins cher que d’expliquer un numéro en double à un contrôleur.
Développement piloté par spécifications avec des agents de code IA
Chaque pan de YeloInvoice a commencé par un document de conception : le cœur fiscal, les modèles PDF, la fiscalité étendue, la comptabilité et les rapports, le point de vente, l’administration, les imports, et les modes de paiement par type d’activité. Chaque spécification énonce les exigences, les sources de conformité, et ce qui est explicitement hors périmètre.
Les spécifications sont ensuite découpées en tâches. Chaque tâche reçoit un brief court qu’un agent de code IA implémente, suivi d’un rapport écrit de ce qui a changé et de ce qui a été vérifié. Le dépôt contient plus d’une centaine de ces paires brief-rapport. Un humain relit le diff, exécute les tests et décide. L’agent tape le code ; la spécification fait la réflexion.
- Des spécifications de conception comme source de vérité unique pour le périmètre et l’architecture.
- De petites tâches avec briefs et rapports, pour que chaque changement soit explicable.
- Des tests écrits en même temps que l’implémentation, y compris des exécutions de bout en bout sur une vraie base de données.
- Un document de conformité qui sépare ce qui est implémenté de ce qui attend encore la confirmation d’un comptable.
Pourquoi c’est meilleur que de demander une application entière
Demander à un agent de « construire une application de facturation » produit quelque chose de plausible et faux. Lui demander d’implémenter une tâche issue d’une spécification qui nomme la règle fiscale, la contrainte de numérotation et le test à ajouter produit quelque chose qu’un comptable peut vérifier. C’est la qualité de la spécification, pas le modèle seul, qui fixe le plafond.
Conformité et sécurité par construction
Les règles fiscales sont documentées avec leurs sources, et les questions ouvertes sont suivies séparément jusqu’à confirmation par un comptable. Plutôt que de promettre une validation juridique, le produit indique clairement que la validation fiscale finale reste du ressort de l’entreprise et de son comptable, et il facilite ce travail avec des documents propres et complets.
Côté sécurité, trois gardes globaux imposent l’authentification, l’appartenance au tenant et les permissions sur chaque requête. Les jetons sont à durée courte avec un rafraîchissement dans un cookie httpOnly. Une checklist de sécurité dans le dépôt suit chaque contrôle comme fait ou encore ouvert, pour que rien ne soit supposé.
Conçu prêt pour MCP : la voie vers les agents IA
YeloInvoice n’expose pas encore de serveur MCP, mais il a été construit pour qu’en ajouter un soit une fine couche et non une réécriture. Chaque capacité est exposée via une API OpenAPI 3 documentée avec des schémas typés. Les permissions sont fines et vérifiées à chaque requête. Les écritures qui comptent sont idempotentes. Ces trois propriétés sont exactement ce dont un outil MCP sûr a besoin : un schéma pour le décrire, une permission pour le contrôler, et l’idempotence pour qu’une nouvelle tentative d’un agent soit sans danger.
La couche MCP prévue suit le modèle qu’OHY Labs a utilisé sur YeloScale. Les outils de lecture pour les factures, les clients et les paiements viennent d’abord. Créer un brouillon est une écriture réversible avec clé d’idempotence. Émettre une facture ou enregistrer un paiement est une action sensible qui exige une étape préparer-puis-confirmer avec un humain dans la boucle.
- Un agent comptable qui répond à « quelles factures sont en retard ce mois-ci » à partir de données en direct.
- Un agent commercial qui rédige une facture depuis une commande confirmée et demande à un humain de l’émettre.
- Un agent de reporting qui compile les synthèses de fin de mois sans exporter de tableurs.
Ce que l’entreprise y gagne
Une PME obtient une facturation conforme, une caisse, un stock et des rapports dans sa propre langue, avec des documents prêts pour son comptable et pour le flux d’e-facturation. Elle obtient aussi une plateforme prête pour l’ère des agents : le jour où elle veut un assistant IA pour les relances, les brouillons ou le reporting, l’API, les permissions et la piste d’audit sont déjà en place.
Pour OHY Labs, YeloInvoice montre que l’ingénierie assistée par IA peut livrer du logiciel dans un domaine où les erreurs coûtent cher, tant que les spécifications, les tests et la relecture humaine restent dans la boucle.