> ## 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 Zelinqa à un backend existant.

L'API REST permet d'intégrer Zelinqa directement depuis votre backend. Les [SDK](/fr/integrations/sdk) et le [serveur MCP](/fr/integrations/mcp) utilisent aussi cette API. Votre backend conserve les identifiants retournés par Zelinqa et appelle le moteur lorsque votre expérience a besoin d'une nouvelle question.

## Responsabilités

| Votre application | Zelinqa |
| - | - |
| 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 Zelinqa, 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",
    "user_text": "Mon budget maximum est de 3 000 euros."
  },
  "client_updates": {
    "data": [
      { "id": "info_budget", "operation": "set", "value": 3000 }
    ]
  }
}
```

La donnée déjà confirmée dans `client_updates` est appliquée de façon structurée. Ici, la question est **ouverte** : même avec une donnée confirmée, la réponse réellement donnée dans `user_text` reste obligatoire et peut être analysée par le moteur. Pour une question fermée ou semi-ouverte, des `choice_ids` seuls suffisent si la personne n'a rien ajouté ; ce chemin peut éviter l'analyse par modèle. N'inventez jamais une valeur incertaine.

<Note>
  `outcome` décrit le résultat de la question, mais ne remplace pas `user_text` pour une question ouverte répondue et 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="Appels HTTP avec curl" icon="terminal" href="/fr/quickstart/first-api-call">
  Exécutez le cycle minimal avant de l'intégrer dans votre application.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.