# API로 시작

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

Journey의 **API 진입점**으로 사용자 집합을 진입시킵니다. 자체 백엔드에서 Journey를 구동하는 데 사용하세요. 예를 들어, 사용자가 서버에서 가입을 완료했을 때 온보딩 플로우를 시작할 수 있습니다.

<Aside type="tip">
이 호출을 Journey를 활성화하고 **실행 중** 상태로 전환하는 [Lifecycle 시작](/ko/developer/api-reference/customer-journey-api/lifecycle/#endpoints)과 혼동하지 마십시오. API로 시작은 이미 실행 중인 Journey에 사용자를 주입합니다. [비교표](/ko/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api)를 참조하세요.
</Aside>

## 전제 조건

- Journey가 **실행 중** 상태입니다.
- Journey에 API 진입점("API로 시작" 요소)이 정확히 하나 포함되어 있으며, 해당 요소는 비활성화되어 있지 않습니다.
- 전송하는 속성 이름이 해당 API 진입점에 구성된 속성과 일치합니다.

<Aside type="caution" title="속도 제한">
각 API 진입점은 **분당 하나의 요청**만 허용합니다. 해당 시간 내에 두 번째 요청이 들어오면 오류(`Enhance your calm! only one request per minute is allowed`)를 반환합니다. 수신자를 여러 개의 작은 요청으로 보내는 대신 단일 요청으로 일괄 처리하세요.
</Aside>

## 경로 매개변수

| 이름 | 유형 | 설명 |
|---|---|---|
| `id` | string | 실행 중인 Journey의 [Journey ID](/ko/developer/api-reference/api-identifiers/#journey-id)입니다. |

## 요청 헤더

| 이름 | 필수 | 값 |
|---|---|---|
| `Content-Type` | 예 | `application/json` |
| `Authorization` | 예 | `Api <server_api_token>`. [서버 API 토큰](/ko/developer/api-reference/api-access-token/#server-api-token)을 참조하세요. |

## 요청 본문

본문에는 단일 `payload` 객체가 있습니다. Journey에 진입할 대상을 선택하려면 `users`, `hwids` 또는 `filter` 중 **정확히 하나**를 제공해야 합니다.

| 필드 | 유형 | 설명 |
|---|---|---|
| `payload.users` | string[] | 진입할 [User ID](/ko/developer/api-reference/api-identifiers/#user-id)입니다. `hwids` 및 `filter`와 상호 배타적입니다. |
| `payload.hwids` | string[] | 진입할 [HWID](/ko/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid)입니다. `users` 및 `filter`와 상호 배타적입니다. |
| `payload.filter` | string | 대상을 선택하는 [seglang](/ko/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가 실행 중 상태가 아닙니다. |
| `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` | 속도 제한에 도달했습니다(진입점당 분당 1회 요청). |

</TabItem>
</Tabs>

## 관련 항목

<CardGrid>
  <LinkCard title="Lifecycle" 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>