# Customer Journey API 개요

Customer Journey API를 사용하면 백엔드에서 프로그래밍 방식으로 [Customer Journeys](/ko/product/customer-journey/pushwoosh-journey-overview/)를 관리할 수 있습니다. Journey 정의 생성 및 편집, Journey의 수명 주기(시작, 일시 중지, 완료, 초안, 보관) 관리, 자체 시스템에서 실행 중인 Journey 트리거, Journey별 통계 가져오기 등이 가능합니다.

이 API는 Customer Journey 빌더가 사용하는 것과 동일하며, gRPC-Gateway 브리지를 통해 REST/JSON으로 노출됩니다.

## 기본 URL

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

<Aside type="tip">
전용 리전이나 프라이빗 배포를 사용하는 경우, Pushwoosh 고객 성공 관리자에게 정확한 기본 URL을 확인하세요.
</Aside>

## 인증

모든 요청에는 서버 측 Pushwoosh [API 액세스 토큰](/ko/developer/api-reference/api-access-token/#server-api-token)이 포함된 `Authorization` 헤더를 포함해야 합니다.

```
Authorization: Api YOUR_API_TOKEN
```

<Aside type="note">
토큰은 소유한 계정에 바인딩됩니다. 모든 작업은 해당 계정에 적용됩니다. 다른 서버 간 API 호출에 사용하는 동일한 토큰을 사용하고, 클라이언트 애플리케이션에 절대 노출하지 마세요.
</Aside>

## 메서드

### Journey 관리

- [수명 주기](/ko/developer/api-reference/customer-journey-api/lifecycle/): `POST /api/v3/journeygateway/{action}`. UUID로 Journey를 시작, 일시 중지, 완료, 초안 작성 또는 보관합니다.
- [생성 및 업데이트](/ko/developer/api-reference/customer-journey-api/create-update/): `POST /api/v3/journeygateway` 및 `PUT /api/v3/journeygateway/{uuid}`. 새로운 Journey 정의를 생성하거나 기존 정의를 교체합니다.

### Journey 트리거

- [API로 시작](/ko/developer/api-reference/customer-journey-api/start-by-api/): `POST /api/journey/{id}/start/external`. 이미 실행 중인 Journey의 API 진입점으로 사용자를 주입합니다.

### 통계 및 잠재고객

- [Journey 통계 가져오기](/ko/developer/api-reference/customer-journey-api/statistics/): `GET /api/journey/{id}/statistics/external`. 포인트별 전달 및 전환 메트릭입니다.
- [Journey에서 사용자 제거](/ko/developer/api-reference/customer-journey-api/drop-users/): `POST /api/journey/drop-users/external`. 모든 또는 선택된 활성 Journey에서 사용자를 제외합니다.

### 참조

- [Journey 객체](/ko/developer/api-reference/customer-journey-api/journey-object/): 수명 주기, 생성 및 업데이트 메서드에서 반환되는 Journey 정의의 형태(정보, 매개변수, 포인트, 주석)입니다.
- [포인트 참조](/ko/developer/api-reference/customer-journey-api/point-reference/): 각 포인트 유형(진입, 타이밍, 분기, 액션 및 메시징 요소)에 대한 `point_data` 구조입니다.

## 수명 주기 시작과 API로 시작 비교

Customer Journey에는 비슷하게 들리지만 다르게 작동하는 두 가지 작업이 있습니다.

[수명 주기 시작](/ko/developer/api-reference/customer-journey-api/lifecycle/#endpoints)은 Journey 상태를 변경합니다(예: 초안에서 **실행 중**으로).
[API로 시작](/ko/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 객체](/ko/developer/api-reference/customer-journey-api/journey-object/)를 반환하고, 실패 시 표준 gRPC-Gateway 오류 봉투를 반환합니다: `{ "code": ..., "message": ..., "details": [...] }`.
- 레거시 외부 메서드(`/api/journey/...`)는 성공 시 메서드별 JSON 본문을 반환하고, 유효성 검사 오류 시 HTTP `400`과 함께 `{ "success": false, "message": ... }`를 반환합니다.

## 빠른 시작

```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>