# Journey 객체

[라이프사이클](/ko/developer/api-reference/customer-journey-api/lifecycle/), [생성 및 업데이트](/ko/developer/api-reference/customer-journey-api/create-update/) 메서드는 모두 동일한 최상위 구조를 가진 Journey 객체를 반환합니다:

```json title="구조"
{
  "info": { ... },        // 읽기 전용 메타데이터 (응답에만 해당)
  "params": { ... },      // Journey 전체 구성 (생성 / 업데이트)
  "points": [ ... ],      // 캔버스 노드 및 연결
  "comments": [ ... ]     // 캔버스 주석
}
```

Journey를 **생성**하거나 **업데이트**할 때 `title`, `params`, `points`, `comments`를 보냅니다. 응답은 `info`( `params` 포함)와 `points`, `comments`를 반환합니다.

## Info

읽기 전용 Journey 메타데이터입니다. 모든 v3 메서드에서 반환됩니다. 요청 본문의 일부가 아닙니다.

| 필드 | 유형 | 설명 |
|---|---|---|
| `uuid` | string | [Journey ID](/ko/developer/api-reference/api-identifiers/#journey-id). |
| `title` | string | Journey 이름입니다. |
| `status` | [`JourneyStatus`](#journeystatus-enum) | 현재 상태입니다. |
| `created_at` | string | 생성 타임스탬프 (ISO 8601)입니다. |
| `updated_at` | string | 마지막 업데이트 타임스탬프 (ISO 8601)입니다. |
| `is_first_activated` | bool | Journey가 한 번 이상 시작되었는지 여부입니다. |
| `params` | [`JourneyParams`](#journeyparams) | Journey 전체 구성입니다. |
| `category_uuid` | string | 카테고리의 UUID이며, 분류되지 않은 경우 비어 있습니다. |
| `pointCounts` | map<string, uint32> | 유형별 포인트 수입니다. |
| `campaign_type` | [`CampaignType`](#campaigntype-enum) | 사용자가 Journey에 진입하는 방법입니다. |
| `stop_reason` | string | 해당하는 경우 Journey가 중지된 이유입니다. |
| `last_edited_by` | `User` | Journey를 마지막으로 편집한 사용자입니다. |
| `dynamic_entry` | bool | 동적 진입이 활성화되었는지 여부입니다. |

## JourneyParams

Journey 전체 구성입니다. 생성/업데이트 시 전송되며 `info.params` 내부에 반환됩니다.

| 필드 | 유형 | 설명 |
|---|---|---|
| `application_code` | string | Journey가 속한 [애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code)입니다. 생성 시 필수입니다. |
| `silent_hours` | [`SilentHours`](#silenthours) | 채널별로 메시지 전송이 억제되는 시간입니다. |
| `capping` | [`EntryCapping`](#entrycapping) | 사용자가 Journey에 다시 진입할 수 있는 빈도에 대한 제한입니다. |
| `conversion_window` | [`ConversionWindow`](#conversionwindow) | 목표 전환을 기여로 인정하는 기간입니다. |
| `user_id_track_change_policy` | [`UserIDTrackChangePolicy`](#useridtrackchangepolicy-enum) | Journey 진행 중에 사용자 ID가 변경될 경우 처리하는 방법입니다. |

### SilentHours

조용한 시간 동안 전송을 억제합니다. **채널별**로 구성되며, 각 채널은 자체 `SilentHoursParams`를 가집니다:

| 필드 | 유형 | 설명 |
|---|---|---|
| `push_params` | `SilentHoursParams` | 푸시 알림의 자동 방해 금지 시간입니다. |
| `inapp_params` | `SilentHoursParams` | 인앱 메시지의 자동 방해 금지 시간입니다. |
| `email_params` | `SilentHoursParams` | 이메일의 자동 방해 금지 시간입니다. |
| `sms_params` | `SilentHoursParams` | SMS의 자동 방해 금지 시간입니다. |
| `whatsapp_params` | `SilentHoursParams` | WhatsApp의 자동 방해 금지 시간입니다. |
| `line_params` | `SilentHoursParams` | LINE의 자동 방해 금지 시간입니다. |

각 `SilentHoursParams`는 다음과 같습니다:

| 필드 | 유형 | 설명 |
|---|---|---|
| `enabled` | bool | 이 채널에 자동 방해 금지 시간이 적용되는지 여부입니다. |
| `from_time` | `Time` | 조용한 시간대의 시작: `{ "hour": 0–23, "minute": 0–59 }`. |
| `to_time` | `Time` | 조용한 시간대의 종료입니다. |
| `week_days` | bool[] | 시간대가 적용되는 요일에 대한 7개의 부울 값 (월요일 = 인덱스 0). |
| `behavior` | enum | 메시지가 자동 방해 금지 시간 내에 해당될 때 수행할 작업: `WaitAndSend` (보류 후 시간대 종료 시 전송), `DropAndGo` (메시지를 건너뛰고 즉시 Journey 계속), 또는 `WaitAndDrop` (시간대 종료까지 대기 후 전송하지 않고 계속). |

### EntryCapping

동일한 사용자가 Journey에 진입할 수 있는 빈도를 제한합니다.

| 필드 | 유형 | 설명 |
|---|---|---|
| `is_enabled` | bool | 진입 제한이 켜져 있는지 여부입니다. |
| `period` | uint64 | 사용자의 진입 간 최소 초 수입니다. |

### ConversionWindow

| 필드 | 유형 | 설명 |
|---|---|---|
| `seconds` | uint64 | 사용자가 Journey에 진입한 후 목표 완료가 전환으로 계산되는 기간(초)입니다. |

## Point

포인트는 Journey 캔버스의 노드입니다: 진입점, 메시지, 지연, 분할기 등이 있습니다.

| 필드 | 유형 | 설명 |
|---|---|---|
| `uuid` | string | Journey 내에서 포인트의 고유 ID입니다. 표준 [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122) UUID여야 합니다: 8-4-4-4-12 그룹의 32개 16진수 숫자. |
| `title` | string | 포인트의 표시 이름입니다. |
| `point_type` | [`PointType`](#pointtype-enum) | 노드의 종류입니다. |
| `outputs` | array of [`PointOutput`](#pointoutput) | 하위 포인트로의 연결입니다. |
| `position` | [`Position`](#position) | 캔버스 좌표입니다. |
| `point_data` | object | `point_type`과 일치하는 정확히 하나의 중첩된 키 ([포인트 유형](#point-types-and-point_data) 표 참조). |

<Aside type="note">
모든 UUID (`info.uuid`, 모든 포인트 `uuid`, 각 출력의 `next_point_uuid`)는 표준 RFC 4122 UUID (8-4-4-4-12 16진수 그룹)여야 합니다.
</Aside>

### PointOutput

포인트의 출력은 나가는 분기입니다. 키는 **자유 형식이 아닙니다**. 유효성 검사기는 각 포인트 유형에 대해 정확한 키 세트를 예상하며, 포인트의 출력 수가 잘못되었거나 인식할 수 없는 키를 가진 Journey를 거부합니다.

| 필드 | 유형 | 설명 |
|---|---|---|
| `identity.key` | string | 분기 키입니다. 아래의 [출력 키 규칙](#output-keys)을 따라야 합니다. |
| `identity.order` | int | 분기의 표시 순서입니다. |
| `info.title` | string | 선택적 분기 레이블입니다. |
| `info.next_point_uuid` | string | 이 분기가 연결되는 다음 포인트의 UUID입니다. |

#### 출력 키

기본(첫 번째) 분기는 항상 `"default"`로 이름이 지정됩니다. 추가 분기는 `"output1"`, `"output2"` 등으로 이름이 지정됩니다 (`output` 접두사 뒤에 1부터 시작하는 인덱스가 붙습니다). 두 가지 포인트 유형은 아래에 명시된 대로 이 규칙을 따르지 않습니다.

| 포인트 유형 | 예상 출력 키 |
|---|---|
| 진입점 (`START_BY_SEGMENT`, `START_BY_API`, `EVENT`), `INAPP`, `SET_TAGS`, `WEBHOOK`, `AUDIENCE_SYNC`, 및 분할기가 없는 메시지 포인트 (`SEND_PUSH`, `SEND_EMAIL`, `SEND_SMS`, `SEND_WHATSAPP`, `SEND_LINE`, `SEND_KAKAO`, `SEND_TELEGRAM`, `SEND_DATA`) | `default` |
| `GOAL_EVENT`, `EXIT` | 없음 (출력 없음) |
| `FILTER` | `default`, `output1` |
| `BOOLEAN_SPLITTER` | `default`, 그 다음 `output1` … `outputN` (조건당 하나의 추가 분기. 간단한 예/아니요 분할은 `default` + `output1`입니다) |
| `WAIT` (지연) | `default`. 분기 분할이 있는 동적 지연은 `output1`을 추가합니다 |
| `WAIT_EVENT` | `default`는 **이벤트가 트리거되지 않은** 분기입니다. `output1`(또는 조건 스크립트가 있는 경우 조건당 하나의 분기)은 트리거된 경로입니다 |
| `SEND_PUSH` (분할기 포함) | `default`, `output1` (메시지 및 전송 분할기가 모두 켜져 있을 때는 `output2`도 포함) |
| `SEND_EMAIL` / `SEND_SMS` / `SEND_LINE` / `SEND_WHATSAPP` (분할기 포함) | `default`, `output1` |
| `SEND_WHATSAPP` (빠른 답장 프리셋 포함) | `default`, 그리고 빠른 답장당 하나의 분기. 키는 빠른 답장 값 자체입니다 |
| `AB_SPLITTER` | `output0`, `output1`, `output2`, … (변형당 하나. **`default` 분기는 없습니다**) |

### Position

| 필드 | 유형 | 설명 |
|---|---|---|
| `x` | float | 캔버스의 수평 좌표입니다. |
| `y` | float | 캔버스의 수직 좌표입니다. |

## 포인트 유형 및 point_data

`point_data`는 다음 중 하나입니다: 포인트의 `point_type`에 의해 결정되는 키를 가진 정확히 하나의 중첩된 객체를 전달합니다.

| `point_type` | `point_data` 키 | 목적 |
|---|---|---|
| `POINT_TYPE_START_BY_SEGMENT` | `start_by_segment` | 진입: 세그먼트와 일치하는 사용자. |
| `POINT_TYPE_EVENT` | `message_bus` | 진입: 이벤트를 트리거하는 사용자. |
| `POINT_TYPE_START_BY_API` | `start_by_api` | 진입: [Start by API](/ko/developer/api-reference/customer-journey-api/start-by-api/) 호출을 통해 주입된 사용자. |
| `POINT_TYPE_WAIT` | `delay` | 고정 또는 동적 간격 동안 대기합니다. |
| `POINT_TYPE_WAIT_EVENT` | `wait_event` | 이벤트가 발생할 때까지 대기합니다. |
| `POINT_TYPE_SEND_PUSH` | `send_push` | 푸시 알림을 보냅니다. |
| `POINT_TYPE_SEND_EMAIL` | `send_email` | 이메일을 보냅니다. |
| `POINT_TYPE_SEND_SMS` | `send_sms` | SMS를 보냅니다. |
| `POINT_TYPE_SEND_WHATSAPP` | `send_whatsapp` | WhatsApp 메시지를 보냅니다. |
| `POINT_TYPE_SEND_TELEGRAM` | `send_telegram` | Telegram 메시지를 보냅니다. |
| `POINT_TYPE_SEND_KAKAO` | `send_kakao` | 카카오 메시지를 보냅니다. |
| `POINT_TYPE_SEND_LINE` | `send_line` | LINE 메시지를 보냅니다. |
| `POINT_TYPE_SEND_DATA` | `send_data` | 자동 데이터 메시지를 보냅니다. |
| `POINT_TYPE_INAPP` | `inapp` | 인앱 메시지를 표시합니다. |
| `POINT_TYPE_BOOLEAN_SPLITTER` | `boolean_splitter` | 조건(세그먼트, 태그 또는 이벤트)에 따라 사용자를 분할합니다. |
| `POINT_TYPE_AB_SPLITTER` | `ab_splitter` | 사용자를 A/B 그룹으로 분할합니다. |
| `POINT_TYPE_FILTER` | `filter` | 필터와 일치하는 사용자만 계속하도록 허용합니다. |
| `POINT_TYPE_SET_TAGS` | `set_tags` | 사용자 태그를 업데이트합니다. |
| `POINT_TYPE_WEBHOOK` | `web_hook` | 아웃바운드 HTTP 요청을 보냅니다. |
| `POINT_TYPE_GOAL_EVENT` | `goal_event` | 전환 목표를 추적합니다. |
| `POINT_TYPE_AUDIENCE_SYNC` | `audience_sync` | 사용자를 외부 잠재고객과 동기화합니다. |
| `POINT_TYPE_EXIT` | `terminator` | Journey를 종료합니다. |

<Aside type="note">
유형별 `point_data` 페이로드는 [포인트 참조](/ko/developer/api-reference/customer-journey-api/point-reference/)에 문서화되어 있습니다. 진입, 타이밍, 분할 및 작업 포인트는 여기에서 전체적으로 다룹니다. 메시징 포인트는 관련 채널 문서에 대한 링크와 함께 엔벨로프 수준에서 다룹니다.
</Aside>

### 예시 포인트

단일 하위 연결이 있는 "태그 설정" 포인트:

```json
{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Tag as engaged",
  "point_type": "POINT_TYPE_SET_TAGS",
  "position": { "x": 480, "y": 120 },
  "outputs": [
    {
      "identity": { "key": "default", "order": 0 },
      "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" }
    }
  ],
  "point_data": {
    "set_tags": {
      "application_code": "XXXXX-XXXXX",
      "tags": [ { "name": "engaged", "value": "true" } ]
    }
  }
}
```

## JourneyComment

| 필드 | 유형 | 설명 |
|---|---|---|
| `id` | string | 주석 UUID입니다. |
| `message` | string | 주석 텍스트입니다. |
| `position` | [`Position`](#position) | 캔버스 좌표입니다. |
| `index` | int | 표시 순서입니다. |
| `created_at` | string | 생성 타임스탬프 (ISO 8601)입니다. |
| `deleted` | bool | 주석이 삭제되었는지 여부입니다. |

## Enums

### JourneyStatus enum

`STATUS_DRAFT`, `STATUS_RUNNING`, `STATUS_FINISHED`, `STATUS_ARCHIVED`, `STATUS_PAUSED`, `STATUS_UNKNOWN`.

### CampaignType enum

- `TriggerBased`: 사용자가 이벤트에 따라 진입합니다.
- `AudienceBased`: 사용자가 세그먼트에서 진입합니다.
- `APIBased`: 사용자가 Start by API 호출을 통해 진입합니다.
- `Mixed`: 둘 이상의 진입 유형이 있습니다.
- `Unknown`: 진입 유형이 결정되지 않았습니다.

### PointType enum

전체 목록과 각 `point_data` 키가 매핑되는 내용은 위의 [포인트 유형](#point-types-and-point_data) 표를 참조하십시오.

### UserIDTrackChangePolicy enum

Journey 진행 중에 [사용자 ID](/ko/developer/api-reference/api-identifiers/#user-id)가 변경될 때 사용자에게 발생하는 일을 제어합니다:

- `DEFAULT`: 기본 동작입니다.
- `TRACK`: 새 ID로 사용자를 계속 추적합니다.
- `DROP`: ID가 변경되면 Journey에서 사용자를 제거합니다.

## 관련

<CardGrid>
  <LinkCard title="포인트 참조" href="/developer/api-reference/customer-journey-api/point-reference/" />
  <LinkCard title="생성 및 업데이트" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="라이프사이클" href="/developer/api-reference/customer-journey-api/lifecycle/" />
</CardGrid>