openapi-spec.yaml

openapi: 3.0.3
info:
  title: SECPSC-PSI API
  description: |
    SECPSC : API PSI (ProSanté Connect - Plateforme de Services d'Identité) pour la gestion des utilisateurs
    Cette API permet de rechercher, créer et mettre à jour les utilisateurs dans le système PSC PSI.
    - Mise à jour du 17/03/2026 : Ajout d'un endpoint de recherche de professionnels de santé par nom et/ou prénom, qui retourne leurs identifiants nationaux et raisons sociales.
  version: 1.1.0
  contact:
    name: ANS - Agence du Numérique en Santé
    url: https://esante.gouv.fr
  license:
    name: Propriétaire ANS
servers:
  - url: http://localhost:8085/psc-psi-api/api
    description: Serveur de développement local
  - url: https://psc-secpsc-api.esante.gouv.fr/api
    description: Serveur de production
paths:
  /user:
    get:
      operationId: rechercherParIdNational
      summary: Rechercher un utilisateur par ID national
      description: Retourne la personne (si trouvée) au SEC PSC sur la base de son identifiant national
      tags:
        - rechercher-user-controller
      parameters:
        - name: nationalId
          in: query
          required: true
          description: L'identifiant national de l'utilisateur à rechercher
          schema:
            type: string
            example: "12345678901"
        - name: includeDeactivated
          in: query
          required: false
          description: Si true, retourne le compte même s'il est désactivé
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Personne trouvée
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Données invalides ou absentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Utilisateur non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '404':
          description: Utilisateur non trouvé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: L'utilisateur avec cet identifiant national existe déjà
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Erreur interne serveur
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericInternalServerErrorDto'

    post:
      operationId: creerUser
      summary: Créer un nouvel utilisateur
      description: Crée l'utilisateur au SEC PSC à partir de ses traits d'identité
      tags:
        - rechercher-user-controller
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Utilisateur créé
        '400':
          description: Données invalides ou absentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Utilisateur non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '404':
          description: Utilisateur non trouvé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Erreur interne serveur
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericInternalServerErrorDto'

    put:
      operationId: updateUser
      summary: Mettre à jour un utilisateur
      description: |
        Met à jour les données de l'utilisateur comme son mail, son téléphone (tous 2 vérifiés), 
        ses traits d'identité, l'id PSI (qui, coté SEC PSC, ajoutera l'id à la liste des identifiants de l'utilisateur).
        Si le compte est désactivé, il est automatiquement réactivé avant d'appliquer la mise à jour.
      tags:
        - rechercher-user-controller
      parameters:
        - name: nationalId
          in: query
          required: true
          description: Identifiant national de l'utilisateur
          schema:
            type: string
            example: "12345678901"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Utilisateur mis à jour
        '400':
          description: Données invalides ou absentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Utilisateur non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '404':
          description: Utilisateur non trouvé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: L'utilisateur avec cet identifiant national existe déjà
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Erreur interne serveur
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericInternalServerErrorDto'

    delete:
      operationId: deleteUser
      summary: Supprimer un utilisateur
      description: |
        Désactive l'utilisateur dans le système (soft delete). 
        L'utilisateur n'est pas physiquement supprimé mais marqué comme désactivé.
      tags:
        - rechercher-user-controller
      parameters:
        - name: nationalId
          in: query
          required: true
          description: Identifiant national de l'utilisateur à supprimer
          schema:
            type: string
            example: "12345678901"
      responses:
        '204':
          description: Utilisateur supprimé avec succès
        '400':
          description: Données invalides ou absentes
        '401':
          description: Utilisateur non autorisé
        '410':
          description: Utilisateur non trouvé ou déjà supprimé
        '500':
          description: Erreur interne serveur

  /user/force:
    delete:
      operationId: forceDeleteUser
      summary: Supprimer définitivement un utilisateur (PREPROD UNIQUEMENT)
      description: |
        Supprime physiquement l'utilisateur de la base de données (hard delete).
        Cette opération est irréversible. L'utilisateur et toutes ses données seront définitivement effacés.
        
        Cet endpoint est activé ou désactivé via la configuration `force.delete.enabled`.
      tags:
        - rechercher-user-controller
      parameters:
        - name: nationalId
          in: query
          required: true
          description: Identifiant national de l'utilisateur à supprimer définitivement
          schema:
            type: string
            example: "12345678901"
      responses:
        '204':
          description: Utilisateur supprimé définitivement avec succès
        '400':
          description: Données invalides ou absentes
        '401':
          description: Utilisateur non autorisé
        '403':
          description: Endpoint non disponible dans cet environnement (production)
        '410':
          description: Utilisateur non trouvé
        '500':
          description: Erreur interne serveur

  /user/identitytraits:
    get:
      operationId: rechercherNationalIdParTraitsIdentite
      summary: Rechercher par traits d'identité
      description: Retourne l'id national de chaque personne trouvée sur la base des traits d'identité
      tags:
        - rechercher-user-controller
      parameters:
        - name: lastName
          in: query
          required: true
          description: Nom de famille
          schema:
            type: string
            example: "Dupont"
        - name: firstNames
          in: query
          required: true
          description: Prénoms
          schema:
            type: string
            example: "Jean Pierre"
        - name: genderCode
          in: query
          required: true
          description: Code du genre (M/F/I)
          schema:
            type: string
            enum: [M, F, I]
            example: "M"
        - name: birthdate
          in: query
          required: true
          description: Date de naissance
          schema:
            type: string
            format: date
            example: "1980-01-01"
        - name: birthTownCode
          in: query
          required: false
          description: Code de la ville de naissance
          schema:
            type: string
            example: "75001"
        - name: birthCountryCode
          in: query
          required: false
          description: Code du pays de naissance
          schema:
            type: string
            example: "FR"
        - name: birthplace
          in: query
          required: false
          description: Lieu de naissance
          schema:
            type: string
            example: "Paris"
      responses:
        '200':
          description: Au moins une personne a été trouvée, retourne donc un tableau d'id
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: ["12345678901", "12345678902"]
        '400':
          description: Données invalides ou absentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Utilisateur non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        '404':
          description: Utilisateur non trouvé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Erreur interne serveur
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericInternalServerErrorDto'

  /user/search:
    get:
      operationId: rechercherParNomPrenom
      summary: Rechercher des PS par nom et/ou prénom
      description: Retourne la liste des professionnels de santé correspondant au nom et/ou prénom, avec leurs identifiants nationaux et raisons sociales.
      tags:
        - rechercher-user-controller
      parameters:
        - name: lastName
          in: query
          required: false
          description: Nom de famille
          schema:
            type: string
            example: "DUPONT"
        - name: firstNames
          in: query
          required: false
          description: Prénom(s) séparés par des espaces
          schema:
            type: string
            example: "JEAN PIERRE"
      responses:
        '200':
          description: Liste de PS avec leurs identifiants nationaux et raisons sociales
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PsNameSearchResultDto'
        '400':
          description: Données invalides ou absentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Erreur interne serveur
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericInternalServerErrorDto'

components:
  schemas:
    User:
      type: object
      required:
        - nationalId
      properties:
        nationalId:
          type: string
          description: Identifiant national unique de l'utilisateur
          example: "12345678901"
        contactInfo:
          $ref: '#/components/schemas/ContactInfo'
        practices:
          type: array
          description: Liste des pratiques professionnelles
          items:
            $ref: '#/components/schemas/Practice'
        civilStatus:
          $ref: '#/components/schemas/CivilStatus'
        alternativeIdentifiers:
          type: array
          description: Identifiants alternatifs
          items:
            $ref: '#/components/schemas/AlternativeIdentifier'
        eims:
          type: array
          description: Liste des EIMs (Electronic Identity Management) associés à l'utilisateur
          items:
            $ref: '#/components/schemas/Eim'

    ContactInfo:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Adresse email vérifiée
          example: "jean.dupont@example.com"
        phone:
          type: string
          description: Numéro de téléphone vérifié
          example: "+33123456789"

    Practice:
      type: object
      properties:
        professionCode:
          type: string
        professionalCategoryCode:
          type: string
        expertiseTypeCode:
          type: string
        expertiseCode:
          type: string
        professionalCivilityTitle:
          type: string
        professionalLastName:
          type: string
        professionalFirstName:
          type: string
        activities:
          type: array
          items:
            $ref: '#/components/schemas/Activity'
    CivilStatus:
      type: object
      properties:
        lastName:
          type: string
          minLength: 1
        firstNames:
          type: string
          description: Prénoms séparés par des espaces
          example: "Jean Pierre"
        birthdate:
          type: string
          example: "1980-10-01"
        birthTownCode:
          type: string
        birthCountryCode:
          type: string
        birthplace:
          type: string
        genderCode:
          type: string
        personalCivilityTitle:
          type: string
      required:
        - lastName

    AlternativeIdentifier:
      type: object
      properties:
        identifier:
          type: string
          description: Valeur de l'identifiant
          example: "PSI123456"
        origine:
          type: string
          description: Origine de l'identifiant alternatif
          example: "PSI"
        quality:
          type: integer
          description: Qualité de l'identifiant
          example: 1

    Eim:
      type: object
      properties:
        nationalId:
          type: string
          description: Identifiant national
          example: "12345678901"
        type:
          type: string
          description: Type d'EIM
          example: "RPPS"
        creationDate:
          type: string
          format: date-time
          description: Date de création
          example: "2025-09-05T15:40:38.688Z"
        endOfValidityDate:
          type: string
          format: date-time
          description: Date de fin de validité
          example: "2025-09-05T15:40:38.688Z"
        eidasLevel:
          type: integer
          description: Niveau eIDAS
          example: 1
        lastUsageDate:
          type: string
          format: date-time
          description: Date de dernière utilisation
          example: "2025-09-05T15:40:38.688Z"
        attributes:
           type: object
           description: Attributs supplémentaires
           properties:
             deviceName:
               type: string
               example: "iPhone 14"
             operatingSystem:
                type: string
                example: "iOS 18.5"
             appVersion:
                type: string
                example: "3.12.7"
             activationMode:
                type: string
                example: "CARD"

    ApiError:
      type: object
      properties:
        code:
          type: string
          description: Code d'erreur
          example: "USER_NOT_FOUND"
        message:
          type: string
          description: Message d'erreur
          example: "Utilisateur non trouvé"
        timestamp:
          type: string
          format: date-time
          description: Horodatage de l'erreur
          example: "2024-01-15T10:30:00Z"

    ErrorDto:
      type: object
      properties:
        error:
          type: string
          description: Type d'erreur
          example: "Unauthorized"
        message:
          type: string
          description: Message d'erreur détaillé
          example: "Token d'authentification invalide"
          
    Activity:
      type: object
      properties:
        professionalModeCode:
          type: string
        activitySectorCode:
          type: string
        pharmacistTableSectionCode:
          type: string
        roleCode:
          type: string
        activityTypeCode:
          type: string
        siretSiteNumber:
          type: string
        sirenSiteNumber:
          type: string
        finessSiteNumber:
          type: string
        finessLegalCompanyNumber:
          type: string
        companyTechnicalIdentifier:
          type: string
        companyName:
          type: string
        companyCommercialSign:
          type: string
        companyAdditionalAddress:
          type: string
        companyGeographicalPointComplement:
          type: string
        companyWayNumber:
          type: string
        companyRepeatIndex:
          type: string
        companyWayType:
          type: string
        companyWayLabel:
          type: string
        companyDistributionMention:
          type: string
        companyCedexOffice:
          type: string
        companyPostalCode:
          type: string
        companyTownCode:
          type: string
        companyCountryCode:
          type: string
        companyPhone1:
          type: string
        companyPhone2:
          type: string
        companyFax:
          type: string
        companyEmail:
          type: string
        companyCountyCode:
          type: string
        companyOldIdentifier:
          type: string
        companyRegistrationAuthority:
          type: string

    GenericInternalServerErrorDto:
      type: object
      properties:
        error:
          type: string
          description: Erreur interne du serveur
          example: "Internal Server Error"
        message:
          type: string
          description: Message d'erreur technique
          example: "Une erreur interne s'est produite"
        trace:
          type: string
          description: Trace technique de l'erreur
          example: "java.lang.Exception: Database connection failed"

    PsNameSearchResultDto:
      type: object
      properties:
        nationalId:
          type: string
          description: Identifiant national du professionnel de santé
          example: "12345678901"
        companyNames:
          type: array
          description: Liste des lieux d'exercice avec code profession et raison sociale
          items:
            $ref: '#/components/schemas/WorkLocationDto'
    WorkLocationDto:
      type: object
      properties:
        professionCode:
          type: string
          description: Code de la profession
        companyName:
          type: string
          description: Raison sociale de la structure
        companyCedexOffice:
          type: string
          description: Code cedex de la structure

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

tags:
  - name: rechercher-user-controller
    description: Contrôleur pour la recherche et gestion des utilisateurs PSI