administration-du-referentiel

Interface synchrone (OpenAPI) — version 0.2.0. Producteur : conformite. Consommateurs déclarés : backoffice.

Ce que ce contrat montre est ce que le moteur applique — même référentiel, mêmes versions datées. Toute interface est authentifiée (401) ; le refus (403) et la seconde validation (202) relèvent du point d’application de la politique.

La spécification

openapi: 3.1.0
info:
  title: conformite — administration du référentiel
  version: 0.2.0
  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.
  summary: >-
    Administrer le référentiel versionné : versions de scénarios, politiques de
    vigilance, activation des versions de listes, exceptions bornées, déclaration des
    jalons d'évaluation.
  description: >-
    Ce que ce contrat montre est ce que le moteur applique — même référentiel, mêmes
    versions datées. Toute interface est authentifiée (401) ; le refus (403) et la
    seconde validation (202) relèvent du point d'application de la politique.
  x-producteurs:
    - conformite
  x-consommateurs:
    - backoffice
paths:
  /scenarios:
    get:
      operationId: consulterLeCatalogueDesScenarios
      summary: Le catalogue des scénarios et, pour chacun, ses versions datées.
      security: [ { authentification: [conformite:parametrage] } ]
      responses:
        '200':
          description: Les scénarios, avec leurs versions et dates d'effet.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Scenarios' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
  /scenarios/{scenario}/versions:
    post:
      operationId: proposerUneVersionDeScenario
      summary: Proposer une version nouvelle datée des paramètres — jamais modifier l'active.
      security: [ { authentification: [conformite:parametrage] } ]
      parameters:
        - $ref: '#/components/parameters/scenario'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NouvelleVersionDeScenario' }
      responses:
        '201':
          description: La version est créée, en attente d'homologation puis d'activation.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VersionDeScenario' }
        '400': { $ref: '#/components/responses/Irrecevable' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
        '404': { $ref: '#/components/responses/Inconnu' }
  /scenarios/{scenario}/versions/{version}/activation:
    post:
      operationId: activerUneVersionDeScenario
      summary: Activer une version homologuée, à sa date d'effet.
      description: >-
        Refusée sans homologation constituée — jeu d'épreuve vert, analyse d'impact,
        propriétaire (409). Geste d'armement de la détection : premier candidat à la
        seconde validation (202, politique du PEP).
      security: [ { authentification: [conformite:parametrage] } ]
      parameters:
        - $ref: '#/components/parameters/scenario'
        - name: version
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Activation' }
      responses:
        '201':
          description: L'activation est posée, avec sa date d'effet.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VersionDeScenario' }
        '202':
          description: Suspendue à une seconde validation.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VersionDeScenario' }
        '400': { $ref: '#/components/responses/Irrecevable' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
        '404': { $ref: '#/components/responses/Inconnu' }
        '409':
          description: L'homologation n'est pas constituée, ou la version n'est pas activable.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Erreur' }
  /politiques-vigilance:
    get:
      operationId: consulterLesPolitiquesDeVigilance
      summary: Les politiques de vigilance et leurs lignes datées.
      security: [ { authentification: [conformite:parametrage] } ]
      responses:
        '200':
          description: Les lignes datées en vigueur et à venir.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PolitiquesDeVigilance' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
    post:
      operationId: poserUneLigneDePolitique
      summary: Poser une ligne nouvelle datée — un seuil se change ainsi, jamais en code.
      security: [ { authentification: [conformite:parametrage] } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NouvelleLigneDePolitique' }
      responses:
        '201':
          description: La ligne datée est posée.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LigneDePolitique' }
        '202':
          description: Suspendue à une seconde validation.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LigneDePolitique' }
        '400': { $ref: '#/components/responses/Irrecevable' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
  /listes:
    get:
      operationId: consulterLesListes
      summary: Les sources autorisées et l'état de leurs versions ingérées.
      description: >-
        Une version en QUARANTAINE n'a pas remplacé la dernière version sûre — l'état le
        montre. La fraîcheur d'une source en retard est une alerte d'exploitation.
      security: [ { authentification: [conformite:parametrage] } ]
      responses:
        '200':
          description: Les sources, leurs versions et leurs états d'ingestion.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Listes' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
  /listes/{source}/versions/{version}/activation:
    post:
      operationId: activerUneVersionDeListe
      summary: Activer une version ingérée — procédure ordinaire ou urgente.
      description: >-
        L'activation URGENTE (publication d'une désignation) allège les contrôles a
        priori, jamais la revue a posteriori : le geste l'enregistre comme due. Une
        version en quarantaine n'est pas activable (409).
      security: [ { authentification: [conformite:parametrage] } ]
      parameters:
        - name: source
          in: path
          required: true
          schema: { type: string }
        - name: version
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ActivationDeListe' }
      responses:
        '201':
          description: >-
            La version est activée ; si une campagne de re-criblage du stock est due,
            sa référence est rendue.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VersionDeListeActivee' }
        '202':
          description: Suspendue à une seconde validation.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VersionDeListeActivee' }
        '400': { $ref: '#/components/responses/Irrecevable' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
        '404': { $ref: '#/components/responses/Inconnu' }
        '409':
          description: La version est en quarantaine ou antérieure à la version active.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Erreur' }
  /exceptions-faux-positif:
    get:
      operationId: consulterLesExceptions
      summary: Les exceptions actives et échues — chacune bornée à une version de liste.
      security: [ { authentification: [conformite:parametrage] } ]
      responses:
        '200':
          description: Les exceptions, avec version de liste et échéance de réexamen.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Exceptions' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
    post:
      operationId: creerUneException
      summary: Écarter durablement un faux positif — borné, justifié, réexaminable.
      description: >-
        Une nouvelle version de liste n'hérite d'aucune exception. Geste d'armement — candidat à
        la seconde validation (202).
      security: [ { authentification: [conformite:parametrage] } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NouvelleException' }
      responses:
        '201':
          description: L'exception est créée.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Exception' }
        '202':
          description: Suspendue à une seconde validation.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Exception' }
        '400': { $ref: '#/components/responses/Irrecevable' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
  /jalons:
    get:
      operationId: consulterLesJalons
      summary: Les jalons d'évaluation déclarés, par domaine appelant.
      security: [ { authentification: [conformite:parametrage] } ]
      responses:
        '200':
          description: Les jalons déclarés — sans jalon déclaré, pas de contrôle.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Jalons' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
    post:
      operationId: declarerUnJalon
      summary: Déclarer un jalon au nom d'un domaine appelant.
      description: >-
        C'est le canal de déclaration que le contrat de l'évaluation suppose : le code
        déclaré ici devient citable dans une demande d'évaluation. Ajouter un jalon est
        un paramétrage, pas une évolution de contrat. Idempotent par demande_id.
      security: [ { authentification: [conformite:parametrage] } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NouveauJalon' }
      responses:
        '201':
          description: Le jalon est déclaré, daté.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Jalon' }
        '400': { $ref: '#/components/responses/Irrecevable' }
        '401': { $ref: '#/components/responses/NonAuthentifie' }
        '403': { $ref: '#/components/responses/NonAutorise' }
components:
  parameters:
    scenario:
      name: scenario
      in: path
      required: true
      schema: { type: string }
  responses:
    NonAuthentifie:
      description: L'appelant n'est pas authentifié.
      content: { application/json: { schema: { $ref: '#/components/schemas/Erreur' } } }
    NonAutorise:
      description: Le point d'application de la politique refuse cette action sur ce périmètre.
      content: { application/json: { schema: { $ref: '#/components/schemas/Erreur' } } }
    Irrecevable:
      description: La demande est irrecevable — le motif nomme le champ.
      content: { application/json: { schema: { $ref: '#/components/schemas/Erreur' } } }
    Inconnu:
      description: L'objet est inconnu — ou hors du périmètre de l'appelant, sans distinction.
      content: { application/json: { schema: { $ref: '#/components/schemas/Erreur' } } }
  securitySchemes:
    authentification:
      type: openIdConnect
      openIdConnectUrl: https://exemple.invalid/.well-known/openid-configuration
      description: Exigence déclarée ici ; mécanisme décliné à l'assemblage.
  schemas:
    Scenarios:
      type: object
      required: [scenarios, servi_le]
      properties:
        scenarios:
          type: array
          items:
            type: object
            required: [scenario, famille, finalite, versions]
            properties:
              scenario: { type: string }
              famille: { type: string }
              finalite: { type: string }
              versions:
                type: array
                items: { $ref: '#/components/schemas/VersionDeScenario' }
        servi_le: { type: string, format: date-time }
    NouvelleVersionDeScenario:
      type: object
      required: [demande_id, parametres, motif]
      properties:
        demande_id: { type: string }
        parametres:
          type: object
          additionalProperties: true
          description: Les paramètres datés (seuils, fenêtres, poids, activation) — jamais de logique.
        motif: { type: string }
    VersionDeScenario:
      type: object
      required: [scenario, version, etat, parametres]
      properties:
        scenario: { type: string }
        version: { type: string }
        etat:
          type: string
          enum: [PROPOSEE, EN_REVUE, HOMOLOGUEE, PLANIFIEE, ACTIVE, SUSPENDUE_A_VALIDATION, REMPLACEE, ARCHIVEE]
        parametres:
          type: object
          additionalProperties: true
        homologation:
          type: object
          properties:
            jeu_epreuve: { type: string, description: Référence du jeu d'épreuve exécuté vert. }
            analyse_impact: { type: string }
            proprietaire: { type: string }
        date_effet: { type: string, format: date }
    Activation:
      type: object
      required: [demande_id, date_effet, homologation]
      properties:
        demande_id: { type: string }
        date_effet: { type: string, format: date }
        homologation:
          type: object
          required: [jeu_epreuve, analyse_impact, proprietaire]
          properties:
            jeu_epreuve: { type: string }
            analyse_impact: { type: string }
            proprietaire: { type: string }
    PolitiquesDeVigilance:
      type: object
      required: [lignes, servi_le]
      properties:
        lignes:
          type: array
          items: { $ref: '#/components/schemas/LigneDePolitique' }
        servi_le: { type: string, format: date-time }
    NouvelleLigneDePolitique:
      type: object
      required: [demande_id, politique, cle, valeur, date_effet, motif]
      properties:
        demande_id: { type: string }
        politique: { type: string, description: "La politique concernée (ex. vigilance_simplifiee, fraude_paiement)." }
        cle: { type: string, description: "Le paramètre (ex. seuil_versement_volontaire)." }
        valeur: { type: string, description: Valeur en chaîne — aucune conversion silencieuse. }
        date_effet: { type: string, format: date }
        motif: { type: string }
    LigneDePolitique:
      allOf:
        - $ref: '#/components/schemas/NouvelleLigneDePolitique'
        - type: object
          required: [posee_le, par]
          properties:
            posee_le: { type: string, format: date-time }
            par: { type: string }
            date_fin: { type: string, format: date, description: Posée par une ligne ultérieure — jamais par modification. }
    Listes:
      type: object
      required: [sources, servi_le]
      properties:
        sources:
          type: array
          items:
            type: object
            required: [source, autorite, versions]
            properties:
              source: { type: string }
              autorite: { type: string }
              fraicheur_attendue: { type: string }
              versions:
                type: array
                items:
                  type: object
                  required: [version, etat, recue_le]
                  properties:
                    version: { type: string }
                    etat:
                      type: string
                      enum: [CONTROLEE, INGEREE, ACTIVE, EN_QUARANTAINE, REMPLACEE]
                    recue_le: { type: string, format: date-time }
                    date_effet: { type: string, format: date }
                    motif_quarantaine: { type: string }
        servi_le: { type: string, format: date-time }
    ActivationDeListe:
      type: object
      required: [demande_id, procedure]
      properties:
        demande_id: { type: string }
        procedure:
          type: string
          enum: [ORDINAIRE, URGENTE]
          description: URGENTE enregistre la revue a posteriori comme due — jamais supprimée.
        motif: { type: string }
    VersionDeListeActivee:
      type: object
      required: [source, version, etat]
      properties:
        source: { type: string }
        version: { type: string }
        etat: { type: string }
        revue_a_posteriori_due: { type: boolean }
        campagne:
          type: string
          description: La campagne de re-criblage du stock déclenchée, le cas échéant.
    Exceptions:
      type: object
      required: [exceptions, servi_le]
      properties:
        exceptions:
          type: array
          items: { $ref: '#/components/schemas/Exception' }
        servi_le: { type: string, format: date-time }
    NouvelleException:
      type: object
      required: [demande_id, sujet, entree, source, version_liste, echeance_reexamen, justification]
      properties:
        demande_id: { type: string }
        sujet: { type: string, description: Référence publiée du sujet écarté. }
        entree: { type: string, description: L'entrée de liste concernée. }
        source: { type: string }
        version_liste:
          type: string
          description: La version à laquelle l'exception est BORNÉE — une nouvelle version n'en hérite pas.
        echeance_reexamen: { type: string, format: date }
        justification: { type: string }
    Exception:
      allOf:
        - $ref: '#/components/schemas/NouvelleException'
        - type: object
          required: [exception, creee_le, par, etat]
          properties:
            exception: { type: string }
            creee_le: { type: string, format: date-time }
            par: { type: string }
            etat: { type: string, enum: [ACTIVE, ECHUE, SUSPENDUE_A_VALIDATION] }
    Jalons:
      type: object
      required: [jalons, servi_le]
      properties:
        jalons:
          type: array
          items: { $ref: '#/components/schemas/Jalon' }
        servi_le: { type: string, format: date-time }
    NouveauJalon:
      type: object
      required: [demande_id, code, domaine_appelant, finalite, motif]
      properties:
        demande_id: { type: string }
        code:
          type: string
          description: "Le code citable dans une demande d'évaluation (ex. OPERATIONS_PAIEMENT_SORTANT)."
        domaine_appelant: { type: string }
        finalite: { type: string }
        budget_latence_ms:
          type: integer
          description: Le budget de latence attendu au jalon.
        motif: { type: string }
    Jalon:
      allOf:
        - $ref: '#/components/schemas/NouveauJalon'
        - type: object
          required: [declare_le, par, etat]
          properties:
            declare_le: { type: string, format: date-time }
            par: { type: string }
            etat: { type: string, enum: [DECLARE, FERME] }
            date_fermeture: { type: string, format: date }
    Erreur:
      type: object
      required: [code, message]
      properties:
        code: { type: string }
        message:
          type: string
          description: >-
            Nomme le champ ou la condition en cause. Ne révèle ni un critère de
            détection au-delà du périmètre de l'appelant, ni l'existence d'un objet
            hors de ce périmètre.