rapprochement-d-identite
Interface synchrone (OpenAPI) — version 0.2.0. Producteur : epargnant. Consommateurs déclarés : entreprise.
L’Entreprise soumet un LOT d’identités déclarées (le lot des salariés d’une signalétique) et reçoit un sort LIGNE À LIGNE, partiel par nature. Trois issues, et trois seulement : résolu-existant (une personne correspond sans ambiguïté, son identifiant publié est renvoyé), resolu-cree (aucune ne correspond, le domaine crée la personne et renvoie son identifiant neuf), rejete (plusieurs personnes candidates — aucune création, aucun choix par approximation ; la ligne est rejetée avec son motif ambiguite). Une ligne ambiguë ne crée jamais de personne ni de lien (INV-EP-14). Le demandeur ne reçoit qu’une issue par ligne : JAMAIS la liste des personnes candidates — l’issue rejete dit qu’il y a ambiguïté, pas qui la compose. Chaque ligne porte sa clé de rapprochement RH, du système de ressources humaines du client, qui joue deux rôles et deux seulement : corréler la réponse à la ligne soumise (l’Entreprise apparie sans réordonner) et rendre l’appel idempotent par cle_rapprochement_rh, dans le tenant de l’installation — deux soumissions de la même ligne ne créent pas deux personnes. Le domaine NE STOCKE PAS cette clé : elle transite pour la corrélation et l’idempotence. Le lot admet un sort partiel : un rejet n’invalide pas les résolutions du même lot.
La spécification
Section intitulée « La spécification »openapi: 3.1.0info: title: epargnant — rapprochement d'identité version: 0.2.0 summary: >- Répondre à une identité déclarée par l'identifiant publié de la personne — sans écrire le lien du demandeur. description: >- L'Entreprise soumet un LOT d'identités déclarées (le lot des salariés d'une signalétique) et reçoit un sort LIGNE À LIGNE, partiel par nature. Trois issues, et trois seulement : résolu-existant (une personne correspond sans ambiguïté, son identifiant publié est renvoyé), resolu-cree (aucune ne correspond, le domaine crée la personne et renvoie son identifiant neuf), rejete (plusieurs personnes candidates — aucune création, aucun choix par approximation ; la ligne est rejetée avec son motif ambiguite). Une ligne ambiguë ne crée jamais de personne ni de lien (INV-EP-14). Le demandeur ne reçoit qu'une issue par ligne : JAMAIS la liste des personnes candidates — l'issue rejete dit qu'il y a ambiguïté, pas qui la compose. Chaque ligne porte sa clé de rapprochement RH, du système de ressources humaines du client, qui joue deux rôles et deux seulement : corréler la réponse à la ligne soumise (l'Entreprise apparie sans réordonner) et rendre l'appel idempotent par cle_rapprochement_rh, dans le tenant de l'installation — deux soumissions de la même ligne ne créent pas deux personnes. Le domaine NE STOCKE PAS cette clé : elle transite pour la corrélation et l'idempotence. Le lot admet un sort partiel : un rejet n'invalide pas les résolutions du même lot. x-producteurs: - epargnant x-consommateurs: - composant: entreprise # Le différentiel de compatibilité exige que toute rupture entre deux # versions publiées soit DÉCLARÉE ici. x-ruptures: - version: 0.2.0 rupture: "chemins déplacés : le préfixe /tenants/{tenant} disparaît du chemin" motif: >- Le tenant n'entre jamais dans le chemin d'une interface : il est résolu à l'assemblage — routage par l'hôte, audience du jeton — jamais par une donnée d'appel. Le paramètre de chemin tenant disparaît avec le préfixe ; l'idempotence s'énonce désormais par cle_rapprochement_rh, dans le tenant de l'installation.paths: /rapprochements-identite: post: operationId: rapprocherUnLotDIdentites summary: >- Soumettre un lot d'identités déclarées et recevoir un sort par ligne — résolu (existant ou créé) ou rejeté pour ambiguïté. description: >- Le corps est un TABLEAU de lignes déclarées ; la réponse un tableau de sorts, un par ligne, corrélés par cle_rapprochement_rh (l'Entreprise apparie sans réordonner). Chaque ligne porte l'identité déclarée — nom, nom d'usage, prénoms, et les DEUX CRITÈRES DÉTERMINISTES du rapprochement : date de naissance et commune de naissance. Idempotence par cle_rapprochement_rh, dans le tenant de l'installation : une re-soumission d'une ligne déjà résolue rend la même issue et le même identifiant, sans nouvelle création ; une ligne rejetée re-soumise inchangée reste rejetée. Sort partiel admis : chaque ligne a son issue indépendante, un rejet n'invalide pas les résolutions du même lot — aucune transaction d'ensemble. Le seuil du rapprochement (la combinaison exacte des critères, les homonymes) relève de la conception du service de dédoublonnage, hors de ce contrat ; son résultat — les trois issues — est stable et contractualisé. security: - authentification: [epargnant:rapprochement] requestBody: required: true description: Le lot d'identités déclarées — au moins une ligne. content: application/json: schema: type: array minItems: 1 description: >- Le tableau des lignes déclarées. La borne supérieure de taille du lot n'est pas encore tranchée (à caler sur le volume réel d'une signalétique) : elle se fixera avec le premier chargement réel de l'Entreprise. items: $ref: '#/components/schemas/LigneDeclaree' responses: '200': description: >- Le sort du lot — un tableau de sorts, un par ligne soumise, corrélés par cle_rapprochement_rh. Sort partiel admis. content: application/json: schema: type: array items: $ref: '#/components/schemas/SortDeLigne' '400': description: >- La demande est irrecevable (corps mal formé, critère déterministe manquant, date mal formée…) — le motif nomme le champ. Un rejet de forme porte sur le lot entier, distinct du rejet métier d'une ligne (issue rejete). content: application/json: schema: $ref: '#/components/schemas/Erreur' '401': description: >- Aucune identité présentée (l'exigence est du contrat, le mécanisme de l'assemblage). '403': description: >- L'identité présentée n'a pas la famille d'accès epargnant:rapprochement — la seule qui autorise une écriture. Les 403 croisés sont prouvés : ni epargnant:consultation, ni epargnant:recherche, ni epargnant:dossier-identification n'ouvrent le rapprochement. '404': description: >- Le tenant du jeton n'est pas celui de l'installation — la muraille ne révèle jamais l'existence d'une donnée d'un autre tenant (INV-EP-12). content: application/json: schema: $ref: '#/components/schemas/Erreur'components: securitySchemes: authentification: type: http scheme: bearer description: >- L'exigence : tout appel est authentifié (401) et autorisé par famille d'accès (403 hors famille) — l'opération déclare sa famille en portée, sous la forme epargnant:famille. La seule famille du domaine ouverte à une écriture est epargnant:rapprochement (restreinte — elle peut créer une personne). Le mécanisme est OIDC ; sa déclinaison relève de l'assemblage. schemas: LigneDeclaree: type: object description: >- Une identité déclarée par l'Entreprise, avec sa clé de corrélation. Les deux critères déterministes du rapprochement sont date_naissance et commune_naissance_code. required: - cle_rapprochement_rh - nom - prenoms - date_naissance - commune_naissance_code properties: cle_rapprochement_rh: type: string minLength: 1 description: >- La clé de rapprochement du système de ressources humaines du client. Corrèle la réponse à la ligne et rend l'appel idempotent, dans le tenant de l'installation. Non stockée par le domaine — elle transite pour la corrélation et l'idempotence. nom: type: string minLength: 1 description: Le nom de naissance déclaré. nom_usage: type: string description: Le nom d'usage déclaré, s'il diffère du nom de naissance. prenoms: type: string minLength: 1 description: Les prénoms déclarés. date_naissance: type: string format: date description: La date de naissance déclarée — premier critère déterministe. commune_naissance_code: type: string minLength: 1 description: Le code de la commune de naissance déclarée — second critère déterministe. SortDeLigne: type: object description: >- Le sort d'une ligne, corrélé à la ligne soumise par cle_rapprochement_rh. Une issue et, au plus, un identifiant publié — jamais de liste de personnes candidates. required: - cle_rapprochement_rh - issue properties: cle_rapprochement_rh: type: string minLength: 1 description: La clé de la ligne soumise — corrélation, sans réordonnancement. issue: type: string enum: [resolu-existant, resolu-cree, rejete] description: >- resolu-existant — une personne correspond sans ambiguïté ; resolu-cree — aucune ne correspond, le domaine a créé la personne ; rejete — plusieurs personnes candidates, aucune création ni choix par approximation. epargnant_id: type: string minLength: 1 description: >- L'identifiant publié de l'épargnant — présent en cas de résolution (resolu-existant ou resolu-cree), absent en cas de rejet. motif: type: string enum: [ambiguite] description: >- Le motif du rejet — présent en cas de rejet (issue rejete), absent sinon. L'issue dit qu'il y a ambiguïté, jamais qui la compose. Erreur: type: object required: [motif] properties: motif: type: string description: Le motif, qui nomme le champ ou l'identifiant en cause.