---
title: 프로세스 생성
description: POST /v1/processes — 공통 필드, 검증 제한, 플로우 필드, 그리고 Human Token과 인텔리전스가 담긴 201 응답을 설명합니다.
canonical: https://developer.unico.io/ko/human-plugin/api-reference/create-process
locale: ko
generated_by: markdown-export
---

# 프로세스 생성

프로세스를 시작하고 Human Token과 해당 사용자의 인텔리전스를 받습니다.

`POST /v1/processes`

[플로우](#flows) 중 하나로 프로세스를 시작하고, `id`, `state`, 그리고 `data`에 담긴 결과(Human Token과 해당 사용자의 [인텔리전스](/ko/human-plugin/get-started/intelligence), `data.ndocs`)로 응답합니다.

## 호출 전 확인 사항

- Human Plugin이 실행 중이고 `GET /health/ready`가 `200`으로 응답합니다.
- 액세스 키가 사용하려는 [플로우](#flows)에 대해 활성화되어 있습니다.
- 문서를 보내는 경우, 해당 `type`이 [속성 카탈로그](/ko/human-plugin/additional-resources/attribute-catalog)에 있습니다.

<a id="flows"></a>

## 플로우

`flow` 필드는 프로세스가 수행할 작업을 선택합니다. Human Plugin은 두 가지 통합 모델로 다음 플로우를 실행합니다.

- **API Only**: 백엔드가 `imageBase64`로 셀피를 보내고, 생성 요청이 결과를 응답합니다.
- **Human Token Journey**: 사용자가 캡처 저니에서 셀피를 촬영한 뒤 `callbackUri`로 돌아옵니다. 생성 요청은 `token`과 `link`로 응답하며, 결과는 [프로세스 조회](/ko/human-plugin/api-reference/get-process)로 읽습니다.

| Flow | Description | Possible result | Integration components required |
| --- | --- | --- | --- |
| `api+humantoken` | 백엔드를 통해 셀피를 받아 고유한 얼굴 식별자인 Human Token을 생성합니다. 응답이 최종 결과이며, 캡처도 두 번째 호출도 없습니다. | `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API |
| `humantoken` | 캡처 저니에서 라이브니스 확인과 함께 셀피를 캡처하고 Human Token을 생성합니다. 생성 요청은 `token`과 `link`를 반환하며, 캡처가 끝나면 결과를 읽습니다. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |
| `humantoken+revalidation` | 셀피를 캡처하여 기대하는 Human Token과 얼굴을 비교합니다. 예를 들어 민감한 작업 전에 동일인인지 여부를 반환합니다. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |

`clientId`, `correlationId`, `credential`은 모든 플로우에서 동일합니다.

## 요청

```json
{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}
```

### 공통 필드

| 필드 | 필수 | 제한(바이트) | 비고 |
| --- | --- | --- | --- |
| `flow` | 예 | 64 | [플로우](#flows) 중 하나 |
| `clientId` | 예 | 128 | 고객에 대한 사용자의 id. 인텔리전스는 서로 다른 값의 개수를 셉니다 |
| `correlationId` | 예 | 128 | 이 프로세스에 대한 사용자의 참조값. **고유해야 함**: 상태와 관계없이 다른 프로세스가 이미 가진 값은 `409`로 거부됩니다 |
| `credential` | 예(비어 있어도 됨) | | 키는 반드시 있어야 합니다. 아래를 참고하세요 |
| `credential.type` | 문서와 함께 | | 속성 카탈로그의 코드. 정확히, 대소문자를 구분하여 일치해야 합니다 |
| `credential.value` | 문서와 함께 | 64 | 문서 번호 |

`flow`, `clientId`, `correlationId`는 제어 문자와 앞뒤 공백이 없는 문자열이어야 합니다. 유효하지 않은 값은 거부되며, 임의로 수정되지 않습니다.

### `credential` 필드

- **문서가 있는 경우:** 정확히 `type`과 `value`만 가진 객체로, 둘 다 문자열이며 함께 보내야 합니다.
- **문서가 없는 경우:** `null` 또는 `{}`. 이 경우에도 프로세스는 인텔리전스에서 하나의 트랜잭션이자 하나의 고객으로 집계됩니다.
- **생략했거나 빈 문자열로 된 객체:** `400 MISSING_CREDENTIAL_TYPE`으로 거부됩니다. 이를 통해 아무것도 처리되기 전에 키 철자 오류를 잡아냅니다.
- `credential` 안의 다른 키는 모두 거부됩니다.

### 플로우 필드

각 플로우가 공통 필드에 추가하는 항목:

| 필드 | 플로우 | 필수 | 값 |
| --- | --- | --- | --- |
| `imageBase64` | `api+humantoken` | 예 | base64로 인코딩한 셀피. PNG, JPEG 또는 WebP, 최대 800 KB |
| `callbackUri` | `humantoken`, `humantoken+revalidation` | 예 | 캡처가 끝나면 사용자가 돌아오는 위치: 사용자의 페이지 또는 앱의 URL 스킴 |
| `references` | `humantoken+revalidation` | 예 | 위 예시처럼 기대하는 Human Token이 담긴 항목 하나 |

Human Plugin은 이 필드를 저장하지 않으며, 철자가 틀린 선택 필드는 오류 없이 무시될 수 있습니다.

`api+humantoken`에는 한 사람의 얼굴이 정면으로, 밝은 조명에서 찍힌 셀피를 사용하세요. 이미지가 아닌 값은 거부되며 프로세스는 실패로 저장됩니다. [플로우 거부 사유](#flow-refusals)를 참고하세요.

`humantoken+revalidation`에서는 결과에 `humanToken` 대신 `humanTokenMatch`가 포함됩니다.

- `"true"`: 동일인입니다. 프로세스는 해당 사용자의 것으로 집계되며, `ndocs`가 그 사용자를 설명합니다.
- 그 외의 값이거나 라이브가 아닌 캡처: 확인되지 않았습니다. 프로세스는 누구의 것으로도 집계되지 않으며 `ndocs`도 없습니다.

두 경우 모두 `PROCESS_STATE_FINISHED`로 응답하므로 `humanTokenMatch`를 확인하세요. [프로세스 조회](/ko/human-plugin/api-reference/get-process#finished-and-failed-processes)를 참고하세요.

일부 이름(예: `clientReference`)은 Human Plugin이 예약해 두었으며 `400 INVALID_REQUEST`로 거부됩니다. `client_id`, `correlation_id`, `Flow`처럼 Human Plugin 자체 필드의 다른 표기도 마찬가지입니다. `flow`, `clientId`, `correlationId`, `credential`만, 정확히 그 철자대로 읽습니다.

### 본문 규칙

- JSON 객체 하나, 최대 **2 MiB**(base64 셀피 한 장이 들어갈 정도)입니다. 이보다 큰 본문은 `400 REQUEST_TOO_LARGE`로 거부됩니다.
- JSON 객체 뒤에 다른 내용이 올 수 없습니다.

## 응답

`201 Created`이며 `Location: /v1/processes/<id>` 헤더가 포함됩니다.

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}
```

- `id`는 Human Plugin의 UUID입니다. 수락된 요청마다 새 값이 생성됩니다.
- `state`는 로컬 상태입니다. [수명 주기](/ko/human-plugin/api-reference/process-lifecycle)를 참고하세요.
- `humantoken`과 `humantoken+revalidation`은 `token` 및 `link`와 함께 `PROCESS_STATE_CREATED`로 응답합니다. 이 값은 **한 번만** 반환되고 저장되지 않으므로 직접 보관하세요. [Human Token Journey](/ko/human-plugin/integrations/human-token-journey)와 사용하는 플랫폼의 캡처 가이드를 참고하세요.
- `data.ndocs`는 해당 사용자의 인텔리전스입니다. 없을 수도 있습니다. [인텔리전스](/ko/human-plugin/get-started/intelligence)를 참고하세요.

<a id="result"></a>

### `data`의 결과

완료된 프로세스는 `data`에 다음 필드를 가집니다. Journey 플로우는 캡처 후 [프로세스를 조회](/ko/human-plugin/api-reference/get-process)할 때 이 필드를 반환합니다.

| 필드 | 조건 | 값 |
| --- | --- | --- |
| `humanToken` | `api+humantoken`, `humantoken` | 사용자가 누구인지를 나타냅니다. `value`는 Human Token이며, 생성된 경우 `status`는 `validated`입니다 |
| `humanTokenMatch` | `humantoken+revalidation` | `references`의 Human Token과 동일인이면 `"true"` |
| `liveness` | Journey 플로우처럼 라이브니스를 확인하는 플로우 | 캡처가 실제 사람에게서 나왔으면 `value`는 `live`, 아니면 `not_live`입니다. 확인이 수행되었으면 `status`는 `validated`입니다 |
| `ndocs` | 해당 사용자에 대한 인텔리전스가 있는 경우 | 해당 사용자의 [인텔리전스](/ko/human-plugin/get-started/intelligence) |

Journey 결과는 다음과 같습니다.

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}
```

결과를 신뢰하기 전에 `liveness`를 확인하세요. `not_live`이면 캡처가 실패한 것으로 처리하고 사용자에게 다시 시도하도록 안내하세요. `not_live`인 프로세스는 누구의 인텔리전스에도 집계되지 않습니다.

## 오류

| 상태 | `message` | 의미 |
| --- | --- | --- |
| 400 | `INVALID_REQUEST`, `REQUEST_TOO_LARGE` | JSON 객체 하나가 아니거나, 예약된 필드이거나, 잘못된 타입이거나, 본문이 2 MiB를 초과함 |
| 400 | `MISSING_<FIELD>`, `INVALID_<FIELD>` | 필수 필드가 없거나 형식이 잘못됨(예: `MISSING_CLIENT_ID`) |
| 401 | 비어 있음(`""`) | Unico가 액세스 키를 거부했습니다: 누락, 오류 또는 더 이상 유효하지 않음. 프로세스는 실패로 저장됩니다. `HUMAN_API_ACCESS_KEY`를 확인하세요 |
| 409 | `CORRELATION_ID_ALREADY_USED` | 다른 프로세스가 이미 해당 `correlationId`를 사용 중입니다. 저장되거나 전송되는 것은 없습니다 |
| 422 | `ATTRIBUTE_TYPE_NOT_SUPPORTED` | `credential.type`이 카탈로그에 없습니다. 저장되거나 전송되는 것은 없습니다 |
| 4xx | 플로우의 `message` | 플로우가 요청을 거부했습니다(예: 잘못된 이미지). [플로우 거부 사유](#flow-refusals)를 참고하세요 |
| 502 | `UPSTREAM_UNAVAILABLE` | 시간 내에 프로세스를 확인하지 못했습니다 |
| 503 | `DATABASE_UNAVAILABLE` | 데이터베이스 오류입니다. 처리된 것은 없습니다 |
| 500 | `INTERNAL` | 예기치 않은 오류 |

<a id="flow-refusals"></a>

### 플로우 거부 사유

플로우가 요청을 거부하면, 생성 요청은 일반적인 [엔벨로프](/ko/human-plugin/api-reference/errors-and-retries)에 사유를 `message`로 담아 `4xx`로 응답합니다. 가장 흔한 사유:

| `message` | 원인 |
| --- | --- |
| `invalid flow` | `flow`가 계정에서 활성화된 플로우가 아님 |
| `INVALID_IMAGE` (`400`) | `imageBase64` 없이 `api+humantoken`을 호출함 |
| `INVALID_REQUEST` (`400`) | `imageBase64`가 base64 이미지가 아님 |
| `IMAGE_TOO_LARGE` | 이미지가 800 KB를 초과함 |
| `UNSUPPORTED_IMAGE_FORMAT` | 이미지가 PNG, JPEG 또는 WebP가 아님 |
| `PERMISSION_DENIED` (`403`) | 액세스 키가 이 플로우에 대해 활성화되어 있지 않음 |

거부된 프로세스는 실패로 저장됩니다. 요청을 수정하고 새 `correlationId`로 새 프로세스를 생성하세요.

재시도 로직을 추가하기 전에 [오류 및 재시도](/ko/human-plugin/api-reference/errors-and-retries)를 읽어 보세요. 새 시도에는 새 `correlationId`가 필요합니다.

## 다음 단계

[프로세스 조회](/ko/human-plugin/api-reference/get-process)