--- title: 프로세스 생성 description: Human API에서 Human Token 프로세스를 생성합니다 — 셀피를 전송하거나(API Only) Human Token Journey를 시작하고, data.humanToken에서 humanToken을 받습니다. canonical: https://developer.unico.io/ko/human-token/api-reference/post-processes locale: ko generated_by: markdown-export --- - [/ko/](/ko/) - API 레퍼런스 - 프로세스 생성 **이 페이지에서프로세스 생성POST백엔드에서 Human Token 프로세스를 생성하고 data.humanToken에서 humanToken을 받습니다. Human Token은 Human API의 `POST /client/v1/process` 엔드포인트에서 실행됩니다. API Only 플로우(`api+humantoken`, `api+liveness+humantoken`, `api+liveness+humantoken+revalidation`)에서는 프로세스가 단일 호출로 생성되고 완료됩니다. 응답에 이미 `data.humanToken` 결과가 포함되어 있습니다. Human Token Journey 플로우(`humantoken` 및 `humantoken+revalidation`)에서는 응답에 프로세스 `id`, `token`, 여정 `link`가 포함되며, 사용자가 여정을 완료한 후 결과를 확인할 수 있습니다. `+revalidation` 플로우는 재검증을 위해 이전에 획득한 `humanToken`이 포함된 `references` 배열이 필요합니다. ### 플로우​ Human Token은 두 가지 통합 모델로 실행됩니다: **API Only** — 백엔드가 `imageBase64`로 셀피를 전송합니다. **Human Token Journey** — 사용자가 웹에서 Unico 여정을 진행한 후 `callbackUri`로 돌아옵니다. FlowCapabilitiesPossible resultIntegration componentsrequiredExample`api+humantoken`[Human Token](/ko/human-token/)PROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDAPIView example`api+liveness+humantoken`Liveness[Human Token](/ko/human-token/)PROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDAPIView example`api+liveness+humantoken+revalidation`Liveness[Human Token](/ko/human-token/)RevalidationPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDAPIView example`humantoken`Liveness[Human Token](/ko/human-token/)PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELEDAPIWebView example`humantoken+revalidation`Liveness[Human Token](/ko/human-token/)RevalidationPROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELEDAPIWebView example ### Endpoint​ 환경URL**프로덕션**`POST https://humantoken.unico.app/client/v1/process` ### 요청​ 헤더 헤더값`x-unico-accesskey``` ([인증](/ko/human-token/get-started/authentication) 참조)`Content-Type``application/json` 본문 매개변수 필드유형필수설명`flow`string예Human Token 플로우: `api+humantoken`, `api+liveness+humantoken`, `api+liveness+humantoken+revalidation`(API Only) 또는 `humantoken`, `humantoken+revalidation`(Human Token Journey). [플로우](#flows)를 참조하세요.`imageBase64`stringAPI Only프런트엔드에서 캡처하여 직접 전송하는 base64 형식의 셀피입니다. PNG, JPEG 또는 WebP, 최대 800 KB. [캡처 스탠다드](/ko/human-token/additional-resources/capture-standard)를 따르세요.`callbackUri`stringHuman Token Journey여정이 끝난 후 사용자가 리디렉션되는 URL입니다.`companyBranchId`string아니요브랜치 식별자. 제공되면 프로세스가 지정된 브랜치의 구성을 사용합니다.`references`array재검증 플로우참조 객체의 배열입니다. `+revalidation` 플로우에 필수입니다. 각 객체는 `referenceType`(`REFERENCE_TYPE_HUMAN_TOKEN`)과 `referenceContent`(이전에 획득한 `humanToken` 값)를 포함합니다. ### 응답​ 200 OK 필드유형설명`id`string (UUID)프로세스 식별자입니다. [프로세스 조회](/ko/human-token/api-reference/get-process)로 프로세스를 다시 조회할 때 사용합니다.`state`string프로세스 상태입니다 — [결과 해석](#interpreting-the-result)을 참조하세요. API Only 플로우에서만 반환됩니다.`token`string생성된 프로세스의 토큰으로, Journey SDK 경험을 열 때 사용할 수 있습니다. Human Token Journey 흐름(`humantoken`, `humantoken+revalidation`)에서만 제공됩니다.`link`stringHuman Token Journey URL로, 사용자를 이 URL로 보냅니다. Human Token Journey 플로우(`humantoken`, `humantoken+revalidation`)에서만 반환됩니다.`data.​humanToken.​value`string얼굴의 안정적이고 불투명한 식별자입니다 (최대 100자). 동일한 사람은 항상 동일한 값으로 확인됩니다. API Only 플로우에서만 반환됩니다(재검증 제외).`data.​humanTokenMatch`string셀피가 참조된 `humanToken`과 일치하면 `"true"`, 그렇지 않으면 `"false"`입니다. `+revalidation` API Only 플로우에서만 반환됩니다. 결과 해석 `state`의미조치 방법`PROCESS_STATE_FINISHED``data.humanToken.value` 있음: Human Token이 있는 실제 사람입니다.기록에서 `value`를 검색하세요. 존재하면 재방문 사용자이거나 중복 가능성이 있으며, 존재하지 않으면 새로운 사람입니다.`PROCESS_STATE_FINISHED``data.humanToken`이 없거나 `value`가 비어 있음: 판단 불가.결과를 불확정으로 처리하세요. 빈 `value`는 절대 저장하거나 매칭하지 마세요. 비즈니스 규칙에 따라 프로세스를 재시도하거나 거부하세요.`PROCESS_STATE_FAILED`식별 프로세스가 실패했습니다.비즈니스 규칙에 따라 프로세스를 다시 시도하거나 거부하세요.`PROCESS_STATE_CREATED`프로세스가 생성되었습니다.기다리세요. 나중에 [프로세스 조회](/ko/human-token/api-reference/get-process)로 결과를 조회하세요.`PROCESS_STATE_CANCELED`프로세스가 취소되었습니다.사용자를 여전히 인증해야 하는 경우 새 프로세스를 생성하세요. 경고`data.humanToken.value`를 사용하기 전에 항상 비어 있지 않은지 확인하세요. ### 오류 코드​ 참고`x-unico-accesskey` 헤더에 액세스 키가 없거나 유효하지 않을 때 반환되는 HTTP 상태는 아직 확인 중입니다. [인증](/ko/human-token/get-started/authentication)을 참조하세요. 400 Bad Request403 Forbidden429 Too Many Requests500 Internal Server Error코드메시지설명`3`invalid flow지정된 플로우가 존재하지 않을 때.`3`INVALID_IMAGE이미지가 유효한 base64가 아니거나 인젝션 시도로 보일 때.`3`IMAGE_TOO_LARGE이미지가 최대 크기인 800 KB를 초과할 때.`3`UNSUPPORTED_IMAGE_FORMAT이미지 형식이 PNG, JPEG 또는 WebP가 아닐 때.`3`MISSING_IMAGE이 플로우에 이미지가 필요하지만 전송되지 않았을 때.`3`INVALID_REQUEST요청 본문이 null이거나 해석할 수 없을 때.`9`monthly process limit of reached for this tenant월간 사용 한도에 도달한 경우.`9`PROCESS_FAILED프로세스 생성 중 최종 실패 상태에 도달했을 때.코드메시지설명`7`PERMISSION_DENIED자격 증명은 유효하지만 이 작업에 대한 권한이 없을 때.레이트 리밋에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄적인 장애를 방지하고 제한이 악화되지 않도록 메커니즘을 구현해야 합니다. **모범 사례:** **쿨다운 기간(backoff):** 시스템에서 후속 요청을 즉시 중지하거나 줄이세요. 실패한 요청을 촘촘한 루프에서 지속적으로 재시도하지 마세요. **큐잉 및 스로틀링(Queueing & throttling):** 재전송하기 전에 발신 요청을 버퍼링하거나 대기열에 넣어 트래픽 흐름을 제어하세요. **지터를 포함한 지수 백오프(Exponential backoff with jitter):** 재시도 시 시도 간 대기 시간을 기하급수적으로 늘리고(예: 1초, 2초, 4초, 8초) 작은 무작위 지연("지터")을 추가하여 대기열의 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요. 경고백오프 없이 레이트 리밋이 적용된 엔드포인트에 지속적으로 요청을 보내면 **제한 기간이 연장되고** 시스템의 운영 처리량에 심각한 영향을 미칠 수 있습니다. 요청을 적절히 스로틀링하면 더 원활하고 탄력적인 통합이 보장됩니다. 기본 제한, 요청 증가 및 추가 세부 정보는 [레이트 리밋](/ko/developers/start/rate-limits)을 참조하세요.코드메시지설명`13`Internal failure! Try again later내부 오류가 발생했을 때. 이 엔드포인트의 전체 코드 목록은 Human API [프로세스 생성](/ko/developers/api-reference/post-processes#error-codes) 레퍼런스를 참조하세요. ### 다음 단계​ 이후 Human Token 호출에서 동일한 사람을 인식할 수 있도록 `humanToken` 값을 사용자 레코드와 함께 저장하세요. 감사 또는 지원 목적으로 프로세스를 다시 조회하려면 [프로세스 조회](/ko/human-token/api-reference/get-process)를 사용하세요. 마지막 업데이트 2026년 10월 22일**에