# Запуск через API

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

Добавляет группу пользователей в **точку входа API** Journey. Используйте этот вызов для запуска Journey с вашего бэкенда. Например, для запуска онбординга, когда пользователь завершает регистрацию на вашем сервере.

<Aside type="tip">
Не путайте этот вызов с [запуском жизненного цикла](/ru/developer/api-reference/customer-journey-api/lifecycle/#endpoints), который активирует Journey и переводит его в состояние **Running** (Запущено). Запуск через API добавляет пользователей в уже запущенный Journey. См. [сравнительную таблицу](/ru/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api).
</Aside>

## Предварительные условия

- Journey находится в состоянии **Running** (Запущено).
- Journey содержит ровно одну точку входа API (элемент «Запуск через API»), и этот элемент не деактивирован.
- Имена атрибутов, которые вы отправляете, совпадают с атрибутами, настроенными в этой точке входа API.

<Aside type="caution" title="Ограничение частоты запросов">
Каждая точка входа API принимает **один запрос в минуту**. Второй запрос в течение этого периода вернет ошибку (`Enhance your calm! only one request per minute is allowed`). Объединяйте получателей в один запрос вместо отправки множества небольших.
</Aside>

## Параметры пути

| Имя | Тип | Описание |
|---|---|---|
| `id` | string | [ID Journey](/ru/developer/api-reference/api-identifiers/#journey-id) запущенного Journey. |

## Заголовки запроса

| Имя | Обязательный | Значение |
|---|---|---|
| `Content-Type` | Да | `application/json` |
| `Authorization` | Да | `Api <server_api_token>`. См. [Токен Server API](/ru/developer/api-reference/api-access-token/#server-api-token). |

## Тело запроса

Тело запроса содержит один объект `payload`. Вы должны указать **ровно один** из параметров `users`, `hwids` или `filter`, чтобы выбрать, кто войдет в Journey.

| Поле | Тип | Описание |
|---|---|---|
| `payload.users` | string[] | [User ID](/ru/developer/api-reference/api-identifiers/#user-id) для входа. Взаимоисключающий с `hwids` и `filter`. |
| `payload.hwids` | string[] | [HWID](/ru/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) для входа. Взаимоисключающий с `users` и `filter`. |
| `payload.filter` | string | Выражение на [языке сегментации (seglang)](/ru/developer/api-reference/segmentation-filters-api/segmentation-language/), выбирающее аудиторию. Взаимоисключающий с `users` и `hwids`. |
| `payload.attribute_values` | map&lt;string, string&gt; | Необязательный. Значения для кастомных атрибутов, определенных в точке входа API. Каждый ключ должен соответствовать имени настроенного атрибута. |

### Примеры запросов

##### Добавление конкретных пользователей

```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"]
    }
  }'
```
##### Добавление конкретных пользователей с атрибутами

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

##### Добавление аудитории по фильтру

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


## Ответ

<Tabs>
<TabItem label="200">

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

| Поле | Тип | Описание |
|---|---|---|
| `request_uuid` | string | Идентификатор принятого запроса на вход. Запрос обрабатывается асинхронно. |

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

Ошибки валидации возвращают HTTP `400` с описательным сообщением. Распространенные случаи:

| Сообщение | Причина |
|---|---|
| `one of users, hwids or filter must be provided` | Ни один из трех селекторов не был указан. |
| `only one of users, hwids or filter must be provided` | Было указано более одного селектора. |
| `Journey is not running` | Journey не находится в состоянии Running (Запущено). |
| `zero api start points` | В Journey нет точки входа API. |
| `there is more then one api start point` | В Journey более одной точки входа API. |
| `point is deactivated` | Точка входа API деактивирована. |
| `unknown attribute: <name>` | Ключ в `attribute_values` не настроен в точке входа API. |
| `Enhance your calm! only one request per minute is allowed` | Достигнут лимит частоты запросов (один запрос в минуту на одну точку входа). |

</TabItem>
</Tabs>

## Связанные материалы

<CardGrid>
  <LinkCard title="Жизненный цикл" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Получить статистику Journey" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Язык сегментации" href="/developer/api-reference/segmentation-filters-api/segmentation-language/" />
</CardGrid>