consultation-du-referentiel
Interface synchrone (OpenAPI) — version 0.2.0. Producteur : epargnant. Consommateurs déclarés : fiscalite, conformite.
Le référentiel des personnes sert ce qu’il détient — la fiche d’identité (identifiant publié, état civil d’usage, statut de cycle de vie), les qualifications fiscales datées (la situation fiscale subie, la dispense choisie, la qualification de travailleur non salarié : une PROJECTION de trois qualifications que le modèle tient distinctes, servie à TOUTE date passée comprise et jamais sans sa date, INV-EP-5), le dossier d’identification (le statut, et pour l’échange automatique d’informations le NIF et l’auto-certification) et la recherche par critères d’identité. Une personne soldée ou décédée reste servie : l’identifiant publié est stable à vie. Une date antérieure à toute qualification connue répond l’absence motivée, jamais une valeur par défaut ni une extrapolation. Toute réponse est en identifiants publiés ; aucune représentation interne ne franchit la frontière (INV-EP-12).
La spécification
Section intitulée « La spécification »openapi: 3.1.0info: title: epargnant — consultation du référentiel version: 0.2.0 summary: >- L'identité d'usage d'une personne, ses qualifications fiscales applicables à toute date, son dossier d'identification, et la recherche de la population — sans jamais exposer la structure interne du référentiel. description: >- Le référentiel des personnes sert ce qu'il détient — la fiche d'identité (identifiant publié, état civil d'usage, statut de cycle de vie), les qualifications fiscales datées (la situation fiscale subie, la dispense choisie, la qualification de travailleur non salarié : une PROJECTION de trois qualifications que le modèle tient distinctes, servie à TOUTE date passée comprise et jamais sans sa date, INV-EP-5), le dossier d'identification (le statut, et pour l'échange automatique d'informations le NIF et l'auto-certification) et la recherche par critères d'identité. Une personne soldée ou décédée reste servie : l'identifiant publié est stable à vie. Une date antérieure à toute qualification connue répond l'absence motivée, jamais une valeur par défaut ni une extrapolation. Toute réponse est en identifiants publiés ; aucune représentation interne ne franchit la frontière (INV-EP-12). x-producteurs: - epargnant x-consommateurs: - composant: fiscalite - composant: conformite # 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 de tous les chemins" 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. - version: 0.2.0 rupture: "propriété retirée : tenant, de toutes les réponses" motif: >- Isolation forte par tenant — aucun identifiant de tenant ne franchit l'interface : l'appartenance est celle de l'installation, le jeton la prouve.paths: /epargnants/{epargnant}: get: operationId: consulterLaFiche summary: >- La fiche d'identité d'une personne — identifiant publié, état civil d'usage, statut de cycle de vie. security: - authentification: [epargnant:consultation] parameters: - $ref: '#/components/parameters/epargnant' responses: '200': description: La fiche d'identité. content: application/json: schema: $ref: '#/components/schemas/FicheDIdentite' '400': description: La demande est irrecevable — le motif nomme le champ en cause. 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:consultation. '404': description: >- L'épargnant est inconnu de ce tenant — la muraille ne révèle jamais l'existence d'un épargnant d'un autre teneur de compte (INV-EP-12) : il est inexistant, pas interdit. content: application/json: schema: $ref: '#/components/schemas/Erreur' /epargnants/{epargnant}/qualifications-fiscales: get: operationId: consulterLesQualificationsFiscales summary: >- Les qualifications fiscales applicables à une date — toute date, passée comprise. description: >- Une PROJECTION de trois qualifications que le modèle tient distinctes : la situation fiscale (l'état subi — résidence et pays fiscal), la dispense fiscale (l'acte de volonté) et la qualification de travailleur non salarié. Chacune porte la période servie qui contient la date interrogée (INV-EP-5). Une qualification absente à la date demandée n'est pas rendue — jamais de valeur par défaut : le domaine ne devine pas une résidence fiscale. security: - authentification: [epargnant:consultation] parameters: - $ref: '#/components/parameters/epargnant' - name: date in: query required: true description: >- La date à laquelle les qualifications sont demandées (AAAA-MM-JJ) — toute consommation d'une qualification datée est datée ; la date vient de l'appelant. schema: type: string format: date responses: '200': description: Les qualifications applicables à la date. content: application/json: schema: $ref: '#/components/schemas/QualificationsFiscales' '400': description: >- La demande est irrecevable (date absente ou mal formée…) — le motif nomme le champ en cause. content: application/json: schema: $ref: '#/components/schemas/Erreur' '401': description: Aucune identité présentée. '403': description: L'identité présentée n'a pas la famille d'accès epargnant:consultation. '404': description: >- L'épargnant est inconnu de ce tenant — la muraille ne révèle jamais l'existence (INV-EP-12). content: application/json: schema: $ref: '#/components/schemas/Erreur' /epargnants/{epargnant}/dossier-identification: get: operationId: consulterLeDossierDIdentification summary: >- Le dossier d'identification — le statut, et pour l'échange automatique le NIF et l'auto-certification. description: >- Famille RESTREINTE, distincte de la consultation courante : la lecture ordinaire d'une personne n'ouvre pas son dossier de conformité. Le statut et les données d'échange automatique d'informations seulement — jamais le contenu d'une pièce, qui vit derrière l'adaptateur de stockage. security: - authentification: [epargnant:dossier-identification] parameters: - $ref: '#/components/parameters/epargnant' responses: '200': description: Le dossier d'identification. content: application/json: schema: $ref: '#/components/schemas/DossierDIdentification' '400': description: La demande est irrecevable — le motif nomme le champ en cause. content: application/json: schema: $ref: '#/components/schemas/Erreur' '401': description: Aucune identité présentée. '403': description: >- L'identité présentée n'a pas la famille d'accès restreinte epargnant:dossier-identification — la famille de consultation n'ouvre pas le dossier (403 croisé prouvé en test). '404': description: >- L'épargnant est inconnu de ce tenant — la muraille ne révèle jamais l'existence (INV-EP-12). content: application/json: schema: $ref: '#/components/schemas/Erreur' /epargnants: get: operationId: rechercherDesEpargnants summary: >- La recherche de la population par critères d'identité — réponse en projection de liste, jamais la fiche complète. description: >- L'énumération de la population, pour le back office — famille distincte de la consultation unitaire (une extraction de masse n'est pas une consultation de dossier). Trois gardes au contrat : des CRITÈRES MINIMAUX obligatoires (aucune énumération sans discriminant — 400 sinon), un PLAFOND de résultats (le drapeau tronque le dit quand il est atteint) et le TRAÇAGE des appels (à l'assemblage). La réponse ne porte que la projection de liste — identifiant publié, état civil d'usage, statut de cycle —, jamais la fiche complète. security: - authentification: [epargnant:recherche] parameters: - name: nom in: query required: false description: Le nom de famille (ou nom d'usage), critère de recherche. schema: type: string minLength: 1 - name: prenoms in: query required: false description: Les prénoms, critère de recherche. schema: type: string minLength: 1 - name: date_naissance in: query required: false description: >- La date de naissance (AAAA-MM-JJ) — avec le code de commune de naissance, l'un des deux critères déterministes. schema: type: string format: date - name: commune_naissance_code in: query required: false description: >- Le code INSEE de la commune de naissance (code pays INSEE pour une naissance à l'étranger) — critère déterministe, avec la date de naissance. schema: type: string minLength: 1 - name: nif in: query required: false description: Le numéro fiscal déclaratif, critère de recherche. schema: type: string minLength: 1 responses: '200': description: >- Les épargnants correspondant aux critères, en projection de liste. Une recherche sans correspondance sert une liste vide, jamais un 404. content: application/json: schema: $ref: '#/components/schemas/ResultatDeRecherche' '400': description: >- La demande est irrecevable — notamment l'absence de critère minimal (aucune énumération sans discriminant) ; le motif nomme le champ en cause. content: application/json: schema: $ref: '#/components/schemas/Erreur' '401': description: Aucune identité présentée. '403': description: L'identité présentée n'a pas la famille d'accès epargnant:recherche. '404': description: >- Le tenant du jeton n'est pas celui de l'installation — la muraille ne révèle jamais l'existence d'une population d'un autre teneur de compte (INV-EP-12). content: application/json: schema: $ref: '#/components/schemas/Erreur'components: parameters: epargnant: name: epargnant in: path required: true description: L'identifiant publié de l'épargnant chez ce tenant — stable à vie. schema: type: string minLength: 1 securitySchemes: authentification: type: http scheme: bearer description: >- L'exigence : tout appel est authentifié (401) et autorisé par famille d'accès (403 hors famille) — chaque opération déclare sa famille en portée, sous la forme epargnant:famille. Trois familles : epargnant:consultation (la lecture unitaire et ciblée), epargnant:recherche (l'énumération de la population, séparée délibérément) et epargnant:dossier-identification (restreinte). Le mécanisme est OIDC ; sa déclinaison relève de l'assemblage. schemas: FicheDIdentite: type: object description: >- L'identité d'usage d'une personne — jamais l'identité brute ni les identifiants déclaratifs (NIF, NIN), qui ne sont pas servis en consultation courante. required: [epargnant, prenoms, statut_cycle] properties: epargnant: type: string minLength: 1 description: L'identifiant publié, stable à vie. nom_usage: type: string description: >- Le nom d'usage — absent pour qui n'en déclare pas (l'état civil d'usage, pas le nom de naissance). prenoms: type: string minLength: 1 statut_cycle: type: string enum: [actif, retraite, decede] description: >- L'étape de vie : actif ; retraite (dérivée du passage à la retraite) ; decede — seul terminus. Une personne décédée reste servie : l'identifiant est stable à vie. QualificationsFiscales: type: object description: >- La PROJECTION à la date des trois qualifications fiscales datées, tenues distinctes par le modèle. Chaque qualification présente porte sa période servie ; une qualification absente à la date n'est pas rendue. required: [epargnant, date] properties: epargnant: type: string minLength: 1 description: L'identifiant publié. date: type: string format: date description: La date interrogée, servie telle qu'elle a été demandée. situation_fiscale: $ref: '#/components/schemas/SituationFiscale' dispense_fiscale: $ref: '#/components/schemas/DispenseFiscale' qualification_tns: $ref: '#/components/schemas/QualificationTns' SituationFiscale: type: object description: >- L'état subi — la résidence fiscale et le pays fiscal, servis pour la période qui contient la date interrogée. Pivot de tout assujettissement (prélèvements sociaux d'entrée, PFL, retenue à la source). required: [du, residence] properties: du: type: string format: date description: Le début de la période servie. au: type: string format: date description: La borne de fin, exclue — absente si la période est ouverte. residence: type: string enum: [R, S, C, N] description: >- R — résident fiscal France (seul cas soumis aux prélèvements sociaux d'entrée) ; S — résident France non soumis à la CSG ; C — résident CEE/EEE hors France ; N — non-résident hors CEE. pays_fiscal_iso: type: string description: Le pays de résidence fiscale, code ISO 3166-1 alpha-2. DispenseFiscale: type: object description: >- L'acte de volonté — la dispense fiscale individuelle en vigueur sur la période qui contient la date interrogée. Absence de dispense = régime normal. required: [du, type] properties: du: type: string format: date description: Le début de la période servie. au: type: string format: date description: La borne de fin, exclue — absente si la période est ouverte. type: type: string enum: [L, C, U] description: >- L — dispense de prélèvement forfaitaire libératoire sur les produits de fonds ; C — même dispense pour le compte courant bloqué ; U — dispense d'acompte de prélèvement forfaitaire unique. QualificationTns: type: object description: >- La qualification de travailleur non salarié en vigueur sur la période qui contient la date interrogée — elle conditionne le régime fiscal et social des versements. required: [du, nature] properties: du: type: string format: date description: Le début de la période servie. au: type: string format: date description: La borne de fin, exclue — absente si la période est ouverte. nature: type: string enum: [mandataire_social, conjoint_collaborateur, entrepreneur_individuel] description: La nature de la qualification. mandat_role_entreprise_id_publie: type: string description: >- L'identifiant publié du rôle d'entreprise (le mandat) qui fonde la qualification — absent quand la nature ne dérive pas d'un mandat référencé. Le rôle est détenu par le domaine Entreprise (miroir du 2026-07-27) : jamais une représentation interne. DossierDIdentification: type: object description: >- Le dossier d'identification (KYC) de la personne — statut et données d'échange automatique d'informations seulement. Le vocabulaire de statut est celui de la Conformité, qui régit le dossier. required: [epargnant, statut_kyc, auto_certification_residence] properties: epargnant: type: string minLength: 1 description: L'identifiant publié. statut_kyc: type: string enum: [ouvert, identifie, verifie, a_renouveler] description: >- L'état du dossier (vocabulaire Conformité) : ouvert (l'état d'entrée), identifie, verifie, a_renouveler. auto_certification_residence: type: boolean description: >- L'auto-certification de résidence a-t-elle été recueillie (échange automatique d'informations, CRS). nif_declare: type: string description: >- Le NIF déclaré dans l'auto-certification d'échange automatique — distinct du NIF de l'identité ; absent tant qu'aucun n'est recueilli. ResultatDeRecherche: type: object description: >- La réponse de la recherche — la projection de liste et le drapeau de plafond. required: [resultats, tronque] properties: resultats: type: array description: Les épargnants correspondant aux critères, en projection de liste. items: $ref: '#/components/schemas/EpargnantEnListe' tronque: type: boolean description: >- Vrai quand le plafond de résultats est atteint et que la liste est donc incomplète — l'appelant doit resserrer ses critères. EpargnantEnListe: type: object description: >- La projection de liste d'un épargnant — identifiant publié, état civil d'usage, statut de cycle. Jamais la fiche complète, jamais une qualification. required: [epargnant, prenoms, statut_cycle] properties: epargnant: type: string minLength: 1 description: L'identifiant publié. nom_usage: type: string description: Le nom d'usage — absent pour qui n'en déclare pas. prenoms: type: string minLength: 1 statut_cycle: type: string enum: [actif, retraite, decede] Erreur: type: object required: [motif] properties: motif: type: string description: Le motif, qui nomme le champ ou l'identifiant en cause.