braver-frontend.yml

openapi: 3.1.0
info:
  title: Braver API (Ofys Integration)
  version: 0.2.2
  description: >-
    API exposée par Braver et consommée par Ofys pour la consultation, la
    création et la gestion des fils de discussion,

    la consultation des statistiques sur les fils actifs, la recherche de
    professionnels et de cliniques,

    ainsi qu'un canal WebSocket pour les activités en temps réel liées aux fils.


    ## État d'avancement


    - /fils/activites: Le websocket n'est pas fonctionnel

    - Les clés d'idempotence ne sont pas fonctionnels

    - Le modèle JSON pour les erreurs n'est pas complété


    ## Modèle de Sécurité


    L'API utilise deux schémas d'authentification JWT:


    1. **ofysJwt** (Authentification Ofys):
       - Utilisé UNIQUEMENT pour l'endpoint POST /auth/token
       - JWT signé par Ofys
       - Permet d'obtenir un braverJwt

    2. **braverJwt** (Authentification Braver):
       - Utilisé pour TOUS les autres endpoints (sauf /professions et /typesLieux)
       - JWT émis par Braver après échange via POST /auth/token
       - Inclus dans l'en-tête Authorization: Bearer <token>

    3. **Endpoints Publics** (pas d'authentification requise):
       - GET /professions
       - GET /typesLieux
       - Ces endpoints retournent des données de référence statiques

    Voir chaque endpoint pour son modèle de sécurité spécifique.


    ## Limites et Pagination


    ### Fils de Discussion


    - **Limite max par requête**: 50 fils

    - **Limite par défaut**: 20 fils

    - **Pagination**: Basée sur l'ID du dernier fil connu (cursor-based)

    - **Ordre**: Du plus récent au plus ancien (par date de création)

    - **Utilisation**:
      - Première requête: Pas de paramètre → retourne les 20 fils les plus récents
      - Requête suivante: Passer l'ID du dernier fil reçu → retourne les 20 fils suivants

    ### Messages


    - **Limite max par requête**: 100 messages

    - **Limite par défaut**: 50 messages

    - **Pagination**: Basée sur `sequenceId` avec `offset` et `limit` (voir GET
    /fils/{ofysOrBraverId})

    - **Ordre**: Du plus récent au moins récent


    ### Pièces Jointes


    - **Taille max totale par message**: 2 GB

    - **Nombre max de fichiers par message**: 10

    - **Types MIME autorisés**: Tous sauf les types à risque (.exe, .bat, .com,
    .cmd, .scr, .vbs, .js, .jar, etc.)


    ### Recherche


    - **Limite max de résultats**: 100 résultats

    - **Pagination**: Basée sur `limit` et `offset`


    ### Rate Limiting


    - À déterminer (voir documentation de déploiement)


    ## Authentification et Tokens


    ### Obtention du Token


    - **Endpoint**: POST /auth/token

    - **Authentification requise**: ofysJwt (JWT signé par Ofys)

    - **Réponse**: braverJwt avec `expires_in` en secondes


    ### Durée d'Expiration


    - **Token Braver (braverJwt)**: 24 heures (86400 secondes)

    - **Refresh**: Un nouveau token peut être obtenu en utilisant le token Ofys
    que contrôle Ofys

    - **Méthode**: Appeler à nouveau POST /auth/token avec un nouveau ofysJwt


    ### WebSocket


    - **Token requis**: braverJwt passé en query parameter lors de la connexion
    initiale

    - **Expiration**: Le token n'expire PAS tant que la connexion WebSocket
    reste ouverte

    - **Reconnexion**: Si la connexion est fermée, un nouveau token doit être
    obtenu pour se reconnecter


    ## Idempotence


    ### Support de l'Idempotency-Key


    Tous les endpoints POST et PUT supportent le header standard
    `Idempotency-Key` pour garantir l'idempotence.


    **Format**: UUID v4 (ex: `550e8400-e29b-41d4-a716-446655440000`)


    **Durée de garantie**: 1 heure


    **Utilisation**: Inclure le header `Idempotency-Key` dans la requête:


    ```

    POST /fils

    Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

    ```


    **Comportement**:


    - Si la même requête est envoyée avec la même `Idempotency-Key` dans
    l'heure, la réponse en cache est retournée

    - Évite les doublons en cas de retry réseau ou de clics multiples

    - Applicable à: POST /fils, POST /fils/{ofysOrBraverId}/messages, POST
    /utilisateurs, POST /patients, etc.


    ## Statuts et Permissions des Participants


    ### Statuts des Participants


    Chaque participant dans une discussion a un statut qui détermine son accès:


    - **pending**: En attente d'activation (invitation envoyée, pas encore
    acceptée)

    - **active**: Participant actif dans la discussion

    - **left**: Participant qui a quitté la discussion (perd accès aux messages)


    **Comportement lors du départ**:


    - Quand un professionnel quitte une clinique, il perd ses accès aux
    discussions liées au client Ofys

    - Ces discussions peuvent être récupérées par la clinique

    - Les discussions peuvent être transférées à un autre médecin au besoin


    ### Permissions des Participants


    Chaque participant peut avoir des contraintes qui restreignent ce qu'il peut
    contribuer:


    - **read_only**: Peut lire les messages mais ne peut pas contribuer

    - **reactions_only**: Peut ajouter des réactions aux messages uniquement

    - **messages_only**: Peut poster des messages mais pas de réactions

    - **full**: Accès complet (messages et réactions)


    **Exemple**: Un participant peut être en statut "active" avec permission
    "read_only" pour une discussion spécifique.


    ## Pièces Jointes


    ### Limites des Pièces Jointes


    - **Taille par fichier en base64**: 50 MB maximum (≈ 37.5 MB de données
    réelles)

    - **Taille totale par message**: 2 GB maximum

    - **Nombre de fichiers par message**: 10 fichiers maximum

    - **Types MIME autorisés**: Tous les types sauf les types à risque


    ### Types MIME Interdits


    Les types MIME suivants sont interdits pour des raisons de sécurité:

    - Exécutables: `.exe`, `.bat`, `.com`, `.cmd`, `.scr`, `.vbs`, `.js`,
    `.jar`, `.msi`, `.dll`, `.sys`

    - Scripts: `.ps1`, `.sh`, `.bash`, `.zsh`, `.fish`

    - Archives exécutables: `.zip` contenant des exécutables, `.rar`, `.7z`
    contenant des exécutables

    - Autres: `.app`, `.dmg`, `.pkg`, `.deb`, `.rpm`


    ### Formats de Transmission


    Les pièces jointes peuvent être transmises de deux façons:

    1. **Base64**: Contenu encodé en base64 dans le champ `contenuBase64`

    2. **URL**: Lien de téléchargement dans le champ `urlTelechargement`


    ### Exemple de Requête


    ```json

    POST /fils/{ofysOrBraverId}/messages

    {
      "contenu": "Voici le document",
      "format": "texte",
      "attachments": [
        {
          "nomFichier": "rapport.pdf",
          "typeMime": "application/pdf",
          "description": "Rapport médical",
          "contenuBase64": "JVBERi0xLjQKJeLj..."
        }
      ]
    }

    ```
  contact:
    name: Braver API Team
    url: https://www.braver.net
    email: developers@braver.net
servers:
  - url: <À préciser prochainement>
    description: Production
  - url: <À préciser prochainement>
    description: Sandbox
tags:
  - name: Authentification
  - name: Fils
  - name: Recherche
  - name: Temps Réel
security:
  - braverJwt: []
paths:
  /auth/token:
    post:
      tags:
        - Authentification
      summary: Obtenir un jeton Braver à partir d'un JWT Ofys
      description: >-
        Ofys appelle cet endpoint en présentant un JWT signé dans Authorization:
        Bearer <token>.

        L'API valide ce jeton et retourne un JWT émis par Braver qui pourra être
        utilisé pour tous les autres appels de cette API.


        **Durée d'expiration**: 24 heures (86400 secondes)


        **Refresh**: Pour obtenir un nouveau token après expiration, appeler à
        nouveau cet endpoint avec un nouveau ofysJwt.


        **Sécurité**: Authentification requise (ofysJwt)
      operationId: exchangeOfysJwtForBraverJwt
      security:
        - ofysJwt: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBraverToken'
      responses:
        '200':
          description: Jeton Braver émis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BraverToken'
        '401':
          description: JWT Ofys invalide ou expiré
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                tokenExpired:
                  value:
                    error:
                      code: AUTH_TOKEN_EXPIRED
                      message: Le token Ofys a expiré
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
                tokenInvalid:
                  value:
                    error:
                      code: AUTH_TOKEN_INVALID
                      message: Signature du token invalide
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
                clinicUnknown:
                  value:
                    error:
                      code: AUTH_CLINIC_UNKNOWN
                      message: Clinic ID non reconnu
                      details:
                        clinicId: clinic-999
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
                userNotProvisioned:
                  value:
                    error:
                      code: AUTH_USER_NOT_PROVISIONED
                      message: Utilisateur non créé dans Braver
                      details:
                        userId: user-123
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
  /fils-actifs/stats:
    get:
      tags:
        - Fils
      summary: Statistiques des fils actifs
      description: >-
        Retourne des compteurs à afficher dans Ofys.

        Inclut le nombre de fils actifs (ouverts) et le nombre total de messages
        non lus.


        **Sécurité**: Authentification requise (braverJwt)
      operationId: getActiveThreadStats
      responses:
        '200':
          description: Statistiques
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveThreadStats'
  /fils-actifs:
    get:
      tags:
        - Fils
      summary: Lister les fils actifs
      description: >-
        Retourne les fils actifs (non fermés) avec métadonnées résumées,
        participants, lieux et infos patient minimales.

        Le contenu détaillé (messages) se trouve via GET /fils/{ofysOrBraverId}.


        **Pagination**: Basée sur le curseur (ID du dernier fil connu)

        - Première requête: Pas de paramètre `afterThreadId` → retourne les N
        fils les plus récents

        - Requête suivante: Passer l'ID du dernier fil reçu → retourne les N
        fils suivants

        - **Ordre**: Du plus récent au plus ancien (par date de création)


        **Sécurité**: Authentification requise (braverJwt)
      operationId: listActiveThreads
      parameters:
        - in: query
          name: afterThreadId
          schema:
            type: string
          description: >-
            Optionnel—ID du dernier fil connu. Si fourni, retourne les fils
            créés avant celui-ci. Omettez ce paramètre pour obtenir les fils les
            plus récents.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          description: Nombre de fils à retourner (max 50, défaut 20)
      responses:
        '200':
          description: Liste paginée des fils actifs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadListResponse'
  /fils/{ofysOrBraverId}:
    get:
      tags:
        - Fils
      summary: Détails complets d'un fil (messages et métadonnées)
      description: '**Sécurité**: Authentification requise (braverJwt)'
      operationId: getThread
      parameters:
        - $ref: '#/components/parameters/PathId'
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: Nombre max de messages à retourner (max 100, défaut 50)
        - in: query
          name: sinceSequenceId
          schema:
            type: integer
            minimum: 0
          required: false
          description: >-
            Optionnel—récupérer les messages depuis un sequenceId (du plus
            récent au moins récent)
      responses:
        '200':
          description: Fil
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thread'
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Fil non trouvé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: THREAD_NOT_FOUND
                  message: Le fil avec l'ID 'thread-123' n'existe pas
                  details:
                    threadId: thread-123
                  timestamp: '2025-11-18T14:32:00Z'
                  traceId: abc-123-def
    put:
      tags:
        - Fils
      summary: Mettre à jour l'état du fil
      description: >-
        Permet de marquer comme lu jusqu'à un sequenceId, marquer globalement
        comme non lu,

        mettre en sourdine pour une durée, associer un patient Ofys, fermer ou
        quitter le fil.


        **Association d'un patient Ofys**:

        Lorsque `associerPatient` est fourni, la requête doit inclure les
        détails complets du patient

        (id, prenom, nom, sexeNaissance, dateNaissance, nam) comme lors d'une
        création de patient backend.

        C'est souvent à ce moment que Braver prend connaissance du patient pour
        la première fois.


        **Sécurité**: Authentification requise (braverJwt)
      operationId: updateThread
      parameters:
        - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThreadUpdate'
      responses:
        '200':
          description: Fil mis à jour
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thread'
        '400':
          description: Requête invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                threadClosed:
                  value:
                    error:
                      code: VALIDATION_THREAD_CLOSED
                      message: Tentative de modifier un fil fermé
                      details:
                        threadId: thread-123
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Fil non trouvé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /fils/{ofysOrBraverId}/messages:
    post:
      tags:
        - Fils
      summary: Poster un message dans un fil
      description: >-
        Ajoute un nouveau message au fil avec contenu textuel (texte brut ou
        markdown)

        et zéro ou plusieurs pièces jointes (fichiers en base64 ou URLs).


        **Sécurité**: Authentification requise (braverJwt)
      operationId: postMessage
      parameters:
        - $ref: '#/components/parameters/PathId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreate'
      responses:
        '201':
          description: Message créé
          headers:
            Location:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '400':
          description: Requête invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                attachmentTooLarge:
                  value:
                    error:
                      code: VALIDATION_ATTACHMENT_TOO_LARGE
                      message: Taille totale des pièces jointes dépasse 2GB
                      details:
                        maxSize: 2147483648
                        currentSize: 2500000000
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
                tooManyAttachments:
                  value:
                    error:
                      code: VALIDATION_ATTACHMENT_COUNT_EXCEEDED
                      message: Maximum 10 pièces jointes par message
                      details:
                        maxCount: 10
                        currentCount: 15
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
                invalidMimeType:
                  value:
                    error:
                      code: VALIDATION_ATTACHMENT_INVALID_TYPE
                      message: Type de fichier non supporté
                      details:
                        mimeType: application/x-msdownload
                        allowedTypes:
                          - image/*
                          - application/pdf
                          - application/msword
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Fil non trouvé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /professions:
    get:
      tags:
        - Recherche
      summary: Lister les professions disponibles
      description: >-
        Retourne la liste de toutes les professions connues par Braver, chacune
        avec un UUID unique,

        des libellés localisés et genrés, ainsi que le type de profession
        (clinique sans licence, clinique licencié, non-clinique).

        Ces IDs sont utilisés dans la recherche de professionnels et
        l'identification des participants dans les discussions.


        **Sécurité**: AUCUNE authentification requise (endpoint public)
      operationId: listProfessions
      security: []
      responses:
        '200':
          description: Liste des professions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfessionListResponse'
  /typesLieux:
    get:
      tags:
        - Recherche
      summary: Lister les types de lieux disponibles
      description: >-
        Retourne la liste de tous les types de lieux connus par Braver
        (cliniques, pharmacies, services hospitaliers, etc.),

        chacun avec un UUID unique et des libellés localisés.

        Ces IDs sont utilisés dans la recherche de cliniques et l'identification
        des lieux dans les discussions.


        **Sécurité**: AUCUNE authentification requise (endpoint public)
      operationId: listLocationTypes
      security: []
      responses:
        '200':
          description: Liste des types de lieux
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationTypeListResponse'
  /rechercheDeProfessionnels:
    get:
      tags:
        - Recherche
      summary: Rechercher des professionnels
      description: '**Sécurité**: Authentification requise (braverJwt)'
      operationId: searchProfessionals
      parameters:
        - in: query
          name: termes
          required: true
          schema:
            type: string
          description: Termes séparés par virgules
        - in: query
          name: profession
          schema:
            type: string
            description: UUID de profession (voir GET /professions)
        - in: query
          name: longitude
          schema:
            type: number
            format: double
        - in: query
          name: latitude
          schema:
            type: number
            format: double
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Nombre max de résultats (max 100, défaut 20)
        - in: query
          name: pageToken
          schema:
            type: string
          description: Token de la derniere page (rien pour la première page)
      responses:
        '200':
          description: Résultats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfessionalSearchResponse'
  /rechercheDeLieux:
    get:
      tags:
        - Recherche
      summary: Rechercher des lieux de pratique
      description: '**Sécurité**: Authentification requise (braverJwt)'
      operationId: searchClinics
      parameters:
        - in: query
          name: termes
          required: true
          schema:
            type: string
        - in: query
          name: typeLieu
          schema:
            type: string
            format: uuid
            description: UUID du type de lieu (voir GET /typesLieux)
        - in: query
          name: longitude
          schema:
            type: number
            format: double
        - in: query
          name: latitude
          schema:
            type: number
            format: double
      responses:
        '200':
          description: Résultats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkplaceSearchResponse'
  /fils:
    post:
      tags:
        - Fils
      summary: Créer un nouveau fil
      description: >-
        Crée un fil avec participants (professionnels et/ou cliniques), contenu
        initial et association patient.


        **Association d'un patient Ofys**:

        Lorsque `patient` est fourni, la requête doit inclure les détails
        complets du patient

        (id, prenom, nom, sexeNaissance, dateNaissance, nam) comme lors d'une
        création de patient backend.

        C'est souvent à ce moment que Braver prend connaissance du patient pour
        la première fois.


        **Sécurité**: Authentification requise (braverJwt)
      operationId: createThread
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThreadCreate'
      responses:
        '201':
          description: Fil créé
          headers:
            Location:
              description: URL de la ressource nouvellement créée
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thread'
        '400':
          description: Données invalides
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                missingTitle:
                  value:
                    error:
                      code: VALIDATION_REQUIRED_FIELD
                      message: Le champ 'titre' est obligatoire
                      details:
                        field: titre
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
                invalidParticipant:
                  value:
                    error:
                      code: VALIDATION_PARTICIPANT_NOT_FOUND
                      message: Le participant avec l'ID 'prof-123' n'existe pas
                      details:
                        participantId: prof-123
                        field: participants[0].id
                      timestamp: '2025-11-18T14:32:00Z'
                      traceId: abc-123-def
        '401':
          description: Non autorisé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /fils/activites:
    get:
      tags:
        - Temps Réel
      summary: Établir une connexion WebSocket pour les activités en temps réel
      description: >-
        Établit une connexion WebSocket pour recevoir en temps réel les
        événements affectant les fils actifs.


        **Sécurité**: Authentification requise (braverJwt)


        **Authentification WebSocket**: Le token braverJwt doit être passé en
        query parameter lors de la connexion initiale.

        Exemple: `wss://api.braver.net/fils/activites?token=<braverJwt>`


        **Expiration du Token**: Le token n'expire PAS tant que la connexion
        WebSocket reste ouverte.

        Si la connexion est fermée, un nouveau token doit être obtenu pour se
        reconnecter.


        **Protocole**: WebSocket standard (wss://)


        **Messages reçus**: Chaque message est un objet JSON avec un champ
        `type` qui détermine sa structure.

        Les types de messages possibles sont:


        - **newThread**: Nouveau fil créé (contient l'objet Thread complet)

        - **newMessage**: Nouveau message dans un fil (contient threadId et
        l'objet Message)

        - **threadUpdated**: Fil mis à jour (contient threadId et l'objet Thread
        mis à jour, tous les champs peuvent être modifiés)

        - **threadClosed**: Fil fermé (contient threadId)


        Voir le schéma `WebSocketMessage` pour la structure détaillée de chaque
        type.


        **Exemples détaillés**: Voir le dossier `examples/websocket/` pour des
        exemples JSON complets couvrant tous les cas d'usage :


        - **newThread** : 4 exemples (avec patient, sans patient, avec message
        initial, avec participant pending)

        - **newMessage** : 4 exemples (texte simple, markdown, pièce jointe,
        système)

        - **threadUpdated** : 6 exemples (ajout participant, changement titre,
        association patient, mise en sourdine, marquage lu, résumés IA)

        - **threadClosed** : 1 exemple (fermeture normale)


        **Note importante** : Les cliniques ne peuvent pas écrire de messages
        (permissions read_only uniquement).
      operationId: getActivitiesSocket
      responses:
        '101':
          description: Protocol Switch to WebSocket (si upgrade direct)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSocketMessage'
        '401':
          description: Non autorisé
components:
  securitySchemes:
    braverJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT émis par Braver suite à l'échange d'un token Ofys via POST
        /auth/token.

        Doit être transmis dans Authorization: Bearer <token> pour tous les
        appels de cette API,

        à l'exception de l'obtention du jeton lui-même.
    ofysJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT émis par Ofys, inclus en Authorization: Bearer <token> lors de
        l'appel à POST /auth/token.

        Claims requis:

        - sub: identifiant utilisateur Ofys

        - exp, iat: timestamps

        - iss: URL identifiant Ofys

        - tid: identifiant de la clinique/client

        Le token peut aussi être utilisé comme sso_token pour
        https://app.braver.net/?sso_token=...
  parameters:
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Identifiant côté Ofys ou Braver selon le contexte
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: UUID v4 pour garantir l'idempotence (optionnel, durée 1h)
  schemas:
    BraverToken:
      type: object
      required:
        - access_token
        - expires_in
      properties:
        access_token:
          description: JWT émis par Braver à utiliser pour les appels suivants
          type: string
        token_type:
          default: Bearer
          const: Bearer
          type: string
        expires_in:
          description: Durée de validité du token en secondes
          type: integer
    CreateBraverToken:
      type: object
      properties:
        ofysClientId:
          description: >-
            Si l'utilisateur est dans plusieurs cliniques, il faut préciser la
            clinique dans laquelle il est connecté
          type: string
    ActiveThreadStats:
      type: object
      required:
        - nbFilsActifs
        - nbFilsNonLus
      properties:
        nbFilsActifs:
          description: Nombre de fils non fermés
          type: integer
        nbFilsNonLus:
          description: Nombre de fils avec un ou plusieurs messages non lus
          type: integer
    ThreadListResponse:
      type: object
      required:
        - threads
        - hasMore
      properties:
        threads:
          description: Liste des fils actifs résumés (du plus récent au plus ancien)
          type: array
          items: &ref_2
            type: object
            required:
              - braverDiscussionId
              - titre
              - participants
              - lieux
              - estFerme
              - nbMessagesNonLus
            properties:
              braverDiscussionId:
                type: string
              titre:
                type: string
              participants:
                type: array
                items: &ref_3
                  type: object
                  required:
                    - id
                    - type
                    - nomAffiche
                  properties:
                    id:
                      type: string
                    type:
                      anyOf:
                        - const: professionnel
                          type: string
                        - const: clinique
                          type: string
                        - const: systeme
                          type: string
                    status:
                      anyOf:
                        - const: pending
                          type: string
                        - const: active
                          type: string
                        - const: left
                          type: string
                    nomAffiche:
                      type: string
                    profession:
                      type: string
                    permissions:
                      type: array
                      items:
                        anyOf:
                          - const: read_only
                            type: string
                          - const: reactions_only
                            type: string
                          - const: messages_only
                            type: string
                          - const: full
                            type: string
                    lieu:
                      type: object
                      required: &ref_0
                        - id
                        - nom
                        - noms
                        - typeLieu
                      properties: &ref_1
                        id:
                          type: string
                        nom:
                          description: >-
                            Nom du lieu en français si disponible, sinon la
                            première traduction disponible
                          type: string
                        noms:
                          description: Noms localisés du lieu.
                          type: object
                          patternProperties:
                            ^(.*)$:
                              type: string
                        typeLieu:
                          type: string
                        adresse:
                          type: string
                        longitude:
                          type: number
                        latitude:
                          type: number
              lieux:
                type: array
                items: &ref_4
                  type: object
                  required: *ref_0
                  properties: *ref_1
              patient:
                type: object
                required: &ref_5
                  - prenom
                  - nom
                properties: &ref_6
                  ofysPatientId:
                    type: string
                  prenom:
                    type: string
                  nom:
                    type: string
                  sexeNaissance:
                    anyOf: &ref_9
                      - const: M
                        type: string
                      - const: F
                        type: string
                      - const: O
                        type: string
                      - const: NA
                        type: string
                  dateNaissance:
                    format: date
                    type: string
                  nam:
                    type: string
              estFerme:
                description: Indique si le fil est fermé
                type: boolean
              enSourdineJusqua:
                format: date-time
                description: >-
                  Indique jusqu’à quand le fil est en sourdine (null si pas en
                  sourdine)
                type: string
              ofysPatientId:
                description: Identifiant Ofys associé si établi
                type: string
              nbMessagesNonLus:
                description: Nombre de messages non lus dans ce fil
                type: integer
              resumeDepuisDebut:
                description: Résumé IA de la discussion depuis le début (markdown)
                type: string
              resumeDepuisDerniereInteraction:
                description: >-
                  Résumé IA de la discussion depuis la dernière interaction
                  (markdown)
                type: string
        hasMore:
          description: Indique s’il y a d’autres fils à récupérer
          type: boolean
        nextCursor:
          description: ID du dernier fil pour la prochaine requête (null si hasMore=false)
          type: string
    ThreadSummary: *ref_2
    Thread: &ref_23
      type: object
      required:
        - braverDiscussionId
        - titre
        - participants
        - lieux
        - messages
        - nbMessages
        - nbMessagesNonLus
        - estFerme
      properties:
        braverDiscussionId:
          type: string
        titre:
          type: string
        participants:
          type: array
          items: *ref_3
        lieux:
          type: array
          items: *ref_4
        patient:
          type: object
          required: *ref_5
          properties: *ref_6
        messages:
          type: array
          items: &ref_14
            description: >-
              Message retourné par GET /fil/{id}. Contient soit du contenu
              texte, soit une pièce jointe, mais pas les deux.
            anyOf:
              - &ref_15
                type: object
                required:
                  - id
                  - sequenceId
                  - auteur
                  - type
                  - contenu
                  - creeAt
                  - nonLu
                properties:
                  id:
                    type: string
                  sequenceId:
                    description: Ordre strict des messages dans le fil
                    type: integer
                  auteur: *ref_3
                  type:
                    const: contenu
                    type: string
                  contenu: &ref_17
                    type: object
                    required: &ref_7
                      - texte
                    properties: &ref_8
                      texte:
                        type: string
                      format:
                        anyOf:
                          - const: texte
                            type: string
                          - const: markdown
                            type: string
                  creeAt:
                    format: date-time
                    type: string
                  nonLu:
                    type: boolean
              - &ref_16
                type: object
                required:
                  - id
                  - sequenceId
                  - auteur
                  - type
                  - pieceJointe
                  - creeAt
                  - nonLu
                properties:
                  id:
                    type: string
                  sequenceId:
                    description: Ordre strict des messages dans le fil
                    type: integer
                  auteur: *ref_3
                  type:
                    const: pieceJointe
                    type: string
                  pieceJointe: &ref_19
                    type: object
                    required:
                      - id
                      - nomFichier
                      - typeMime
                      - fichierPret
                    properties:
                      id:
                        type: string
                      nomFichier:
                        type: string
                      typeMime:
                        type: string
                      tailleOctets:
                        description: >-
                          Taille en octets du fichier. Représenté en String pour
                          éviter les overflow
                        type: string
                      urlTelechargement:
                        format: uri
                        type: string
                      fichierPret:
                        type: boolean
                  creeAt:
                    format: date-time
                    type: string
                  nonLu:
                    type: boolean
        nbMessages:
          description: Nombre total de messages dans ce fil
          type: integer
        nbMessagesNonLus:
          description: Nombre de messages non lus dans ce fil
          type: integer
        estFerme:
          description: Indique si le fil est fermé
          type: boolean
        enSourdineJusqua:
          format: date-time
          description: >-
            Indique jusqu’à quand le fil est en sourdine (null si pas en
            sourdine)
          type: string
        ofysPatientId:
          description: Identifiant Ofys associé si établi
          type: string
        braverPatientId:
          description: Identifiant Braver du patient (si le patient a été créé côté Braver)
          type: string
        resumeDepuisDebut:
          description: Résumé IA de la discussion depuis le début (markdown)
          type: string
        resumeDepuisDerniereInteraction:
          description: Résumé IA de la discussion depuis la dernière interaction (markdown)
          type: string
    ThreadCreate:
      type: object
      required:
        - ofysId
        - titre
        - participants
      properties:
        ofysId:
          description: Identifiant Ofys du fil
          type: string
        titre:
          type: string
        participants:
          type: array
          items: &ref_12
            type: object
            properties:
              professionnelOfysId:
                type: string
              locationOfysId:
                type: string
        contenuInitial:
          type: object
          required: *ref_7
          properties: *ref_8
        patient:
          description: >-
            Créer un patient Braver en même temps que la création du fil.
            Mutuellement exclusif avec ofysPatientId
          type: object
          required: &ref_10
            - ofysPatientId
            - prenom
            - nom
            - dateNaissance
            - nam
          properties: &ref_11
            ofysPatientId:
              description: Identifiant Ofys du patient
              type: string
            prenom:
              type: string
            nom:
              type: string
            sexeNaissance:
              anyOf: *ref_9
            dateNaissance:
              format: date
              type: string
            nam:
              description: Numéro d'assurance maladie
              type: string
        ofysPatientId:
          description: >-
            Associer un patient existant au fil. Mutuellement exclusif avec
            patient
          type: string
        piecesJointes:
          type: array
          items: &ref_18
            type: object
            required:
              - nomFichier
              - typeMime
              - description
            properties:
              nomFichier:
                description: Nom du fichier
                type: string
              typeMime:
                description: Type MIME du fichier (ex. application/pdf, image/png)
                type: string
              description:
                description: Description ou légende du fichier
                type: string
              contenuBase64:
                format: byte
                maxLength: 52428800
                description: >-
                  Contenu du fichier encodé en base64 (mutuellement exclusif
                  avec urlTelechargement)
                          Limite: max 50 MB par fichier en base64 (≈ 37.5 MB de données réelles)
                          Limites globales: max 2 GB total par message, max 10 fichiers par message
                type: string
              urlTelechargement:
                format: uri
                description: >-
                  URL pour télécharger le fichier (mutuellement exclusif avec
                  contenuBase64)
                type: string
    ThreadUpdate:
      anyOf:
        - title: Marquer comme lu jusqu’à ce sequenceId
          type: object
          required:
            - marquerLuJusquaSequenceId
          properties:
            marquerLuJusquaSequenceId:
              minimum: 0
              description: Marque tous les messages jusqu’à ce sequenceId comme lus
              type: integer
        - title: Marquer comme non lu
          type: object
          required:
            - marquerNonLu
          properties:
            marquerNonLu:
              description: Marque le fil globalement comme non lu
              type: boolean
        - title: Mettre en sourdine pour N secondes
          type: object
          required:
            - mettreEnSourdinePourSecondes
          properties:
            mettreEnSourdinePourSecondes:
              minimum: 0
              description: Mettre en sourdine pour N secondes (0 pour retirer la sourdine)
              type: integer
        - title: Associer un patient
          type: object
          required:
            - associerPatient
          properties:
            associerPatient:
              description: >-
                Associer un patient existant au fil. Soit son ID Ofys, ou les
                détails pour un nouveau patient
              anyOf:
                - &ref_13
                  description: >-
                    Créer un patient Braver en même temps que la création du
                    fil. Mutuellement exclusif avec ofysPatientId
                  type: object
                  required: *ref_10
                  properties: *ref_11
                - type: string
        - title: Fermer le fil
          type: object
          required:
            - fermer
          properties:
            fermer:
              description: >-
                Fermer le fil. Doit être "true", un fil ne peut pas être
                ré-ouvert
              type: boolean
        - title: Quitter le fil sans le fermer
          type: object
          required:
            - quitterSansFermer
          properties:
            quitterSansFermer:
              description: Quitter le fil sans le fermer. Doit être "true"
              type: boolean
    ThreadParticipantRef: *ref_12
    Participant: *ref_3
    PracticeLocation: *ref_4
    PatientMini:
      type: object
      required: *ref_5
      properties: *ref_6
    PatientCreateForThread: *ref_13
    Message: *ref_14
    MessageWithContent: *ref_15
    MessageWithAttachment: *ref_16
    MessageContent: *ref_17
    MessageCreate:
      type: object
      properties:
        contenu:
          type: object
          required: *ref_7
          properties: *ref_8
        piecesJointes:
          type: array
          items: *ref_18
    Attachment: *ref_19
    AttachmentCreate: *ref_18
    ProfessionalProfile: &ref_20
      type: object
      required:
        - id
        - nom
        - prenom
        - professions
        - lieux
      properties:
        id:
          type: string
        nom:
          type: string
        prenom:
          type: string
        professions:
          type: array
          items:
            type: object
            required:
              - id
            properties:
              id:
                type: string
              numeroPratique:
                type: string
        lieux:
          type: array
          items: *ref_4
    ProfessionalSearchResponse:
      type: object
      required:
        - results
        - pageToken
      properties:
        results:
          type: array
          items: *ref_20
        pageToken:
          description: PageToken pour la prochaine requête
          type: string
    WorkplaceSearchResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items: *ref_4
    Profession: &ref_21
      type: object
      required:
        - id
        - type
        - labels
      properties:
        id:
          description: Identifiant unique de la profession
          type: string
        type:
          anyOf:
            - const: clinique_sans_licence
              type: string
            - const: clinique_licence
              type: string
            - const: non_clinique
              type: string
        labels:
          type: object
          properties:
            fr_M:
              type: string
            fr_F:
              type: string
            fr_O:
              type: string
            en_M:
              type: string
            en_F:
              type: string
            en_O:
              type: string
          description: Libellés localisés et genrés de la profession
    LocationType: &ref_22
      type: object
      required:
        - id
        - labels
      properties:
        id:
          description: Identifiant unique du type de lieu
          type: string
        labels:
          type: object
          properties:
            fr:
              type: string
            en:
              type: string
          description: Libellés localisés du type de lieu
    ProfessionListResponse:
      type: object
      required:
        - professions
      properties:
        professions:
          type: array
          items: *ref_21
    LocationTypeListResponse:
      type: object
      required:
        - typesLieux
      properties:
        typesLieux:
          type: array
          items: *ref_22
    WebSocketMessage:
      anyOf:
        - &ref_24
          type: object
          required:
            - type
            - thread
            - timestamp
          properties:
            type:
              const: newThread
              type: string
            thread: *ref_23
            timestamp:
              format: date-time
              type: string
        - &ref_25
          type: object
          required:
            - type
            - threadId
            - message
            - timestamp
          properties:
            type:
              const: newMessage
              type: string
            threadId:
              type: string
            message: *ref_14
            timestamp:
              format: date-time
              type: string
        - &ref_26
          type: object
          required:
            - type
            - threadId
            - thread
            - timestamp
          properties:
            type:
              const: threadUpdated
              type: string
            threadId:
              type: string
            thread: *ref_2
            timestamp:
              format: date-time
              type: string
        - &ref_27
          type: object
          required:
            - type
            - threadId
            - timestamp
          properties:
            type:
              const: threadClosed
              type: string
            threadId:
              type: string
            timestamp:
              format: date-time
              type: string
    WebSocketMessageNewThread: *ref_24
    WebSocketMessageNewMessage: *ref_25
    WebSocketMessageThreadUpdated: *ref_26
    WebSocketMessageThreadClosed: *ref_27
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - timestamp
            - traceId
          properties:
            code:
              description: >-
                Code d'erreur machine-readable (ex. USER_ALREADY_EXISTS,
                PATIENT_NOT_FOUND)
              type: string
            message:
              description: Message d'erreur lisible par l'humain
              type: string
            details:
              type: object
              patternProperties:
                ^(.*)$: {}
            timestamp:
              format: date-time
              description: Timestamp ISO 8601 de l'erreur
              type: string
            traceId:
              description: Identifiant unique pour tracer l'erreur en production
              type: string