메인 콘텐츠로 건너뛰기
퀵스타트

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

Markdown

이 페이지에서는 사용 중인 환경에서 빠르게 시작할 수 있도록 임시 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은 모든 플로우에서 동일합니다.

사용자가 캡처 저니에서 셀카를 촬영합니다. 응답에는 해당 저니로 연결되는 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은 이를 저장하지 않습니다.

  • 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

다음 단계​

마지막 업데이트 에