# 通过 API 启动
`POST` `https://journey.pushwoosh.com/api/journey/{id}/start/external`
将一组用户送入 Journey 的 **API 入口点**。可用于从您自己的后端驱动 Journey。例如，当用户在您的服务器上完成注册时，启动一个引导流程。
## 先决条件
- Journey 处于**正在运行**状态。
- Journey 包含且仅包含一个 API 入口点（“通过 API 启动”元素），且该元素未被停用。
- 您发送的属性名称与该 API 入口点上配置的属性相匹配。
## 路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
| `id` | string | 正在运行的 Journey 的 [Journey ID](/zh/developer/api-reference/api-identifiers/#journey-id)。 |
## 请求标头
| 名称 | 必需 | 值 |
|---|---|---|
| `Content-Type` | 是 | `application/json` |
| `Authorization` | 是 | `Api `。请参阅[服务器 API 令牌](/zh/developer/api-reference/api-access-token/#server-api-token)。 |
## 请求正文
正文包含一个 `payload` 对象。您必须**只提供** `users`、`hwids` 或 `filter` 中的**一个**，以选择进入 Journey 的用户。
| 字段 | 类型 | 描述 |
|---|---|---|
| `payload.users` | string[] | 要进入的 [User ID](/zh/developer/api-reference/api-identifiers/#user-id)。与 `hwids` 和 `filter` 互斥。 |
| `payload.hwids` | string[] | 要进入的 [HWID](/zh/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid)。与 `users` 和 `filter` 互斥。 |
| `payload.filter` | string | 一个选择受众的 [seglang](/zh/developer/api-reference/segmentation-filters-api/segmentation-language/) 表达式。与 `users` 和 `hwids` 互斥。 |
| `payload.attribute_values` | map<string, string> | 可选。在 API 入口点上定义的自定义属性的值。每个键必须与配置的属性名称匹配。 |
### 请求示例
##### 输入特定用户
```bash
curl -X POST 'https://journey.pushwoosh.com/api/journey//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\")"
}
}
```
## 响应
```json
{
"request_uuid": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}
```
| 字段 | 类型 | 描述 |
|---|---|---|
| `request_uuid` | string | 已接受的进入请求的标识符。该请求是异步处理的。 |
验证错误会返回 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 未处于“正在运行”状态。 |
| `zero api start points` | Journey 没有 API 入口点。 |
| `there is more then one api start point` | Journey 有多个 API 入口点。 |
| `point is deactivated` | API 入口点已被停用。 |
| `unknown attribute: ` | API 入口点上未配置 `attribute_values` 键。 |
| `Enhance your calm! only one request per minute is allowed` | 达到速率限制（每个入口点每分钟一个请求）。 |
## 相关内容