프로세스 조회GET

식별자로 Human Token 프로세스를 조회합니다 — 사용자가 Human Token Journey에서 돌아온 후 또는 API Only 결과를 다시 조회할 때 사용합니다.

Markdown

Endpoint

환경	URL
프로덕션	GET https://humantoken.unico.app/client/v1/process/{processId}

요청

헤더

헤더	값
x-unico-accesskey	<your_access_key> (인증 참조)

경로 매개변수

매개변수	유형	필수	설명
processId	string (UUID)	예	프로세스 생성에서 반환된 프로세스 식별자입니다.

예제

cURL

curl -X GET https://humantoken.unico.app/client/v1/process/$PROCESS_ID \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://humantoken.unico.app/client/v1/process/${processId}`,
  { headers: { 'x-unico-accesskey': process.env.UNICO_ACCESS_KEY } }
);
const result = await res.json();
// result.data.humanToken.value

응답

200 OK

응답 형식은 프로세스 생성과 동일합니다. data의 구조는 프로세스 생성 시 사용된 플로우에 따라 다릅니다.

표준 플로우 (api+humantoken, api+liveness+humantoken, humantoken):

{
  "id": "6ed74799-4c2f-4023-b43f-a73cf7c847b2",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": {
      "value": "3f9a1c7e5b2d4086a1e3c5f7092b4d6e8a0c2e4f6183a5c7e9b1d3f5072a4c6e",
      "status": "validated"
    }
  }
}

재검증 플로우 (api+liveness+humantoken+revalidation, humantoken+revalidation):

{
  "id": "cb0472c0-6dbc-46c6-b830-2be7edc35424",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanTokenMatch": "true"
  }
}

필드	유형	설명
id	string (UUID)	프로세스 식별자입니다.
state	string	프로세스 상태입니다 — state 값을 참조하세요.
data.​humanToken.​value	string	표준 플로우만 해당. 얼굴의 안정적이고 불투명한 식별자입니다 (최대 100자). 동일한 사람은 항상 동일한 값으로 확인됩니다.
data.​humanTokenMatch	string	재검증 플로우만 해당. 셀피가 참조된 humanToken과 일치하면 "true", 그렇지 않으면 "false".

state 값

값	의미
PROCESS_STATE_UNSPECIFIED	상태가 지정되지 않았습니다.
PROCESS_STATE_CREATED	프로세스가 생성되었으며 아직 새 세션을 받을 수 있습니다. data는 {}입니다.
PROCESS_STATE_FINISHED	프로세스가 완료되어 더 이상 새 세션을 받지 않습니다. 표준 플로우의 경우 Human Token이 생성되면 data.humanToken이 포함되며, 재검증 플로우의 경우 data.humanTokenMatch가 셀피가 참조된 토큰과 일치하는지 나타냅니다. 그렇지 않으면 data는 {}입니다.
PROCESS_STATE_FAILED	프로세스가 실패했습니다. data는 {}입니다.
PROCESS_STATE_CANCELED	프로세스가 취소되었습니다. data는 {}입니다.
PROCESS_STATE_AWAITING_FOR_DOCUMENT	프로세스가 신분증을 기다리고 있습니다. data는 {}입니다.

경고

data.humanToken.value를 사용하기 전에 항상 비어 있지 않은지 확인하세요.

오류 코드

400 Bad Request

코드	메시지	설명
3	process id is invalid	프로세스 ID가 유효하지 않을 때.

401 Unauthorized

x-unico-accesskey 헤더에 액세스 키가 없거나 유효하지 않습니다. 인증을 참조하세요.

404 Not Found

코드	메시지	설명
5	error getting process: rpc error: code = NotFound desc = process not found	프로세스 ID를 찾을 수 없을 때.

429 Too Many Requests

레이트 리밋에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄적인 장애를 방지하고 제한이 악화되지 않도록 메커니즘을 구현해야 합니다.

모범 사례:

• 쿨다운 기간(backoff): 시스템에서 후속 요청을 즉시 중지하거나 줄이세요. 실패한 요청을 촘촘한 루프에서 지속적으로 재시도하지 마세요.
• 큐잉 및 스로틀링(Queueing & throttling): 재전송하기 전에 발신 요청을 버퍼링하거나 대기열에 넣어 트래픽 흐름을 제어하세요.
• 지터를 포함한 지수 백오프(Exponential backoff with jitter): 재시도 시 시도 간 대기 시간을 기하급수적으로 늘리고(예: 1초, 2초, 4초, 8초) 작은 무작위 지연("지터")을 추가하여 대기열의 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요.

경고

백오프 없이 레이트 리밋이 적용된 엔드포인트에 지속적으로 요청을 보내면 제한 기간이 연장되고 시스템의 운영 처리량에 심각한 영향을 미칠 수 있습니다. 요청을 적절히 스로틀링하면 더 원활하고 탄력적인 통합이 보장됩니다.

기본 제한, 요청 증가 및 추가 세부 정보는 레이트 리밋을 참조하세요.

500 Internal Server Error

코드	메시지	설명
99999	Internal failure! Try again later	내부 오류가 발생했을 때.

다음 단계

• 새 셀피를 전송하려면 프로세스 생성으로 돌아가세요.
• humanToken이 무엇을 나타내며 언제 생성되지 않는지 알아보려면 Human Token 개요를 참조하세요.