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

# Intégration technique

> Endpoints de l'API, format de requête, structure de réponse et exemples de code pour consommer la sortie JSON de Reelevant

## Endpoint du Runner

Chaque Workflow publié expose une URL de Runner. Lorsque l'Output Node est un **JSON Template**, le Runner renvoie du `application/json` au lieu de HTML ou d'une image.

```
GET https://reelevant.run/{workflowId}/{entrypointId}?rlvt-u={userId}
```

| Paramètre      | Type  | Description                                                                                                                            |
| -------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `workflowId`   | path  | L'ID du Workflow (visible dans l'URL de l'éditeur de Workflow ou dans la fenêtre modale d'intégration)                                 |
| `entrypointId` | path  | L'ID de l'entrypoint au sein du Workflow                                                                                               |
| `rlvt-u`       | query | Identifiant de l'utilisateur pour la personnalisation. Peut être un email, un ID utilisateur interne ou le cookie anonyme `rlvt_tmpId` |

La réponse est un objet JSON dont la forme correspond au schéma du template défini dans la plateforme.

## Format de réponse

Le corps de la réponse correspond directement aux données du template résolu — pas d'enveloppe englobante. Les champs statiques sont renvoyés tels quels et les champs de dépendance sont remplacés par des valeurs réelles issues des Datasources :

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "headline": "Recommended for you",
  "productName": "Running Shoes Pro",
  "productPrice": 129.99
}
```

### En-tête Content-Type

Le Runner renvoie `Content-Type: application/json; charset=utf-8` pour les Output Nodes JSON Template.

### Codes de statut HTTP

| Statut  | Signification                                                                                                  |
| ------- | -------------------------------------------------------------------------------------------------------------- |
| **200** | Le Workflow s'est exécuté avec succès. Le corps contient le payload JSON.                                      |
| **204** | Le Workflow s'est exécuté mais aucun contenu n'a été produit (par exemple, toutes les Branches étaient vides). |
| **404** | Workflow introuvable ou non publié.                                                                            |

## Exemples de code

### JavaScript (fetch)

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const workflowId = 'your-workflow-id'
const userId = 'user@example.com'

const response = await fetch(
  `https://reelevant.run/${workflowId}/0?rlvt-u=${encodeURIComponent(userId)}`
)

if (response.ok) {
  const data = await response.json()
  // data.headline, data.productName, data.productPrice, etc.
  renderRecommendation(data)
}
```

### React

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
function Recommendation({ workflowId, userId }: Props) {
  const [data, setData] = useState(null)

  useEffect(() => {
    fetch(`https://reelevant.run/${workflowId}/0?rlvt-u=${userId}`)
      .then(res => res.json())
      .then(setData)
  }, [workflowId, userId])

  if (!data) return <Skeleton />

  return (
    <div className="recommendation-card">
      <h3>{data.headline}</h3>
      <p>{data.productName} — ${data.productPrice}</p>
      <a href={data.productUrl}>View product</a>
    </div>
  )
}
```

### Python

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

workflow_id = "your-workflow-id"
user_id = "user@example.com"

response = requests.get(
    f"https://reelevant.run/{workflow_id}/0",
    params={"rlvt-u": user_id}
)

if response.ok:
    data = response.json()
    print(data["headline"], data["productName"])
```

### cURL

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -s "https://reelevant.run/{workflowId}/0?rlvt-u=user@example.com"
```

## JSON Templates

### Qu'est-ce qu'un JSON Template ?

Un JSON Template est une définition de schéma réutilisable créée dans la plateforme Reelevant. Il décrit :

* **Definition** — la structure JSON où chaque champ est soit `{ "type": "static", "value": ... }` (fixe), soit `{ "type": "dependency", "variable": "..." }` (résolu à l'exécution)
* **Variables** — des emplacements nommés qui correspondent à des valeurs de Datasource, en cohérence avec les noms de `variable` de la définition

Chaque variable déclare un `type` qui indique au Runner comment résoudre sa dépendance :

| `type`   | Champ supplémentaire | Comportement                                                                        | Exemple de cas d'usage                                     |
| -------- | -------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `scalar` | —                    | Se résout en une valeur unique, sélectionnée automatiquement par Branch             | Le nom de l'utilisateur, une recommandation produit unique |
| `array`  | —                    | Se résout en un tableau de toutes les valeurs à travers les lignes de la Datasource | Liste de produits recommandés, noms de catégories          |
| `fixed`  | `index` (base 0)     | Se résout en la valeur à une position fixe de la Datasource                         | Toujours le 1er (`index: 0`) ou le 3e (`index: 2`) produit |

L'interface expose les positions `fixed` sous la forme **Datasource item #1 … #20** ; l'élément #N correspond à `index: N - 1`.

### API de gestion des templates

Les JSON Templates sont gérés via l'API REST `/workflows/json-templates` :

```
POST   /workflows/json-templates          # Create a template
GET    /workflows/json-templates          # List templates (supports ?workflowId= filter and pagination)
GET    /workflows/json-templates/{id}     # Get a template by ID
PUT    /workflows/json-templates/{id}     # Update a template
DELETE /workflows/json-templates/{id}     # Delete a template
```

### Validation au moment de la publication

Lorsque vous publiez un Workflow qui utilise des Output Nodes JSON Template, la plateforme valide que :

1. **Tous les Nodes JSON Template** du Workflow référencent le **même ID de template** — garantissant une forme de réponse cohérente entre les Branches.
2. Le template référencé **existe** et appartient à votre entreprise.

Si la validation échoue, la publication est rejetée avec une erreur descriptive.

## Combinaison avec d'autres méthodes d'intégration

L'approche par API JSON fonctionne conjointement avec le Client-Side Script et le Server-Side SDK :

* Utilisez le **Server-Side SDK** pour appeler le Runner depuis votre backend et transmettre les données JSON à votre frontend via des props ou l'état serveur.
* Utilisez le **Client-Side Script** pour le tracking d'événements (impressions, clics) parallèlement à votre UI alimentée par JSON.
* Appelez le Runner **directement depuis le navigateur** avec `fetch()` si votre cas d'usage est purement côté client.

## Identité et personnalisation

Le paramètre de requête `rlvt-u` pilote la personnalisation. La valeur que vous transmettez détermine quel profil utilisateur le moteur utilise pour sélectionner les Branches et résoudre les requêtes de Datasource.

Pour de meilleurs résultats :

* Transmettez un **identifiant utilisateur stable** (email, ID interne) lorsque l'utilisateur est connecté.
* Transmettez la valeur du cookie `rlvt_tmpId` pour les visiteurs anonymes — cela préserve la continuité avec le tracking côté client.
* Le même système d'identité alimente tous les Channels Reelevant (email, web, push), la personnalisation est donc cohérente sur tous les points de contact.