# Customer Journey API 概览

Customer Journey API 允许后端以编程方式管理 [Customer Journey](/zh/product/customer-journey/pushwoosh-journey-overview/)：创建和编辑 Journey 定义，在 Journey 的生命周期中移动（启动、暂停、完成、草稿、归档），从您自己的系统触发正在运行的 Journey，以及拉取每个 Journey 的统计数据。

它与 Customer Journey 构建器使用的 API 相同，通过 gRPC-Gateway 桥接在 REST/JSON 上公开。

## 基础 URL

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

<Aside type="tip">
如果您使用专用区域或私有部署，请与您的 Pushwoosh 客户成功经理确认确切的基础 URL。
</Aside>

## 身份验证

每个请求都必须包含一个 `Authorization` 标头，其中包含一个服务器端的 Pushwoosh [API 访问令牌](/zh/developer/api-reference/api-access-token/#server-api-token)：

```
Authorization: Api YOUR_API_TOKEN
```

<Aside type="note">
该令牌绑定到拥有它的账户。所有操作都适用于该账户。请使用您为其他服务器到服务器 API 调用颁发的相同令牌，切勿在客户端应用程序中暴露它。
</Aside>

## 方法

### 管理 Journey

- [生命周期](/zh/developer/api-reference/customer-journey-api/lifecycle/)：`POST /api/v3/journeygateway/{action}`。通过 Journey 的 UUID 启动、暂停、完成、草稿或归档一个 Journey。
- [创建和更新](/zh/developer/api-reference/customer-journey-api/create-update/)：`POST /api/v3/journeygateway` 和 `PUT /api/v3/journeygateway/{uuid}`。创建一个新的 Journey 定义或替换一个现有的定义。

### 触发 Journey

- [通过 API 启动](/zh/developer/api-reference/customer-journey-api/start-by-api/)：`POST /api/journey/{id}/start/external`。将用户注入到一个已在运行的 Journey 的 API 入口点。

### 统计数据和受众

- [获取 Journey 统计数据](/zh/developer/api-reference/customer-journey-api/statistics/)：`GET /api/journey/{id}/statistics/external`。每个点的投放和转化指标。
- [从 Journey 中移除用户](/zh/developer/api-reference/customer-journey-api/drop-users/)：`POST /api/journey/drop-users/external`。从所有或选定的活动 Journey 中移除用户。

### 参考

- [Journey 对象](/zh/developer/api-reference/customer-journey-api/journey-object/)：由生命周期、创建和更新方法返回的 Journey 定义的结构（信息、参数、点、注释）。
- [点参考](/zh/developer/api-reference/customer-journey-api/point-reference/)：每种点类型的 `point_data` 结构：入口、计时、拆分、操作和消息元素。

## 生命周期启动 vs API 启动

Customer Journey 有两个操作听起来相似，但行为不同。

[生命周期启动](/zh/developer/api-reference/customer-journey-api/lifecycle/#endpoints) 会更改 Journey 状态（例如，从“草稿”变为**运行中**）。
[通过 API 启动](/zh/developer/api-reference/customer-journey-api/start-by-api/) 会将用户注入到一个已在运行的 Journey 中。下表对它们进行了并排比较。

| | 生命周期启动 | 通过 API 启动 |
|---|---|---|
| 端点 | `POST /api/v3/journeygateway/start` | `POST /api/journey/{id}/start/external` |
| 作用 | 激活 Journey 并将其移至**运行中**状态 | 将用户注入到一个已在运行的 Journey 的**API 入口点** |
| 要求的 Journey 状态 | 草稿或暂停 | 运行中（带有 API 启动点） |
| 运行频率 | 每次状态更改运行一次 | 重复运行，根据用户进入的需求 |

## 请求和响应格式

- 内容类型：`application/json`。
- `v3` 字段名称使用 `snake_case`（蛇形命名法）。枚举值序列化为其字符串名称（例如，`"STATUS_RUNNING"`、`"POINT_TYPE_SEND_PUSH"`）。
- gRPC-Gateway 方法 (`/api/v3/journeygateway/...`) 在成功时返回 [Journey 对象](/zh/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>