퀵스타트 | Unico Developer Portal

퀵스타트

빈 호스트에서 시작해 몇 분 만에 첫 프로세스를 생성하고 조회합니다.

이 페이지에서는 사용 중인 환경에서 빠르게 시작할 수 있도록 임시 PostgreSQL 컨테이너와 함께 Human Plugin을 실행합니다. 배포하려면 Docker Compose 또는 Kubernetes를 참고하세요.

사전 요구 사항

linux/amd64 또는 linux/arm64에서 Docker 24 이상(macOS의 Docker Desktop도 사용 가능).
Unico에서 받은 레지스트리 자격 증명과 액세스 키. 사전 요구 사항 및 액세스를 참고하세요.

1. 이미지 가져오기

호스트마다 한 번, 사용자 이름과 토큰으로 Unico 레지스트리에 로그인합니다.

echo "<token>" | docker login pkg.unico.run -u <username> --password-stdin

docker pull pkg.unico.run/human-plugin-api:latest

2. PostgreSQL과 Human Plugin 시작하기

docker network create human-plugin

docker run -d --name human-plugin-db --network human-plugin \
  -e POSTGRES_USER=human_plugin -e POSTGRES_PASSWORD=human_plugin -e POSTGRES_DB=human_plugin \
  postgres:16

셸에 액세스 키를 설정한 다음 Human Plugin을 시작합니다.

export HUMAN_API_ACCESS_KEY='<your access key>'

docker run -d --name human-plugin --network human-plugin --stop-timeout 60 -p 127.0.0.1:8080:8080 \
  -e HUMAN_API_ACCESS_KEY \
  -e POSTGRES_ADDRESS_HOST=human-plugin-db \
  -e POSTGRES_USER=human_plugin \
  -e POSTGRES_PASSWORD=human_plugin \
  -e POSTGRES_SSL_MODE=disable \
  pkg.unico.run/human-plugin-api:latest

POSTGRES_SSL_MODE=disable은 이 로컬 데이터베이스에만 사용합니다. 그 외의 데이터베이스에서는 기본값인 require를 유지하세요. 구성을 참고하세요.

Human Plugin이 준비되었는지 확인합니다.

curl --fail http://127.0.0.1:8080/health/ready

{"status":"ok"}가 표시되어야 합니다. 명령이 실패하면 docker logs human-plugin에서 원인을 확인할 수 있습니다.

3. 프로세스 생성하기

플로우 중 하나를 선택하세요. clientId, correlationId, credential은 모든 플로우에서 동일합니다.

humantoken (사용자가 직접 촬영)
api+humantoken (셀카를 직접 전송)

사용자가 캡처 저니에서 셀카를 촬영합니다. 응답에는 해당 저니로 연결되는 link가 포함됩니다.

curl -s -X POST http://127.0.0.1:8080/v1/processes \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "humantoken",
    "clientId": "client-a",
    "correlationId": "quickstart-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "callbackUri": "https://example.com/callback"
  }'

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_CREATED",
  "token": "<SDK token>",
  "link": "https://…"
}

휴대폰에서 link를 열고 셀카를 촬영합니다. token과 link는 여기서만 반환되며, Human Plugin은 이를 저장하지 않습니다.

백엔드에 이미 셀카가 있다면 imageBase64로 전송합니다. 응답은 Human Token과 인텔리전스가 포함된 최종 결과입니다.

curl -s -X POST http://127.0.0.1:8080/v1/processes \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "quickstart-002",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'

{
  "id": "5d1f7c2e-1b8a-4e0f-9a4b-2f6c3d9e8a71",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 1,
      "transactionsCount": 1,
      "firstSeen": "2026-11-03",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

id는 Human Plugin이 프로세스에 부여한 자체 ID입니다. 나중에 프로세스를 읽을 수 있는 유일한 방법이므로 보관하세요.
correlationId는 귀사의 참조 값이며 고유해야 합니다. 이미 사용한 값을 다시 쓰면 409 CORRELATION_ID_ALREADY_USED가 반환됩니다.
credential은 사용자의 문서입니다. 문서가 없으면 null을 보내세요. 사용할 수 있는 유형은 속성 카탈로그에 있습니다.
data.humanToken은 사용자가 누구인지를, data.ndocs는 사용자의 인텔리전스, 즉 귀사와 어떤 활동을 했는지를 나타냅니다. 인텔리전스를 참고하세요.
Journey를 사용하면 완료된 프로세스에 data.liveness도 포함됩니다. 캡처가 실제 사람에게서 이루어졌다면 live, 그렇지 않다면 not_live입니다. data의 결과를 참고하세요.

4. 다시 읽어 오기

ID를 응답에서 받은 값으로 바꾸세요.

curl -s http://127.0.0.1:8080/v1/processes/b063041c-7529-4e70-a2b4-c71c00f19801

Journey는 사용자가 캡처를 마칠 때까지 PROCESS_STATE_CREATED 상태로 유지됩니다. 캡처가 끝난 뒤 다시 읽으면 응답이 PROCESS_STATE_FINISHED로 바뀌며 data.humanToken, data.liveness, data.ndocs가 포함됩니다. 결과를 신뢰하기 전에 data.liveness.value가 live인지 확인하세요.

5. 정리하기

docker rm -f human-plugin human-plugin-db && docker network rm human-plugin

다음 단계

플로우: 어떤 플로우를 사용할지, 각 플로우에 무엇이 필요한지.
프로세스 생성: 모든 필드와 규칙.
백엔드 통합: 무엇을 저장하고 실패를 어떻게 처리할지.
Human Token Journey: 캡처 저니.
프런트엔드 측 캡처를 위한 가이드: Web, Android, iOS, Ionic, React Native, Flutter.
인프라에서 Human Plugin 실행하기

사전 요구 사항​

1. 이미지 가져오기​

2. PostgreSQL과 Human Plugin 시작하기​

3. 프로세스 생성하기​

4. 다시 읽어 오기​

5. 정리하기​

다음 단계​