cas-d-usage-du-correspondant
Interface synchrone (OpenAPI) — version 0.1.0. Producteur : diapason.
Le consommateur est le serveur d’un teneur de compte, jamais le navigateur d’un correspondant. Le correspondant est la personne que l’entreprise désigne pour administrer son dispositif ; il n’est pas notre utilisateur, et la plateforme ne sait jamais qui est devant l’écran du teneur. L’identifiant d’entreprise que porte un chemin désigne la ressource ; il ne vaut jamais autorisation. Vérifier que la personne connectée est bien correspondante de cette entreprise est une obligation du teneur de compte. Ce contrat sert le dispositif en vigueur ; il ne le dessine pas. Instituer un plan, négocier un accord, construire un abondement relèvent de Concerto, produit distinct.
La spécification
Section intitulée « La spécification »openapi: 3.1.0info: title: diapason — les cas d'usage du correspondant d'entreprise version: 0.1.0 summary: >- Ce dont un portail d'entreprise a besoin : les dispositifs en vigueur, le suivi d'une opération collective, les restitutions que la convention de tenue de compte prévoit, la population rattachée — et les deux écritures qui font vivre le dispositif. description: >- Le consommateur est le **serveur** d'un teneur de compte, jamais le navigateur d'un correspondant. Le correspondant est la personne que l'entreprise désigne pour administrer son dispositif ; il n'est pas notre utilisateur, et la plateforme ne sait jamais qui est devant l'écran du teneur.
L'identifiant d'entreprise que porte un chemin **désigne la ressource** ; il ne vaut jamais autorisation. Vérifier que la personne connectée est bien correspondante de cette entreprise est une obligation du teneur de compte.
Ce contrat sert le dispositif **en vigueur** ; il ne le dessine pas. Instituer un plan, négocier un accord, construire un abondement relèvent de Concerto, produit distinct. x-ruptures: [] x-producteurs: - diapason # Les serveurs des teneurs de compte ne sont pas recensables : un # retrait de version majeure relève du préavis contractuel, jamais d'un décompte. x-consommateurs: []servers: - url: https://{hote} description: >- Un hôte par teneur de compte — un processus ne sert qu'un tenant. Le tenant se lit à l'hôte et au jeton, jamais dans un chemin : le nom d'hôte route, l'identité autorise. variables: hote: default: passerelle.teneur.exemple description: L'hôte attribué au teneur de compte à l'activation de sa passerelle.security: - jetonPartenaire: []paths: /v1/perimetre: get: operationId: consulterLePerimetreSouscrit summary: Les cas d'usage que ce client peut exercer — lisibles par le teneur lui-même. description: >- Le périmètre souscrit se lit, il ne se devine pas à coups de 403. Il est **dérivé des politiques d'autorisation** et jamais ressaisi à côté d'elles : cette réponse est une projection de ce que le point de décision rendrait, pas une seconde source. Sa forme reste à arbitrer. responses: '200': description: Le périmètre du client qui appelle. content: application/json: schema: { $ref: '#/components/schemas/PerimetreSouscrit' } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '401': { $ref: '#/components/responses/NonAuthentifie' }
/v1/entreprises/{entreprise}/dispositifs: get: operationId: listerLesDispositifsDeLEntreprise summary: Les dispositifs en vigueur de l'entreprise. parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/correlation' - name: en_vigueur_le in: query required: false description: >- La date à laquelle apprécier « en vigueur » ; absente, aujourd'hui. Un dispositif clos reste servi pour une date passée : les opérations qui en sont issues continuent d'exister. schema: { type: string, format: date } responses: '200': description: Les dispositifs, du plus récemment institué au plus ancien. content: application/json: schema: type: object required: [lignes] properties: lignes: type: array items: { $ref: '#/components/schemas/LigneDeDispositif' } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '400': { $ref: '#/components/responses/DemandeIrrecevable' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' }
/v1/entreprises/{entreprise}/dispositifs/{dispositif}: get: operationId: consulterUnDispositifDeLEntreprise summary: Un dispositif — son paramétrage en vigueur et sa politique d'abondement. description: >- L'abondement est servi **tel que le règlement le présente** : ses règles en libellés, ses plafonds, sa période. Il n'est pas servi en paliers, portées et compteurs exécutables — un portail qui les évaluerait recalculerait notre métier et s'en écarterait. Simuler un abondement pour un versement donné est un cas d'usage distinct, aujourd'hui fermé (voir les principes du contrat). parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/dispositif' - $ref: '#/components/parameters/correlation' responses: '200': description: Le dispositif et son paramétrage en vigueur. content: application/json: schema: { $ref: '#/components/schemas/FicheDeDispositif' } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' }
/v1/entreprises/{entreprise}/operations-collectives: get: operationId: listerLesOperationsCollectives summary: Les opérations collectives de l'entreprise, filtrées et paginées. parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/correlation' - name: dispositif in: query required: false schema: { type: string, minLength: 1 } - name: exercice in: query required: false description: L'exercice au titre duquel l'opération est déclarée. schema: { type: integer } - name: en_cours in: query required: false description: Vrai pour ne rendre que les opérations dont l'exécution n'est pas achevée. schema: { type: boolean } - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/taille' responses: '200': description: La page demandée, de la plus récente à la plus ancienne. content: application/json: schema: { $ref: '#/components/schemas/PageDOperationsCollectives' } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '400': { $ref: '#/components/responses/DemandeIrrecevable' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' }
post: operationId: declarerUneOperationCollective summary: Déclarer une opération collective — le point d'entrée de l'argent de l'entreprise. description: >- La déclaration est prise en compte, elle n'est pas exécutée : la réponse est un accusé portant la référence de l'opération collective née, que `Location` désigne et que le portail suit. Deux envois de la même clé d'idempotence produisent **une** opération collective.
La répartition individuelle est transmise ici quand l'entreprise la calcule elle-même. Le teneur de compte contrôle les valeurs reçues ; il ne les reconstitue jamais. parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/idempotence' - $ref: '#/components/parameters/correlation' requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/DeclarationDOperationCollective' } responses: '202': description: >- La déclaration est prise en compte. Un rejeu de la même clé rend cette même réponse, avec la même référence. headers: Location: description: La ressource d'opération collective où suivre l'exécution. schema: { type: string } Correlation-Id: { $ref: '#/components/headers/CorrelationId' } content: application/json: schema: { $ref: '#/components/schemas/PriseEnCompte' } '400': { $ref: '#/components/responses/DemandeIrrecevable' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' } '409': { $ref: '#/components/responses/RejeuDivergent' } '422': { $ref: '#/components/responses/EcritureRefusee' }
/v1/entreprises/{entreprise}/operations-collectives/{operation}: get: operationId: suivreUneOperationCollective summary: Où en sont la répartition, l'ordre et l'exécution. description: >- Les trois étapes que le correspondant surveille, servies **décidées** : l'état de la répartition, celui de l'ordre passé au marché et celui de l'exécution. Les anomalies sont rendues en nombre et en nature, avec ce qu'il faut pour les corriger ; leur traitement appartient au teneur de compte. parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/operation' - $ref: '#/components/parameters/correlation' responses: '200': description: L'avancement de l'opération collective. content: application/json: schema: { $ref: '#/components/schemas/SuiviDOperationCollective' } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' }
/v1/entreprises/{entreprise}/restitutions: get: operationId: listerLesRestitutions summary: Les restitutions que la convention de tenue de compte prévoit. description: >- Le catalogue n'est pas une liste fixe de la plateforme : il est celui que la **convention de tenue de compte** de cette entreprise prévoit. Un correspondant y lit ce à quoi son entreprise a droit, période par période — campagnes, encours, frais. parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/correlation' - name: type in: query required: false schema: { $ref: '#/components/schemas/TypeDeRestitution' } - name: depuis in: query required: false description: Borne basse incluse, sur la fin de période de la restitution. schema: { type: string, format: date } - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/taille' responses: '200': description: La page demandée, de la plus récente à la plus ancienne. content: application/json: schema: { $ref: '#/components/schemas/PageDeRestitutions' } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '400': { $ref: '#/components/responses/DemandeIrrecevable' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' }
/v1/entreprises/{entreprise}/restitutions/{restitution}: get: operationId: consulterUneRestitution summary: Le contenu d'une restitution, en données exploitables. description: >- Les valeurs de la restitution, arrêtées à sa période et servies telles qu'elles ont été arrêtées — un chiffre de restitution ne se recalcule pas à la lecture. La même restitution servie deux fois est identique. parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/restitution' - $ref: '#/components/parameters/correlation' responses: '200': description: La restitution et ses valeurs. content: application/json: schema: { $ref: '#/components/schemas/Restitution' } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' } '409': { $ref: '#/components/responses/AgregatRetenu' }
/v1/entreprises/{entreprise}/restitutions/{restitution}/contenu: get: operationId: telechargerUneRestitution summary: Le document de la restitution, quand la convention en prévoit un. parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/restitution' - $ref: '#/components/parameters/correlation' responses: '200': description: Le document, dans le format annoncé par la fiche de restitution. content: application/pdf: schema: { type: string, format: binary } text/csv: schema: { type: string } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': description: >- 404 — la restitution est inconnue de ce teneur, ou la convention n'en prévoit aucun document. content: application/json: schema: { $ref: '#/components/schemas/Erreur' }
/v1/entreprises/{entreprise}/personnes: get: operationId: listerLesPersonnesDeLEntreprise summary: Les personnes rattachées à l'entreprise, et leur situation courante. description: >- Le référentiel dit **personne dans l'entreprise**, et non « salarié » : le terme couvre aussi les chefs d'entreprise, mandataires sociaux et conjoints, qui ont accès à certains dispositifs. Chaque ligne porte la situation courante, jamais l'historique de ce que l'entreprise a déclaré. parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/correlation' - name: presence in: query required: false description: Restreindre aux personnes présentes ou sorties ; absent, les deux. schema: { type: string, enum: [PRESENTE, SORTIE] } - name: etablissement in: query required: false schema: { type: string, minLength: 1 } - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/taille' responses: '200': description: La page demandée, par matricule croissant. content: application/json: schema: { $ref: '#/components/schemas/PageDePersonnes' } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '400': { $ref: '#/components/responses/DemandeIrrecevable' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' }
/v1/entreprises/{entreprise}/transmissions: post: operationId: transmettreLaPopulation summary: Transmettre les mouvements de population — entrées, sorties, mises à disposition. description: >- La transmission est prise en compte, elle n'est pas appliquée : elle est contrôlée, et ses écarts sont rendus par la ressource que `Location` désigne. Deux envois de la même clé d'idempotence produisent **une** transmission.
Un mouvement porte le **matricule** que l'entreprise donne à la personne dans ses propres systèmes ; c'est par lui que le rapprochement se fait. La plateforme n'écrit jamais une identité depuis une transmission — elle rapproche, et signale ce qu'elle ne sait pas rapprocher. parameters: - $ref: '#/components/parameters/entreprise' - $ref: '#/components/parameters/idempotence' - $ref: '#/components/parameters/correlation' requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/TransmissionDePopulation' } responses: '202': description: La transmission est prise en compte et son contrôle est engagé. headers: Location: description: La ressource de transmission où lire l'avancement et les écarts. schema: { type: string } Correlation-Id: { $ref: '#/components/headers/CorrelationId' } content: application/json: schema: { $ref: '#/components/schemas/PriseEnCompte' } '400': { $ref: '#/components/responses/DemandeIrrecevable' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' } '409': { $ref: '#/components/responses/RejeuDivergent' } '422': { $ref: '#/components/responses/EcritureRefusee' }
/v1/entreprises/{entreprise}/transmissions/{transmission}: get: operationId: suivreUneTransmission summary: L'avancement d'une transmission et les écarts constatés. description: >- Les écarts sont ceux que le contrôle a retenus, avec de quoi les corriger : un matricule inconnu, une sortie sans date, une personne déjà sortie. Ce sont eux que le correspondant traite ; la transmission n'est jamais rejetée en bloc pour un écart isolé. parameters: - $ref: '#/components/parameters/entreprise' - name: transmission in: path required: true description: La référence de la transmission, telle que la prise en compte l'a publiée. schema: { type: string, minLength: 1 } - $ref: '#/components/parameters/correlation' responses: '200': description: L'avancement de la transmission et ses écarts. content: application/json: schema: { $ref: '#/components/schemas/SuiviDeTransmission' } headers: Correlation-Id: { $ref: '#/components/headers/CorrelationId' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/HorsPerimetre' } '404': { $ref: '#/components/responses/Inconnu' }
components: securitySchemes: jetonPartenaire: type: http scheme: bearer bearerFormat: JWT description: >- Le jeton est obtenu par le **client credentials grant** OAuth 2.0 : l'appelant est le serveur du teneur de compte, pas une personne. Il est validé comme par tout serveur de ressources — signature, émetteur, dates, audience, tenant comparé au tenant du déploiement.
**L'audience est celle de ce contrat.** Le jeton doit avoir été obtenu pour la surface du correspondant : un jeton obtenu pour celle de l'épargnant est rejeté en `401`, et non en `403` — il ne nous était pas adressé, ce n'est pas un droit qui manque. C'est ce qui confine les écritures de cette surface, dont la déclaration d'une opération collective : un portail d'épargnant compromis ne les atteint pas. Un client enregistré ne sert qu'un teneur de compte ; il peut en revanche servir les deux surfaces, si son enregistrement l'y autorise.
**Le jeton authentifie, il n'autorise pas** : aucune portée, aucun claim propriétaire n'accorde quoi que ce soit. L'autorisation est rendue à chaque appel par le point de décision, sur la question relationnelle « ce client sert-il le teneur dont relève la ressource, et ce cas d'usage est-il dans son périmètre souscrit ? ». La liste de portées de ce schéma est vide, et c'est intentionnel.
headers: CorrelationId: description: L'identifiant de corrélation reçu, restitué tel quel — la jointure entre le journal du teneur et le nôtre. schema: { type: string, minLength: 1, maxLength: 128 }
parameters: entreprise: name: entreprise in: path required: true description: >- L'identifiant publié de l'entreprise chez ce teneur de compte. Il **désigne la ressource** ; un identifiant d'entreprise dans une URL ne vaut jamais autorisation. schema: { type: string, minLength: 1 } dispositif: name: dispositif in: path required: true description: L'identifiant publié du dispositif — plan d'épargne ou mécanisme de partage de la valeur. schema: { type: string, minLength: 1 } operation: name: operation in: path required: true description: La référence de l'opération collective, telle que la plateforme l'a publiée. schema: { type: string, minLength: 1 } restitution: name: restitution in: path required: true description: La référence de la restitution, telle que le catalogue la publie. schema: { type: string, minLength: 1 } correlation: name: Correlation-Id in: header required: true description: >- L'identifiant que le teneur de compte donne à l'échange dans **son** journal. Obligatoire : notre trace dit qui a lu quoi, jamais pour qui, et ce champ est la seule jointure entre les deux journaux. Il est restitué dans la réponse. schema: { type: string, minLength: 1, maxLength: 128 } idempotence: name: Idempotency-Key in: header required: true description: >- La clé d'idempotence de l'écriture, choisie par l'appelant. Un serveur tiers réessaie : deux envois de la même clé produisent **un** effet. Le rejeu à charge identique rend la réponse d'origine ; le rejeu à charge différente est refusé. schema: { type: string, minLength: 8, maxLength: 128 } page: name: page in: query required: false description: >- L'ordre est fixé par un critère stable : une page suivante ne saute ni ne répète une ligne, même si des lignes naissent entre deux appels. schema: { type: integer, minimum: 0, default: 0 } taille: name: taille in: query required: false schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
responses: DemandeIrrecevable: description: 400 — la demande est mal formée ; le motif nomme le champ en cause. content: application/json: schema: { $ref: '#/components/schemas/Erreur' } NonAuthentifie: description: >- 401 — aucune identité présentée, ou jeton invalide : signature, émetteur, dates, tenant, ou **audience obtenue pour une autre surface**. La réponse porte `WWW-Authenticate: Bearer error="invalid_token"`. headers: WWW-Authenticate: description: Le défi d'authentification, au format des jetons porteurs. schema: { type: string } content: application/json: schema: { $ref: '#/components/schemas/Erreur' } HorsPerimetre: description: >- 403 — le cas d'usage n'est pas dans le périmètre souscrit de ce client. La réponse ne dit jamais si la ressource existe. content: application/json: schema: { $ref: '#/components/schemas/Erreur' } Inconnu: description: >- 404 — inconnu de ce teneur de compte. Une entreprise, un dispositif ou une opération relevant d'un autre teneur est *inexistant*, jamais *interdit* : la muraille de Chine ne laisse pas fuir une existence. content: application/json: schema: { $ref: '#/components/schemas/Erreur' } RejeuDivergent: description: >- 409 — cette clé d'idempotence a déjà servi, avec une charge utile différente. Rien n'a été engagé. content: application/json: schema: { $ref: '#/components/schemas/Erreur' } AgregatRetenu: description: >- 409 — la restitution existe mais son contenu est **retenu** : le nombre de porteurs derrière l'agrégat est sous le plancher d'agrégation du teneur, et le servir approcherait le patrimoine d'une personne. Ce n'est ni une erreur du portail ni un droit qui manque — c'est une protection, et elle se lève quand la population s'étoffe. Le motif est destiné à être affiché tel quel. content: application/json: schema: { $ref: '#/components/schemas/Erreur' } EcritureRefusee: description: >- 422 — la demande est bien formée mais l'écriture est refusée par le métier : dispositif clos à la période déclarée, exercice déjà arrêté, montant global incohérent avec la répartition transmise. content: application/json: schema: { $ref: '#/components/schemas/Erreur' }
schemas: PerimetreSouscrit: type: object required: [client, contrat, audience, version, cas_d_usage] properties: client: type: string description: L'identifiant du client OAuth qui appelle — le sujet de l'autorisation. contrat: type: string description: Le contrat concerné (« cas-d-usage-du-correspondant »). audience: type: string description: >- L'audience pour laquelle un jeton doit être obtenu afin d'exercer ce contrat — la valeur à demander au point de jeton. Un client qui sert aussi la surface de l'épargnant lit l'autre audience dans l'autre contrat. version: type: string description: La version du contrat servie par ce déploiement. cas_d_usage: type: array description: >- Les `operationId` que ce client peut exercer. Un cas d'usage absent répond 403 sans révéler l'existence de la ressource. items: { type: string } entreprises: type: array description: >- Les entreprises sur lesquelles ce client peut agir, quand son périmètre en nomme une liste fermée. Absent, il porte sur toutes les entreprises du teneur. items: { type: string }
LigneDeDispositif: type: object required: [dispositif, libelle, type, cadre_legal, etat, periode] properties: dispositif: { type: string } libelle: { type: string } type: type: string description: >- Le type de dispositif — PEE, PEI, PERECO, participation, intéressement, supplément, prime de partage de la valeur — dans la nomenclature publiée par le domaine Entreprise. cadre_legal: { $ref: '#/components/schemas/CadreLegal' } etat: type: string description: L'état courant du dispositif, servi tel que le domaine Entreprise le porte. periode: { $ref: '#/components/schemas/Periode' }
CadreLegal: type: string description: >- Le cadre légal dont relèvent les avoirs du dispositif — il se lit, il ne se déduit pas du type. enum: [epargne-salariale, plan-epargne-retraite]
FicheDeDispositif: type: object required: [dispositif, libelle, type, cadre_legal, etat, periode] properties: dispositif: { type: string } libelle: { type: string } type: { type: string } cadre_legal: { $ref: '#/components/schemas/CadreLegal' } etat: { type: string } periode: { $ref: '#/components/schemas/Periode' } derniere_alimentation: type: [string, 'null'] format: date description: >- La date du dernier fait d'acquisition inscrit au dispositif — « le PERCO n'est plus alimenté depuis mars 2023 » se lit ici. Null pour un dispositif jamais alimenté, ce qui n'est pas la même chose qu'un dispositif clos. actes: type: array description: >- Les actes qui fondent, modifient ou clôturent le dispositif — leurs métadonnées seulement ; le document vit dans la gestion documentaire. items: type: object required: [acte, nature, role, signe_le] properties: acte: { type: string } nature: { type: string, description: Accord, règlement, avenant ou décision unilatérale. } role: { type: string, enum: [FONDE, MODIFIE, CLOTURE] } signe_le: { type: string, format: date } abondement: $ref: '#/components/schemas/AbondementEnVigueur' supports: type: array description: Les supports que le dispositif autorise, dans son offre en vigueur. items: type: object required: [support, libelle, ouvert_aux_versements] properties: support: { type: string } libelle: { type: string } classification: { type: string } ouvert_aux_versements: { type: boolean }
AbondementEnVigueur: type: object description: >- La politique d'abondement **telle qu'elle se présente**, pour être affichée et comprise. Elle n'est pas servie en portées, compteurs et paliers exécutables : la résolution d'un abondement pour un versement donné appartient au domaine qui la calcule. required: [periode, regles] properties: periode: { $ref: '#/components/schemas/Periode' } empreinte: type: string description: >- La signature du paramétrage en vigueur — elle permet au correspondant et au teneur de parler de la même version. regles: type: array items: type: object required: [libelle, enonce] properties: libelle: { type: string } enonce: type: string description: La règle énoncée en clair, destinée à être affichée telle quelle. plafond: type: string description: La limite, énoncée en clair — montant, période et ce sur quoi elle se compte.
PageDOperationsCollectives: type: object required: [lignes, total] properties: lignes: type: array items: { $ref: '#/components/schemas/LigneDOperationCollective' } total: type: [integer, 'null'] description: >- Le nombre total de lignes du filtre — **null quand il ne se compte pas à coût raisonnable**. Un portail pagine sans total ; il ne le fabrique pas.
LigneDOperationCollective: type: object required: [operation, dispositif, nature, etat, declaree_le] properties: operation: { type: string } dispositif: { type: string } nature: type: string description: La nature de l'opération collective, dans la nomenclature publiée par les Opérations. etat: { type: string } exercice: { type: integer } declaree_le: { type: string, format: date } montant_global_ct: { type: integer } beneficiaires: { type: integer, description: Le nombre de bénéficiaires de la répartition. }
SuiviDOperationCollective: type: object required: [operation, dispositif, nature, etat, repartition, execution] properties: operation: { type: string } dispositif: { type: string } nature: { type: string } etat: { type: string } exercice: { type: integer } montant_global_ct: { type: integer } repartition: type: object required: [etat, beneficiaires] properties: etat: { type: string, description: L'état de la répartition, servi décidé. } beneficiaires: { type: integer } montant_reparti_ct: { type: integer } arretee_le: { type: string, format: date-time } ordre: type: object description: Le passage au marché — absent tant qu'aucun ordre n'est né. properties: etat: { type: string } date_centralisation: { type: string, format: date } execution: type: object required: [etat] properties: etat: { type: string } date_execution: { type: string, format: date } date_reglement: { type: string, format: date } anomalies: type: array description: >- Les anomalies retenues, en nombre et en nature, avec de quoi les corriger. Leur traitement appartient au teneur de compte. items: type: object required: [nature, nombre] properties: nature: { type: string } nombre: { type: integer } precision: { type: string, description: Destinée à être affichée telle quelle. }
TypeDeRestitution: type: string description: >- Le vocabulaire clos des restitutions servies. Ce que chaque type contient dépend de la convention de tenue de compte de l'entreprise. enum: - CAMPAGNE - ENCOURS - FRAIS
PageDeRestitutions: type: object required: [lignes, total] properties: lignes: type: array items: { $ref: '#/components/schemas/LigneDeRestitution' } total: type: [integer, 'null'] description: >- Le nombre total de lignes du filtre — **null quand il ne se compte pas à coût raisonnable**. Un portail pagine sans total ; il ne le fabrique pas.
LigneDeRestitution: type: object required: [restitution, type, libelle, periode, arretee_le] properties: restitution: { type: string } type: { $ref: '#/components/schemas/TypeDeRestitution' } libelle: { type: string } periode: { $ref: '#/components/schemas/Periode' } arretee_le: { type: string, format: date-time } format_du_document: type: string enum: [application/pdf, text/csv] description: Absent quand la convention ne prévoit aucun document pour cette restitution.
Restitution: type: object required: [restitution, type, libelle, periode, arretee_le, valeurs] properties: restitution: { type: string } type: { $ref: '#/components/schemas/TypeDeRestitution' } libelle: { type: string } periode: { $ref: '#/components/schemas/Periode' } arretee_le: { type: string, format: date-time } valeurs: type: array description: >- Les valeurs arrêtées, chacune avec son libellé et son unité. La forme reste volontairement plate : la composition d'une restitution dépend de la convention, et la figer en schéma reviendrait à imposer une convention unique. items: type: object required: [libelle, unite] properties: libelle: { type: string } unite: type: string enum: [CENTIME_EURO, NOMBRE, QUANTITE_INSTRUMENT] description: >- `QUANTITE_INSTRUMENT` désigne une quantité dans l'unité de l'instrument, publiée par le référentiel des instruments : une restitution d'encours porte aujourd'hui des **quantités**, sa valorisation en euros attendant la projection de valorisation courante de la tenue de compte. valeur_entiere: { type: integer, description: La valeur, dans l'unité déclarée — jamais un flottant. } instrument: { type: string, description: L'instrument concerné, quand l'unité est une quantité. } dispositif: { type: string, description: Le dispositif concerné, quand la ligne en vise un. }
PageDePersonnes: type: object required: [lignes, total] properties: lignes: type: array items: { $ref: '#/components/schemas/LignePersonne' } total: type: [integer, 'null'] description: >- Le nombre total de lignes du filtre — **null quand il ne se compte pas à coût raisonnable**. Un portail pagine sans total ; il ne le fabrique pas.
LignePersonne: type: object required: [matricule, presence, type_activite] properties: matricule: type: string description: L'identifiant que l'entreprise donne à la personne dans ses propres systèmes. epargnant: type: string description: >- L'identifiant publié de l'épargnant, quand le rapprochement a abouti. Absent tant qu'il n'a pas abouti — c'est alors un écart de la dernière transmission. presence: { type: string, enum: [PRESENTE, SORTIE] } type_activite: type: string description: >- Salariée, chef d'entreprise, mandataire social, conjoint collaborateur ou conjoint associé — le titre auquel la personne est rattachée. etablissement: { type: string } date_entree: { type: string, format: date } date_sortie: { type: string, format: date }
DeclarationDOperationCollective: type: object required: [dispositif, nature, exercice, montant_global_ct, repartition] properties: dispositif: { type: string } nature: type: string description: La nature déclarée, dans la nomenclature publiée par les Opérations. exercice: type: integer description: L'exercice au titre duquel l'opération est déclarée. periode: { $ref: '#/components/schemas/Periode' } montant_global_ct: type: integer minimum: 1 description: >- Le montant global déclaré, en centimes. La somme de la répartition lui est confrontée : un écart est refusé, jamais absorbé. date_versement_souhaitee: { type: string, format: date } repartition: type: array minItems: 1 description: La répartition individuelle calculée par l'entreprise, par matricule. items: type: object required: [matricule, montant_ct] properties: matricule: { type: string } montant_ct: { type: integer, minimum: 0 } reference_du_teneur: { type: string }
TransmissionDePopulation: type: object required: [mouvements] properties: arretee_le: type: string format: date description: La date à laquelle l'entreprise a arrêté ces mouvements. mouvements: type: array minItems: 1 maxItems: 10000 description: >- Les mouvements de la période. Au-delà de la borne, la transmission se découpe : une écriture partenaires reste une écriture, pas un transfert de fichier. items: { $ref: '#/components/schemas/MouvementDePopulation' } reference_du_teneur: { type: string }
MouvementDePopulation: type: object required: [matricule, action, date_effet] properties: matricule: { type: string } action: type: string enum: [ENTREE, SORTIE, MISE_A_DISPOSITION] description: >- L'entrée d'une personne dans l'entreprise, sa sortie, ou sa mise à disposition auprès d'une autre entreprise du périmètre. date_effet: { type: string, format: date } type_activite: { type: string } etablissement: { type: string } motif_sortie: type: string description: >- La raison pour laquelle la relation de travail est déclarée terminée — dont la retraite et la préretraite. C'est une qualification du départ **dans cette entreprise**, jamais une qualité universelle de la personne.
SuiviDeTransmission: type: object required: [transmission, etat, recue_le, mouvements_recus, mouvements_appliques, ecarts] properties: transmission: { type: string } etat: { type: string } recue_le: { type: string, format: date-time } mouvements_recus: { type: integer } mouvements_appliques: { type: integer } ecarts: type: array description: >- Le tableau vide signifie « aucun écart ». Un écart isolé ne rejette pas la transmission : les autres mouvements s'appliquent. items: type: object required: [ligne, nature, precision] properties: ligne: { type: integer, description: Le rang du mouvement dans la transmission, à partir de 1. } matricule: { type: string } nature: { type: string, description: La nature de l'écart, dans le vocabulaire clos que le domaine publie. } precision: { type: string, description: De quoi le corriger, destinée à être affichée telle quelle. }
Periode: type: object required: [debut] properties: debut: { type: string, format: date } fin: { type: string, format: date, description: Absente pour une période encore ouverte. }
PriseEnCompte: type: object required: [reference, etat, recu_le] properties: reference: type: string description: La référence de ce qui est né — celle que `Location` désigne. etat: { type: string } recu_le: { type: string, format: date-time } reference_du_teneur: { type: string }
Erreur: type: object required: [code, motif] properties: code: type: string description: >- Le code stable sur lequel un portail se branche — le motif, lui, est écrit pour être lu par une personne et peut changer sans rupture. enum: - DEMANDE_MAL_FORMEE - CHAMP_INVALIDE - NON_AUTHENTIFIE - HORS_PERIMETRE_SOUSCRIT - RESSOURCE_INCONNUE - REJEU_DIVERGENT - ECRITURE_REFUSEE - AGREGAT_RETENU motif: type: string description: Le motif, qui nomme le champ ou l'identifiant en cause. champ: type: string description: Le champ en cause, quand l'erreur en désigne un. correlation: type: string description: L'identifiant de corrélation de l'appel — le même que l'en-tête restitué.