# Objet de parcours

Les méthodes de [cycle de vie](/fr/developer/api-reference/customer-journey-api/lifecycle/) et de [création et mise à jour](/fr/developer/api-reference/customer-journey-api/create-update/) retournent toutes un objet de parcours avec la même structure de haut niveau :

```json title="Structure"
{
  "info": { ... },        // métadonnées en lecture seule (réponses uniquement)
  "params": { ... },      // configuration globale du parcours (création / mise à jour)
  "points": [ ... ],      // nœuds du canevas et leurs connexions
  "comments": [ ... ]     // commentaires du canevas
}
```

Lorsque vous **créez** ou **mettez à jour** un parcours, vous envoyez `title`, `params`, `points` et `comments`. Les réponses retournent `info` (qui contient `params`) ainsi que `points` et `comments`.

## Info

Métadonnées du parcours en lecture seule. Retournées par chaque méthode v3. Ne fait pas partie du corps de la requête.

| Champ | Type | Description |
|---|---|---|
| `uuid` | string | [ID de parcours](/fr/developer/api-reference/api-identifiers/#journey-id). |
| `title` | string | Nom du parcours. |
| `status` | [`JourneyStatus`](#journeystatus-enum) | État actuel. |
| `created_at` | string | Horodatage de création (ISO 8601). |
| `updated_at` | string | Horodatage de la dernière mise à jour (ISO 8601). |
| `is_first_activated` | bool | Indique si le parcours a été démarré au moins une fois. |
| `params` | [`JourneyParams`](#journeyparams) | Configuration globale du parcours. |
| `category_uuid` | string | UUID de la catégorie, ou vide si non catégorisé. |
| `pointCounts` | map<string, uint32> | Nombre de points par type. |
| `campaign_type` | [`CampaignType`](#campaigntype-enum) | Comment les utilisateurs entrent dans le parcours. |
| `stop_reason` | string | Raison de l'arrêt du parcours, le cas échéant. |
| `last_edited_by` | `User` | Utilisateur ayant modifié le parcours en dernier. |
| `dynamic_entry` | bool | Indique si l'entrée dynamique est activée. |

## JourneyParams

Configuration globale du parcours. Envoyée lors de la création/mise à jour et retournée dans `info.params`.

| Champ | Type | Description |
|---|---|---|
| `application_code` | string | [Code d'application](/fr/developer/api-reference/api-identifiers/#application-code) auquel le parcours appartient. Requis à la création. |
| `silent_hours` | [`SilentHours`](#silenthours) | Heures pendant lesquelles les messages sont supprimés, par canal. |
| `capping` | [`EntryCapping`](#entrycapping) | Limites sur la fréquence à laquelle un utilisateur peut réintégrer le parcours. |
| `conversion_window` | [`ConversionWindow`](#conversionwindow) | Fenêtre d'attribution des conversions d'objectifs. |
| `user_id_track_change_policy` | [`UserIDTrackChangePolicy`](#useridtrackchangepolicy-enum) | Comment gérer le changement d'ID d'un utilisateur en milieu de parcours. |

### SilentHours

Supprime l'envoi pendant les heures creuses. Configuré **par canal** : chaque canal prend ses propres `SilentHoursParams` :

| Champ | Type | Description |
|---|---|---|
| `push_params` | `SilentHoursParams` | Heures de silence pour les notifications push. |
| `inapp_params` | `SilentHoursParams` | Heures de silence pour les messages in-app. |
| `email_params` | `SilentHoursParams` | Heures de silence pour les e-mails. |
| `sms_params` | `SilentHoursParams` | Heures de silence pour les SMS. |
| `whatsapp_params` | `SilentHoursParams` | Heures de silence pour WhatsApp. |
| `line_params` | `SilentHoursParams` | Heures de silence pour LINE. |

Chaque `SilentHoursParams` est :

| Champ | Type | Description |
|---|---|---|
| `enabled` | bool | Indique si les heures de silence s'appliquent à ce canal. |
| `from_time` | `Time` | Début de la fenêtre de silence : `{ "hour": 0–23, "minute": 0–59 }`. |
| `to_time` | `Time` | Fin de la fenêtre de silence. |
| `week_days` | bool[] | Sept booléens pour les jours où la fenêtre s'applique (lundi = index 0). |
| `behavior` | enum | Que faire lorsqu'un message tombe pendant les heures de silence : `WaitAndSend` (attendre, puis envoyer à la fin de la fenêtre), `DropAndGo` (ignorer le message, continuer le parcours immédiatement), ou `WaitAndDrop` (attendre la fin de la fenêtre, puis continuer sans envoyer). |

### EntryCapping

Limite la fréquence à laquelle le même utilisateur peut entrer dans le parcours.

| Champ | Type | Description |
|---|---|---|
| `is_enabled` | bool | Indique si le plafonnement des entrées est activé. |
| `period` | uint64 | Nombre minimum de secondes entre les entrées d'un utilisateur. |

### ConversionWindow

| Champ | Type | Description |
|---|---|---|
| `seconds` | uint64 | Combien de temps après être entré dans un parcours, l'accomplissement d'un objectif par un utilisateur compte encore comme une conversion. |

## Point

Un point est un nœud sur le canevas du parcours : un point d'entrée, un message, un délai, un diviseur, etc.

| Champ | Type | Description |
|---|---|---|
| `uuid` | string | ID unique du point dans le parcours. Doit être un UUID canonique [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122) : 32 chiffres hexadécimaux en groupes 8-4-4-4-12. |
| `title` | string | Nom d'affichage du point. |
| `point_type` | [`PointType`](#pointtype-enum) | Le type de nœud. |
| `outputs` | array of [`PointOutput`](#pointoutput) | Connexions aux points en aval. |
| `position` | [`Position`](#position) | Coordonnées du canevas. |
| `point_data` | object | Exactement une clé imbriquée, correspondant à `point_type` (voir le tableau des [types de points](#point-types-and-point_data)). |

<Aside type="note">
Tous les UUID (`info.uuid`, chaque `uuid` de point, et le `next_point_uuid` de chaque sortie) doivent être des UUID canoniques RFC 4122 (groupes hexadécimaux 8-4-4-4-12).
</Aside>

### PointOutput

Les sorties d'un point sont ses branches sortantes. Leurs clés ne sont **pas libres**. Le validateur attend un ensemble exact de clés pour chaque type de point, et rejette un parcours dont un point a un nombre incorrect de sorties ou une clé qu'il ne reconnaît pas.

| Champ | Type | Description |
|---|---|---|
| `identity.key` | string | Clé de la branche. Doit suivre les [règles des clés de sortie](#output-keys) ci-dessous. |
| `identity.order` | int | Ordre d'affichage de la branche. |
| `info.title` | string | Étiquette de branche facultative. |
| `info.next_point_uuid` | string | UUID du prochain point auquel cette branche se connecte. |

#### Clés de sortie

La branche par défaut (la première) est toujours nommée `"default"`. Les branches supplémentaires sont nommées `"output1"`, `"output2"`, … (le préfixe `output` suivi d'un index basé sur 1). Deux types de points dérogent à cette règle, comme indiqué ci-dessous.

| Type de point | Clés de sortie attendues |
|---|---|
| Points d'entrée (`START_BY_SEGMENT`, `START_BY_API`, `EVENT`), `INAPP`, `SET_TAGS`, `WEBHOOK`, `AUDIENCE_SYNC`, et points de message sans diviseur (`SEND_PUSH`, `SEND_EMAIL`, `SEND_SMS`, `SEND_WHATSAPP`, `SEND_LINE`, `SEND_KAKAO`, `SEND_TELEGRAM`, `SEND_DATA`) | `default` |
| `GOAL_EVENT`, `EXIT` | aucun (pas de sorties) |
| `FILTER` | `default`, `output1` |
| `BOOLEAN_SPLITTER` | `default`, puis `output1` … `outputN` (une branche supplémentaire par condition. Une simple division oui/non est `default` + `output1`) |
| `WAIT` (délai) | `default`. Un délai dynamique avec division de branche ajoute `output1` |
| `WAIT_EVENT` | `default` est la branche de l'**événement non déclenché**. `output1` (ou, avec un script de conditions, une branche par condition) est le chemin déclenché |
| `SEND_PUSH` avec un diviseur | `default`, `output1` (et `output2` lorsque les diviseurs de message et de livraison sont tous deux activés) |
| `SEND_EMAIL` / `SEND_SMS` / `SEND_LINE` / `SEND_WHATSAPP` avec un diviseur | `default`, `output1` |
| `SEND_WHATSAPP` avec un préréglage de réponse rapide | `default`, plus une branche par réponse rapide. La clé est la valeur de la réponse rapide elle-même |
| `AB_SPLITTER` | `output0`, `output1`, `output2`, … (un par variante. **Il n'y a pas de branche `default`**) |

### Position

| Champ | Type | Description |
|---|---|---|
| `x` | float | Coordonnée horizontale sur le canevas. |
| `y` | float | Coordonnée verticale sur le canevas. |

## Types de points et point_data

`point_data` est un one-of : il contient exactement un objet imbriqué dont la clé est déterminée par le `point_type` du point.

| `point_type` | Clé `point_data` | Objectif |
|---|---|---|
| `POINT_TYPE_START_BY_SEGMENT` | `start_by_segment` | Entrée : utilisateurs correspondant à un segment. |
| `POINT_TYPE_EVENT` | `message_bus` | Entrée : utilisateurs déclenchant un événement. |
| `POINT_TYPE_START_BY_API` | `start_by_api` | Entrée : utilisateurs injectés via l'appel [Start by API](/fr/developer/api-reference/customer-journey-api/start-by-api/). |
| `POINT_TYPE_WAIT` | `delay` | Attendre un intervalle fixe ou dynamique. |
| `POINT_TYPE_WAIT_EVENT` | `wait_event` | Attendre qu'un événement se produise. |
| `POINT_TYPE_SEND_PUSH` | `send_push` | Envoyer une notification push. |
| `POINT_TYPE_SEND_EMAIL` | `send_email` | Envoyer un e-mail. |
| `POINT_TYPE_SEND_SMS` | `send_sms` | Envoyer un SMS. |
| `POINT_TYPE_SEND_WHATSAPP` | `send_whatsapp` | Envoyer un message WhatsApp. |
| `POINT_TYPE_SEND_TELEGRAM` | `send_telegram` | Envoyer un message Telegram. |
| `POINT_TYPE_SEND_KAKAO` | `send_kakao` | Envoyer un message Kakao. |
| `POINT_TYPE_SEND_LINE` | `send_line` | Envoyer un message LINE. |
| `POINT_TYPE_SEND_DATA` | `send_data` | Envoyer un message de données silencieux. |
| `POINT_TYPE_INAPP` | `inapp` | Afficher un message in-app. |
| `POINT_TYPE_BOOLEAN_SPLITTER` | `boolean_splitter` | Diviser les utilisateurs selon une condition (segment, tags ou événement). |
| `POINT_TYPE_AB_SPLITTER` | `ab_splitter` | Diviser les utilisateurs en groupes A/B. |
| `POINT_TYPE_FILTER` | `filter` | Autoriser uniquement les utilisateurs correspondant à un filtre à continuer. |
| `POINT_TYPE_SET_TAGS` | `set_tags` | Mettre à jour les tags utilisateur. |
| `POINT_TYPE_WEBHOOK` | `web_hook` | Envoyer une requête HTTP sortante. |
| `POINT_TYPE_GOAL_EVENT` | `goal_event` | Suivre un objectif de conversion. |
| `POINT_TYPE_AUDIENCE_SYNC` | `audience_sync` | Synchroniser les utilisateurs avec une audience externe. |
| `POINT_TYPE_EXIT` | `terminator` | Quitter le parcours. |

<Aside type="note">
Les charges utiles `point_data` par type sont documentées dans la [Référence des points](/fr/developer/api-reference/customer-journey-api/point-reference/). Les points d'entrée, de synchronisation, de division et d'action y sont entièrement couverts. Les points de messagerie sont couverts au niveau de l'enveloppe avec des liens vers la documentation du canal correspondant.
</Aside>

### Exemple de point

Un point "définir des tags" avec une seule connexion en aval :

```json
{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Tag as engaged",
  "point_type": "POINT_TYPE_SET_TAGS",
  "position": { "x": 480, "y": 120 },
  "outputs": [
    {
      "identity": { "key": "default", "order": 0 },
      "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" }
    }
  ],
  "point_data": {
    "set_tags": {
      "application_code": "XXXXX-XXXXX",
      "tags": [ { "name": "engaged", "value": "true" } ]
    }
  }
}
```

## JourneyComment

| Champ | Type | Description |
|---|---|---|
| `id` | string | UUID du commentaire. |
| `message` | string | Texte du commentaire. |
| `position` | [`Position`](#position) | Coordonnées du canevas. |
| `index` | int | Ordre d'affichage. |
| `created_at` | string | Horodatage de création (ISO 8601). |
| `deleted` | bool | Indique si le commentaire est supprimé. |

## Énumérations

### Énumération JourneyStatus

`STATUS_DRAFT`, `STATUS_RUNNING`, `STATUS_FINISHED`, `STATUS_ARCHIVED`, `STATUS_PAUSED`, `STATUS_UNKNOWN`.

### Énumération CampaignType

- `TriggerBased` : les utilisateurs entrent lors d'un événement.
- `AudienceBased` : les utilisateurs entrent à partir d'un segment.
- `APIBased` : les utilisateurs entrent via l'appel Start by API.
- `Mixed` : plus d'un type d'entrée.
- `Unknown` : type d'entrée non déterminé.

### Énumération PointType

Voir le tableau des [types de points](#point-types-and-point_data) ci-dessus pour la liste complète et la clé `point_data` à laquelle chacun correspond.

### Énumération UserIDTrackChangePolicy

Contrôle ce qui arrive à un utilisateur qui est en milieu de parcours lorsque son [ID utilisateur](/fr/developer/api-reference/api-identifiers/#user-id) change :

- `DEFAULT` : comportement par défaut.
- `TRACK` : continuer à suivre l'utilisateur sous le nouvel ID.
- `DROP` : supprimer l'utilisateur du parcours lorsque son ID change.

## Connexe

<CardGrid>
  <LinkCard title="Référence des points" href="/developer/api-reference/customer-journey-api/point-reference/" />
  <LinkCard title="Créer et mettre à jour" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Cycle de vie" href="/developer/api-reference/customer-journey-api/lifecycle/" />
</CardGrid>