> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelinqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enregistrer une conversion

> Enregistre le résultat d'une conversation à des fins d'analyse et de suivi des conversions. Le `session_id` doit correspondre à celui utilisé lors de l'appel à `/v1/next-questions`. L'en-tête `Idempotency-Key` est obligatoire — rejouer la même clé pour la même conversation est une opération nulle, ce qui rend l'appel sûr à réessayer.




## OpenAPI

````yaml /openapi.fr.yaml post /v1/sessions/{session_id}/conversion
openapi: 3.1.0
info:
  title: API NBQ Engine
  description: >-
    L'API REST du NBQ Engine retourne la prochaine meilleure question à poser
    lors d'une conversation.
  version: 1.0.0
servers:
  - url: https://api.zelinqa.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Vérification de l'état de l'API
  - name: Questions
    description: Sélection de la prochaine question
  - name: Sessions
    description: Enregistrement du résultat de la conversation
paths:
  /v1/sessions/{session_id}/conversion:
    post:
      tags:
        - Sessions
      summary: Enregistrer une conversion
      description: >
        Enregistre le résultat d'une conversation à des fins d'analyse et de
        suivi des conversions. Le `session_id` doit correspondre à celui utilisé
        lors de l'appel à `/v1/next-questions`. L'en-tête `Idempotency-Key` est
        obligatoire — rejouer la même clé pour la même conversation est une
        opération nulle, ce qui rend l'appel sûr à réessayer.
      operationId: recordConversion
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
          description: >-
            L'identifiant de session utilisé lors de l'appel à
            `/v1/next-questions`.
          example: conv-7f3a1c
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: >-
            Une clé unique générée côté client (UUID recommandé). Sûr à
            réessayer — rejouer la même clé est une opération nulle.
          example: 6f1d2c8e-9a4b-4f7a-bd2e-0c1a2b3c4d5e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionRequest'
            example:
              outcome: purchase
              metadata:
                order_value: 1290
                currency: EUR
      responses:
        '202':
          description: Conversion enregistrée
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionResponse'
              example:
                conversion_id: cv_4a7b9c0d1e2f3a4b5c6d7e8f
                request_id: req_77a8b9c0d1e2f3a4
        '403':
          description: Non autorisé
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Erreur de validation — ex. en-tête Idempotency-Key manquant
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Trop de requêtes
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Erreur serveur interne
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ConversionRequest:
      type: object
      required:
        - outcome
      properties:
        outcome:
          type: string
          enum:
            - purchase
            - lead
            - abandon
            - other
          description: Le résultat de la conversation.
          example: purchase
        metadata:
          type: object
          description: >-
            Informations clé/valeur libres pour votre propre usage. Non
            interprétées par NBQ. Taille maximale sérialisée 4096 octets.
          additionalProperties: true
          example:
            order_value: 1290
            currency: EUR
    ConversionResponse:
      type: object
      properties:
        conversion_id:
          type: string
          description: Identifiant de la conversion enregistrée.
          example: cv_4a7b9c0d1e2f3a4b5c6d7e8f
        request_id:
          type: string
          description: >-
            Identifiant unique de cette requête. À inclure dans toute demande de
            support.
          example: req_77a8b9c0d1e2f3a4
    ErrorResponse:
      type: object
      description: >-
        Format RFC 7807 problem-details. Retourné avec Content-Type:
        application/problem+json.
      properties:
        type:
          type: string
          description: URI stable identifiant la classe d'erreur.
          example: https://api.zelinqa.ai/errors/validation_failed
        title:
          type: string
          description: Résumé court et lisible du problème.
          example: Le corps ou les paramètres de la requête ont échoué à la validation.
        status:
          type: integer
          description: Code de statut HTTP, reflété dans le corps.
          example: 422
        request_id:
          type: string
          description: À inclure dans toute demande de support pour tracer l'appel exact.
          example: req_2c4e6a8b0d1f3508
        detail:
          type: string
          description: Explication lisible spécifique à cette occurrence.
          example: >-
            Erreur de valeur, requête invalide : fournissez conversation_history
            ou context
        errors:
          type: array
          description: >-
            Problèmes de validation par champ. Présent en cas d'erreurs de
            validation 422.
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  type: string
              msg:
                type: string
              type:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Transmettez votre clé API NBQ dans l'en-tête Authorization : `Bearer
        nbq_live_xxx`

````