메인 콘텐츠로 건너뛰기
API Reference 개요

제로에서 첫 번째 humanToken까지 필요한 모든 것.

Markdown

Human Token에는 세 개의 엔드포인트가 있습니다. 이 페이지에서는 이들이 어떻게 연결되는지 보여주어 바로 통합을 시작할 수 있도록 합니다.

기본 URL​

환경기본 URL
프로덕션https://humantoken.unico.app

모든 요청에는 x-unico-accesskey 헤더가 필요합니다. 키 생성 방법은 인증을 참조하세요.

빠른 시작 흐름​

1단계 — 인증​

Human Dashboard 또는 Authentication API에서 x-unico-accesskey를 생성합니다. 아래의 모든 요청은 이 키를 사용합니다.

x-unico-accesskey: uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2

2단계 — 프로세스 생성​

Create Process를 호출하여 검증을 시작합니다. 두 가지 모델 중 하나를 선택하세요:

모델플로우작동 방식
API Onlyapi+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation백엔드가 셀피를 imageBase64로 전송합니다. humanToken이 동일한 응답에서 반환됩니다.
Human Token Journeyhumantoken, humantoken+revalidation사용자가 Unico 플랫폼에서 캡처를 완료합니다. journey를 제시할 token과 link를 받은 후, Get Process로 결과를 조회합니다.

API Only 예시:

curl -X POST https://humantoken.unico.app/client/v1/process \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "api+humantoken",
    "imageBase64": "<base64-encoded-selfie>",
    "companyBranchId": "<your-branch-id>"
  }'

Human Token Journey 예시:

curl -X POST https://humantoken.unico.app/client/v1/process \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "humantoken",
    "callbackUri": "https://yourapp.com/callback",
    "companyBranchId": "<your-branch-id>"
  }'

모든 플로우, 매개변수 및 응답 세부 정보는 Create Process를 참조하세요.

3단계 — 사용자에게 journey 제시 (Journey 플로우만 해당)​

humantoken 및 humantoken+revalidation 플로우의 경우, Create Process 응답에는 다음이 포함됩니다:

  • token — Web SDK 또는 네이티브 통합을 초기화합니다
  • link — 사용자를 리디렉션할 URL

플랫폼에 맞는 통합을 선택하세요:

플랫폼접근 방식
Web — SDKidpay-b2b-sdk로 journey를 인라인 임베드 → Web Integration
Web — Redirect사용자를 link로 리디렉션 → Web Integration
AndroidCustom Tabs → Android
iOSASWebAuthenticationSession → iOS
IonicCapacitor plugin → Ionic
React NativeNative module → React Native
FlutterPlatform Channels → Flutter

journey가 종료되면 사용자는 callbackUri로 돌아옵니다. 4단계로 진행하세요.

API Only 플로우

이 단계를 건너뛰세요 — 결과는 이미 Create Process 응답에 포함되어 있습니다.

4단계 — 결과 조회 (Journey 플로우만 해당)​

프로세스 id로 Get Process를 호출하여 결과를 가져옵니다:

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

응답에는 data.humanToken.value(표준 플로우) 또는 data.humanTokenMatch(재검증 플로우)가 포함됩니다. 전체 응답 스키마와 상태 값은 Get Process를 참조하세요.

5단계 — humanToken 사용​

humanToken은 안정적이고 불투명한 식별자입니다(최대 100자). 동일한 사람은 항상 동일한 값으로 해석됩니다.

const { humanToken } = process.data;

if (!humanToken?.value) {
  // Inconclusive — retry or reject per your business rules
  return;
}

const existing = await db.persons.findByHumanToken(humanToken.value);

if (existing) {
  // Same person seen before — returning user or duplicate
} else {
  // First time — create a new record
  await db.persons.create({ humanToken: humanToken.value });
}
경고

저장하거나 매칭하기 전에 항상 data.humanToken.value가 비어 있지 않은지 확인하세요.

6단계 — 셀피 검색 (선택 사항)​

Get Selfie를 호출하여 캡처한 이미지를 다운로드합니다. 셀피는 프로세스 완료 후 24시간 동안 사용할 수 있으며, 그 이후에는 영구적으로 삭제됩니다.

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

응답 세부 정보와 오류 코드는 Get Selfie를 참조하세요.

엔드포인트 한눈에 보기​

메서드엔드포인트설명
POST/client/v1/processCreate Process — 검증 시작
GET/client/v1/process/{processId}Get Process — 결과 조회
GET/client/v1/process/{processId}/selfieGet Selfie — 셀피 다운로드 (24시간)

다음 단계​

  • Create Process — 5개 플로우 모두에 대한 전체 매개변수 레퍼런스
  • Authentication — 액세스 키 생성 및 관리
  • Build With LLM — AI 어시스턴트에 프롬프트를 붙여넣어 전체 통합 생성
마지막 업데이트 에