> ## 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.

# Intégration REST

> Le modèle d'intégration recommandé pour connecter NBQ à un backend existant.

L'API REST est l'intégration disponible pour la V1. Votre backend conserve les identifiants retournés par NBQ et appelle le moteur lorsque votre expérience a besoin d'une nouvelle question.

## Responsabilités

| Votre application                         | NBQ Engine                                            |
| ----------------------------------------- | ----------------------------------------------------- |
| Afficher ou reformuler la question        | Choisir les meilleures candidates                     |
| Conserver `session_id` et `state_version` | Maintenir l'état canonique de la session              |
| Envoyer la réponse réellement observée    | Comprendre la réponse et mettre à jour la progression |
| Décider quand terminer l'expérience       | Signaler les avertissements et l'absence de question  |
| Protéger la clé API côté serveur          | Appliquer l'isolation, les scopes et l'idempotence    |

## Boucle recommandée

1. Créez une session une fois avec `POST /v1/sessions`.
2. Appelez `/next` avec la dernière `state_version`.
3. Utilisez `candidates[0]`, ou choisissez parmi les candidats si votre produit le nécessite.
4. Après la réponse, appelez de nouveau `/next` avec `previous_turn`.
5. Envoyez les informations externes par `/events` sans provoquer une nouvelle sélection.
6. Envoyez le résultat final par `/feedback`.

<Note>
  Si votre backend redémarre, relisez la session avec `GET /v1/sessions/{session_id}`. Ne reconstruisez pas l'état à partir d'une copie locale obsolète.
</Note>

## Réponses à choix

Lorsque votre interface affiche les choix fournis par NBQ, renvoyez leurs `choice_id` dans `structured_answer.choice_ids`. Cela évite une interprétation sémantique inutile et conserve un mapping déterministe.

## Privilégier les réponses structurées

Si votre application connaît déjà le sens de la réponse, transmettez-le directement :

* `previous_turn.outcome` indique si la question a reçu une réponse exploitable, aucune réponse ou un refus ;
* `structured_answer.choice_ids` transmet les choix d'une question fermée ou semi-ouverte ;
* `client_updates.data` envoie une donnée métier déjà validée par votre système.

```json theme={null}
{
  "state_version": 3,
  "previous_turn": {
    "decision_id": "dec_7f2a",
    "question_id": "q_budget",
    "outcome": "asked_answered"
  },
  "client_updates": {
    "data": [
      { "id": "info_budget", "operation": "set", "value": 3000 }
    ]
  }
}
```

Ce chemin est déterministe : NBQ valide et applique les informations structurées sans demander à un modèle de langage de réinterpréter le texte. Il est donc plus rapide et reproductible. N'inventez toutefois pas une valeur incertaine : lorsque votre application ne connaît que le verbatim, envoyez `user_text` et laissez NBQ l'analyser.

<Note>
  `outcome` décrit le résultat de la question, mais ne crée pas à lui seul une donnée métier. Utilisez également `structured_answer` ou `client_updates` lorsque votre système connaît l'information obtenue.
</Note>

<Card title="Tester avec curl" icon="terminal" href="/fr/quickstart/first-api-call">
  Exécutez le cycle minimal avant de l'intégrer dans votre application.
</Card>