Un moteur commun, des règles différentes
Factures, devis et contrats partagent un même besoin technique : transformer des données structurées en document. Pourtant, chaque famille possède ses propres règles, durées de conservation et étapes de validation.
L’objectif n’est pas de tout fusionner dans un template universel. Il s’agit de partager une infrastructure de génération tout en conservant des modèles et des contrats de données distincts.
Construire un pipeline commun
Le pipeline peut assurer les responsabilités transverses :
- authentifier l’application appelante ;
- vérifier son accès au template ;
- valider le payload ;
- créer un job idempotent ;
- rendre le document ;
- stocker la sortie de façon privée ;
- publier l’état et les webhooks ;
- appliquer la rétention.
Les règles propres à une facture ou à un contrat restent en amont dans le service métier.
Factures : exactitude et répétabilité
La facture nécessite des identifiants stables, des montants calculés par le système source et des mentions adaptées au contexte. Le template présente ces valeurs ; il ne devrait pas devenir le moteur comptable.
Testez notamment les arrondis affichés, les devises, les remises, les taxes multiples et les tableaux répartis sur plusieurs pages.
Devis : contenu modulaire et rapidité
Une proposition commerciale combine souvent contenu éditorial et lignes chiffrées. Des blocs réutilisables permettent de composer couverture, contexte, planning, prestations et conditions sans dupliquer tout le template.
Si vous suivez l’ouverture du document, utilisez un lien dédié et informez le destinataire selon les règles applicables à votre activité.
Contrats : contrôle et responsabilité
Un contrat exige une revue plus stricte. La version publiée doit être identifiable, les variables doivent être limitées et les clauses sensibles validées par la personne compétente.
La génération documentaire ne remplace ni le conseil juridique ni la signature électronique. Elle produit un document à partir d’un modèle approuvé.
Ne pas dupliquer les intégrations
Exposez une interface commune qui varie principalement par l’identifiant de template et le type de payload :
await documents.generate({
templateVersionId: selectedVersion,
data: businessPayload,
idempotencyKey: businessReference
});
Les équipes peuvent ainsi ajouter un nouveau type de document sans inventer un nouveau mécanisme d’authentification, de suivi ou de stockage.
Checklist d’architecture
- Un contrat de données par famille de document.
- Les calculs métier restent dans les services sources.
- Un pipeline de job commun gère rendu et observabilité.
- Les clés API sont limitées par usage.
- Chaque type possède sa politique de rétention.
- Les modèles publiés sont versionnés.
- Les événements sont rejouables sans doublon.
Questions fréquentes
Faut-il un template par client ?
Pas systématiquement. Commencez par un template partagé et des variantes de marque. Créez un template distinct lorsqu’un client possède une structure ou des obligations réellement différentes.
Où placer les conditions métier ?
Les conditions de présentation simples peuvent vivre dans le template. Les décisions financières, juridiques ou contractuelles doivent rester dans le système métier qui peut les tester et les auditer.