백엔드에서 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로 돌아옵니다.
| Flow | Capabilities | Possible result | Integration components required | Example |
|---|---|---|---|---|
api+humantoken | Human Token | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
api+liveness+humantoken | LivenessHuman Token | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
api+liveness+humantoken+revalidation | LivenessHuman TokenRevalidation | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
humantoken | LivenessHuman Token | PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED | APIWeb | |
humantoken+revalidation | LivenessHuman TokenRevalidation | PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED | APIWeb |
Endpoint
| 환경 | URL |
|---|---|
| 프로덕션 | POST https://humantoken.unico.app/client/v1/process |
요청
| 헤더 | 값 |
|---|---|
x-unico-accesskey | <your_access_key> (인증 참조) |
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). 플로우를 참조하세요. |
imageBase64 | string | API Only | 프런트엔드에서 캡처하여 직접 전송하는 base64 형식의 셀피입니다. PNG, JPEG 또는 WebP, 최대 800 KB. 캡처 스탠다드를 따르세요. |
callbackUri | string | Human Token Journey | 여정이 끝난 후 사용자가 리디렉션되는 URL입니다. |
companyBranchId | string | 아니요 | 브랜치 식별자. 제공되면 프로세스가 지정된 브랜치의 구성을 사용합니다. |
references | array | 재검증 플로우 | 참조 객체의 배열입니다. +revalidation 플로우에 필수입니다. 각 객체는 referenceType(REFERENCE_TYPE_HUMAN_TOKEN)과 referenceContent(이전에 획득한 humanToken 값)를 포함합니다. |
응답
| 필드 | 유형 | 설명 |
|---|---|---|
id | string (UUID) | 프로세스 식별자입니다. 프로세스 조회로 프로세스를 다시 조회할 때 사용합니다. |
state | string | 프로세스 상태입니다 — 결과 해석을 참조하세요. API Only 플로우에서만 반환됩니다. |
token | string | 생성된 프로세스의 토큰으로, Journey SDK 경험을 열 때 사용할 수 있습니다. Human Token Journey 흐름(humantoken, humantoken+revalidation)에서만 제공됩니다. |
link | string | Human 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 | 프로세스가 생성되었습니다. | 기다리세요. 나중에 프로세스 조회로 결과를 조회하세요. |
PROCESS_STATE_CANCELED | 프로세스가 취소되었습니다. | 사용자를 여전히 인증해야 하는 경우 새 프로세스를 생성하세요. |
data.humanToken.value를 사용하기 전에 항상 비어 있지 않은지 확인하세요.
오류 코드
x-unico-accesskey 헤더에 액세스 키가 없거나 유효하지 않을 때 반환되는 HTTP 상태는 아직 확인 중입니다. 인증을 참조하세요.
- 400 Bad Request
- 403 Forbidden
- 429 Too Many Requests
- 500 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 <monthly_limit> reached for this tenant | 월간 사용 한도에 도달한 경우. |
9 | PROCESS_FAILED | 프로세스 생성 중 최종 실패 상태에 도달했을 때. |
| 코드 | 메시지 | 설명 |
|---|---|---|
7 | PERMISSION_DENIED | 자격 증명은 유효하지만 이 작업에 대한 권한이 없을 때. |
레이트 리밋에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄적인 장애를 방지하고 제한이 악화되지 않도록 메커니즘을 구현해야 합니다.
모범 사례:
- 쿨다운 기간(backoff): 시스템에서 후속 요청을 즉시 중지하거나 줄이세요. 실패한 요청을 촘촘한 루프에서 지속적으로 재시도하지 마세요.
- 큐잉 및 스로틀링(Queueing & throttling): 재전송하기 전에 발신 요청을 버퍼링하거나 대기열에 넣어 트래픽 흐름을 제어하세요.
- 지터를 포함한 지수 백오프(Exponential backoff with jitter): 재시도 시 시도 간 대기 시간을 기하급수적으로 늘리고(예: 1초, 2초, 4초, 8초) 작은 무작위 지연("지터")을 추가하여 대기열의 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과 를 방지하세요.
백오프 없이 레이트 리밋이 적용된 엔드포인트에 지속적으로 요청을 보내면 제한 기간이 연장되고 시스템의 운영 처리량에 심각한 영향을 미칠 수 있습니다. 요청을 적절히 스로틀링하면 더 원활하고 탄력적인 통합이 보장됩니다.
기본 제한, 요청 증가 및 추가 세부 정보는 레이트 리밋을 참조하세요.
| 코드 | 메시지 | 설명 |
|---|---|---|
13 | Internal failure! Try again later | 내부 오류가 발생했을 때. |
이 엔드포인트의 전체 코드 목록은 Human API 프로세스 생성 레퍼런스를 참조하세요.
다음 단계
- 이후 Human Token 호출에서 동일한 사람을 인식할 수 있도록
humanToken값을 사용자 레코드와 함께 저장하세요. - 감사 또는 지원 목적으로 프로세스를 다시 조회하려면 프로세스 조회를 사용하세요.