S'intégrer à la plateforme
Tout échange entre les domaines ou avec un système externe repose sur un contrat publié.
La composition d’un contrat
Section intitulée « La composition d’un contrat »Un contrat comprend deux fichiers publiés sous une même version :
- une notice, qui précise le sens des données ainsi que les garanties et les limites du contrat ;
- une spécification exécutable, qui décrit les chemins, les messages, les champs et leurs types.
Les interfaces synchrones sont décrites en OpenAPI et les événements en AsyncAPI. Les données échangées utilisent le format JSON.
La spécification permet de valider les échanges et de générer des clients. La notice complète cette description technique en précisant, par exemple, la signification métier d’un montant. En cas d’ambiguïté, elle fait référence pour l’interprétation des données.
Chaque contrat identifie son producteur ainsi que ses consommateurs connus.
Événement ou consultation synchrone
Section intitulée « Événement ou consultation synchrone »Les événements et les consultations répondent à des besoins différents. Un événement permet au producteur de publier un fait sans dépendre de ses consommateurs. Une consultation rend l’appelant dépendant de la disponibilité du fournisseur.
Les événements
Section intitulée « Les événements »L’événement est le mode d’échange privilégié. Il décrit un fait métier survenu et porte un nom au passé, comme « CRE comptabilisé » ou « ordre exécuté ».
Il est publié par le domaine responsable du fait, reste immuable et peut être lu par plusieurs consommateurs. Le producteur n’a pas à connaître chacun d’eux.
Les consultations synchrones
Section intitulée « Les consultations synchrones »Une consultation synchrone est utilisée lorsqu’une décision en cours exige une information à jour. Elle répond à une question précise, sans modifier l’état du fournisseur.
La consultation d’une position auprès de la tenue de compte en est un exemple. Si le fournisseur ne répond pas, la décision doit attendre : une copie locale ne peut pas garantir que l’information est encore valable.
Le contenu d’un événement
Section intitulée « Le contenu d’un événement »| Champ | Rôle |
|---|---|
| Identifiant unique | Permet de détecter un événement déjà traité. |
| Date de survenance | Indique quand le fait métier s’est produit. |
| Identifiant public de l’entité | Désigne l’entité concernée. |
| Version du contrat | Indique la version selon laquelle interpréter l’événement. |
| Numéro de séquence | Permet de détecter un événement manquant ou reçu dans le désordre. |
| Référence de causalité | Relie, le cas échéant, un événement à celui qu’il compense. |
| Charge utile | Contient les faits publiés et les identifiants nécessaires, sans exposer les représentations internes du producteur. |
Les garanties de livraison
Section intitulée « Les garanties de livraison »Les événements sont livrés au moins une fois. Un même événement peut donc être reçu plusieurs fois, mais sa livraison exactement une fois n’est pas garantie.
Les consommateurs doivent respecter trois règles :
- Traiter les événements de manière idempotente. L’identifiant unique permet d’ignorer un événement déjà traité.
- Ne supposer un ordre qu’au sein du périmètre garanti. Le numéro de séquence permet d’y détecter un manque ou un désordre. Aucun ordre global n’est garanti entre plusieurs producteurs.
- Tolérer les champs inconnus. L’ajout d’un champ compatible ne doit pas interrompre le traitement.
Ces règles s’appliquent à tous les événements. Chaque contrat précise, si nécessaire, son périmètre d’ordonnancement et ses clés d’idempotence particulières.
Le versionnement
Section intitulée « Le versionnement »Les contrats suivent un versionnement sémantique.
Une version mineure ajoute des éléments compatibles avec les consommateurs existants.
Une version majeure introduit un changement incompatible. L’ancienne version reste disponible pendant la migration et n’est pas retirée tant qu’un consommateur recensé l’utilise.
Une version 0.x désigne un contrat qui n’a pas encore atteint la stabilité. Son utilisation en production nécessite un accord explicite avec le producteur et ne bénéficie pas des mêmes garanties de compatibilité.
Les règles communes
Section intitulée « Les règles communes »Montants et quantités
Section intitulée « Montants et quantités »Les montants et les quantités sont représentés par des entiers associés à une unité explicite, par exemple des centimes ou des millionièmes de part. Les nombres à virgule flottante ne sont pas utilisés pour transporter des valeurs comptables.
Cloisonnement
Section intitulée « Cloisonnement »Aucun échange ne franchit la frontière d’un tenant. Comme un déploiement applicatif ne sert qu’un seul tenant, son identifiant n’est fourni ni dans l’adresse des interfaces métier ni dans les messages échangés.
L’appartenance au tenant découle de la configuration du déploiement ; elle n’est jamais déterminée à partir d’une valeur transmise par l’appelant. Ce mécanisme est détaillé dans Le cloisonnement.
Trouver un contrat
Section intitulée « Trouver un contrat »Chaque domaine recense ses contrats et propose une documentation interactive de ses interfaces dans la section L’API. Le panorama des domaines permet d’identifier le domaine responsable de chaque information.