# Обзор Customer Journey API

Customer Journey API позволяет бэкенду программно управлять [Customer Journeys](/ru/product/customer-journey/pushwoosh-journey-overview/): создавать и редактировать определения Journey, перемещать Journey по их жизненному циклу (запуск, пауза, завершение, черновик, архивация), запускать работающий Journey из ваших собственных систем и получать статистику по каждому Journey.

Это тот же API, который использует конструктор Customer Journey, доступный через REST/JSON посредством моста gRPC-Gateway.

## Базовый URL

```
https://journey.pushwoosh.com
```

<Aside type="tip">
Если вы используете выделенный регион или частное развертывание, уточните точный базовый URL у вашего менеджера по работе с клиентами Pushwoosh.
</Aside>

## Аутентификация

Каждый запрос должен содержать заголовок `Authorization` с серверным [токеном доступа к API](/ru/developer/api-reference/api-access-token/#server-api-token) Pushwoosh:

```
Authorization: Api YOUR_API_TOKEN
```

<Aside type="note">
Токен привязан к аккаунту, которому он принадлежит. Все операции применяются к этому аккаунту. Используйте тот же токен, который вы выпускаете для других вызовов API сервер-сервер, и никогда не раскрывайте его в клиентских приложениях.
</Aside>

## Методы

### Управление Journey

- [Жизненный цикл](/ru/developer/api-reference/customer-journey-api/lifecycle/): `POST /api/v3/journeygateway/{action}`. Запуск, приостановка, завершение, перевод в черновик или архивация Journey по его UUID.
- [Создание и обновление](/ru/developer/api-reference/customer-journey-api/create-update/): `POST /api/v3/journeygateway` и `PUT /api/v3/journeygateway/{uuid}`. Создание нового определения Journey или замена существующего.

### Запуск Journey

- [Запуск через API](/ru/developer/api-reference/customer-journey-api/start-by-api/): `POST /api/journey/{id}/start/external`. Добавление пользователей в точку входа API уже запущенного Journey.

### Статистика и аудитория

- [Получение статистики Journey](/ru/developer/api-reference/customer-journey-api/statistics/): `GET /api/journey/{id}/statistics/external`. Метрики доставки и конверсии по каждой точке.
- [Удаление пользователей из Journey](/ru/developer/api-reference/customer-journey-api/drop-users/): `POST /api/journey/drop-users/external`. Удаление пользователей из всех или выбранных активных Journey.

### Справочник

- [Объект Journey](/ru/developer/api-reference/customer-journey-api/journey-object/): структура определения Journey (info, params, points, comments), возвращаемая методами жизненного цикла, создания и обновления.
- [Справочник по точкам](/ru/developer/api-reference/customer-journey-api/point-reference/): структура `point_data` для каждого типа точки: элементы входа, времени, разделения, действия и сообщений.

## Lifecycle start в сравнении со Start by API

В Customer Journey есть две операции, которые звучат похоже, но работают по-разному.

[Lifecycle start](/ru/developer/api-reference/customer-journey-api/lifecycle/#endpoints) изменяет состояние Journey (например, с Draft на **Running**).
[Start by API](/ru/developer/api-reference/customer-journey-api/start-by-api/) добавляет пользователей в уже запущенный Journey. В таблице ниже приведено их сравнение.

| | Lifecycle Start | Start by API |
|---|---|---|
| Эндпоинт | `POST /api/v3/journeygateway/start` | `POST /api/journey/{id}/start/external` |
| Что делает | Активирует Journey и переводит его в состояние **Running** | Добавляет пользователей в **точку входа API** уже запущенного Journey |
| Требуемое состояние Journey | Draft или Paused | Running (с точкой входа API) |
| Частота запуска | Один раз при смене состояния | Многократно, по мере необходимости входа пользователей |

## Формат запросов и ответов

- Тип контента: `application/json`.
- Имена полей `v3` используют `snake_case`. Значения Enum сериализуются как их строковые имена (например, `"STATUS_RUNNING"`, `"POINT_TYPE_SEND_PUSH"`).
- Методы gRPC-Gateway (`/api/v3/journeygateway/...`) возвращают [объект Journey](/ru/developer/api-reference/customer-journey-api/journey-object/) в случае успеха и стандартную оболочку ошибки gRPC-Gateway в случае неудачи: `{ "code": ..., "message": ..., "details": [...] }`.
- Устаревшие внешние методы (`/api/journey/...`) возвращают специфичное для метода тело JSON в случае успеха и `{ "success": false, "message": ... }` с HTTP `400` при ошибках валидации.

## Быстрый старт

```bash title="Запуск Journey"
curl -X POST https://journey.pushwoosh.com/api/v3/journeygateway/start \
  -H "Authorization: Api YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "11111111-2222-3333-4444-555555555555" }'
```

## Следующие шаги

<CardGrid>
  <LinkCard title="Жизненный цикл" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Создание и обновление" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Запуск через API" href="/developer/api-reference/customer-journey-api/start-by-api/" />
  <LinkCard title="Получение статистики Journey" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Удаление пользователей из Journey" href="/developer/api-reference/customer-journey-api/drop-users/" />
  <LinkCard title="Объект Journey" href="/developer/api-reference/customer-journey-api/journey-object/" />
  <LinkCard title="Справочник по точкам" href="/developer/api-reference/customer-journey-api/point-reference/" />
</CardGrid>