# Démarrage par API

`POST` `https://journey.pushwoosh.com/api/journey/{id}/start/external`

Fait entrer un ensemble d'utilisateurs dans le **point d'entrée API** d'un Journey. Utilisez-le pour piloter des Journeys depuis votre propre backend. Par exemple, démarrez un flux d'intégration lorsqu'un utilisateur termine son inscription sur votre serveur.

<Aside type="tip">
Ne confondez pas cet appel avec le [démarrage du cycle de vie](/fr/developer/api-reference/customer-journey-api/lifecycle/#endpoints), qui active un Journey et le fait passer à l'état **En cours d'exécution**. Le démarrage par API injecte des utilisateurs dans un Journey qui est déjà en cours d'exécution. Consultez le [tableau comparatif](/fr/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api).
</Aside>

## Prérequis

- Le Journey est dans l'état **En cours d'exécution**.
- Le Journey contient exactement un point d'entrée API (l'élément « Démarrage par API »), et cet élément n'est pas désactivé.
- Les noms d'attributs que vous envoyez correspondent aux attributs configurés sur ce point d'entrée API.

<Aside type="caution" title="Limite de débit">
Chaque point d'entrée API accepte **une requête par minute**. Une deuxième requête dans cette fenêtre renvoie une erreur (`Enhance your calm! only one request per minute is allowed`). Regroupez vos destinataires en une seule requête plutôt que d'en envoyer plusieurs petites.
</Aside>

## Paramètres de chemin

| Nom | Type | Description |
|---|---|---|
| `id` | chaîne | [ID du Journey](/fr/developer/api-reference/api-identifiers/#journey-id) du Journey en cours d'exécution. |

## En-têtes de requête

| Nom | Requis | Valeur |
|---|---|---|
| `Content-Type` | Oui | `application/json` |
| `Authorization` | Oui | `Api <server_api_token>`. Voir [Jeton d'API serveur](/fr/developer/api-reference/api-access-token/#server-api-token). |

## Corps de la requête

Le corps a un seul objet `payload`. Vous devez fournir **exactement un** des éléments suivants : `users`, `hwids` ou `filter` pour sélectionner qui entre dans le Journey.

| Champ | Type | Description |
|---|---|---|
| `payload.users` | string[] | [ID utilisateur](/fr/developer/api-reference/api-identifiers/#user-id) à faire entrer. Mutuellement exclusif avec `hwids` et `filter`. |
| `payload.hwids` | string[] | [HWID](/fr/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) à faire entrer. Mutuellement exclusif avec `users` et `filter`. |
| `payload.filter` | string | Une expression [seglang](/fr/developer/api-reference/segmentation-filters-api/segmentation-language/) sélectionnant l'audience. Mutuellement exclusif avec `users` et `hwids`. |
| `payload.attribute_values` | map&lt;string, string&gt; | Optionnel. Valeurs pour les attributs personnalisés définis sur le point d'entrée API. Chaque clé doit correspondre à un nom d'attribut configuré. |

### Exemples de requête

##### Faire entrer des utilisateurs spécifiques

```bash
curl -X POST 'https://journey.pushwoosh.com/api/journey/<journey_id>/start/external' \
  -H 'Authorization: Api YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "users": ["user-123", "user-456"]
    }
  }'
```
##### Faire entrer des utilisateurs spécifiques avec des attributs

```json
{
  "payload": {
    "users": ["user-123", "user-456"],
    "attribute_values": {
      "promo_code": "SUMMER25",
      "tier": "gold"
    }
  }
}
```

##### Faire entrer une audience par filtre

```json
{
  "payload": {
    "filter": "A(\"XXXXX-XXXXX\").tags(\"City\").eq(\"London\")"
  }
}
```


## Réponse

<Tabs>
<TabItem label="200">

```json
{
  "request_uuid": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}
```

| Champ | Type | Description |
|---|---|---|
| `request_uuid` | chaîne | Identifiant de la requête d'entrée acceptée. La requête est traitée de manière asynchrone. |

</TabItem>
<TabItem label="400">

Les erreurs de validation renvoient un code HTTP `400` avec un message descriptif. Cas courants :

| Message | Cause |
|---|---|
| `one of users, hwids or filter must be provided` | Aucun des trois sélecteurs n'a été défini. |
| `only one of users, hwids or filter must be provided` | Plus d'un sélecteur a été défini. |
| `Journey is not running` | Le Journey n'est pas dans l'état En cours d'exécution. |
| `zero api start points` | Le Journey n'a pas de point d'entrée API. |
| `there is more then one api start point` | Le Journey a plus d'un point d'entrée API. |
| `point is deactivated` | Le point d'entrée API est désactivé. |
| `unknown attribute: <name>` | Une clé `attribute_values` n'est pas configurée sur le point d'entrée API. |
| `Enhance your calm! only one request per minute is allowed` | Limite de débit atteinte (une requête par minute par point d'entrée). |

</TabItem>
</Tabs>

## Articles connexes

<CardGrid>
  <LinkCard title="Cycle de vie" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Obtenir les statistiques du Journey" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Langage de segmentation" href="/developer/api-reference/segmentation-filters-api/segmentation-language/" />
</CardGrid>