S'intégrer à la plateforme

Tout échange avec la plateforme — entre ses propres domaines comme avec un système externe — passe par un contrat publié. Un contrat se lit en deux pièces qui portent la même version : une notice en prose, qui fait foi pour le sens et les garanties, et une spécification exécutable, qui fait foi pour la structure des échanges — OpenAPI pour une interface synchrone, AsyncAPI pour un événement, les charges utiles en JSON. Chaque contrat déclare aussi ses producteurs et ses consommateurs connus.

Les deux modes d’échange

L’événement est le mode par défaut : un fait métier survenu, nommé au passé (« CRE comptabilisé », « ordre exécuté »), publié par le domaine qui détient l’entité au moment où son état change. Il est immuable, et consommable par tout abonné — l’émetteur ne connaît pas ses consommateurs.

La consultation synchrone est l’exception, réservée aux lectures au moment d’une décision : une question datée, une réponse exacte, aucun effet de bord. La lecture des positions servie par la tenue de compte en est l’exemple type. Si le fournisseur ne répond pas, la décision attend — un consommateur ne décide jamais sur une copie locale potentiellement périmée.

L’anatomie d’un événement

Tout événement porte : un identifiant unique (la clé de déduplication des consommateurs), la date de survenance du fait, l’identifiant public de l’entité concernée, la version du contrat, un numéro de séquence par producteur, une référence de causalité quand le fait en compense un autre, et une charge utile qui ne transporte que des identifiants publiés et des faits — jamais la représentation interne d’un autre système.

Les garanties de livraison — et ce qu’elles exigent de vous

La plateforme garantit la livraison au moins une fois — jamais « exactement une fois ». Trois conséquences pratiques pour l’intégrateur :

• Soyez idempotents. Un événement peut arriver deux fois : l’identifiant unique fait foi, un événement déjà traité s’ignore sans erreur.
• Ne supposez l’ordre que par producteur. Le numéro de séquence permet de détecter un manque ou un désordre dans chaque flux ; rien n’est garanti sur l’entrelacement entre producteurs.
• Soyez tolérants. Un champ inconnu dans une charge utile s’ignore — il ne fait pas échouer le traitement. C’est ce qui permet aux contrats d’évoluer sans casser leurs consommateurs.

Le versionnement des contrats

Chaque contrat suit un versionnement sémantique. Un ajout compatible est une version mineure ; un changement incompatible est une version majeure, publiée en coexistence avec la précédente le temps que les consommateurs migrent — une version majeure ne se retire jamais tant qu’un consommateur recensé la référence. Un contrat en version 0.x est une proposition : instable, non opposable, en convergence avec ses premiers consommateurs.

Les règles transverses

Deux règles valent pour tous les échanges. Les montants et quantités sont des entiers munis d’une unité explicite (des centimes, des millionièmes de part…) — jamais des nombres à virgule flottante. Et le cloisonnement par teneur de compte est absolu : tout échange porte son tenant, aucun ne franchit cette frontière.