메인 콘텐츠로 건너뛰기
백엔드 연동

서버 측 서비스에서 Human Plugin을 호출하기 위한 체크리스트입니다.

Markdown

Human Plugin은 백엔드에서만 호출하도록 설계되었습니다. 인바운드 인증이 없으므로 브라우저나 모바일 앱에 노출하지 마세요.

1. 생성​

curl -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "onboarding-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'

클라이언트 타임아웃은 최소 60초로 설정하세요. 생성 요청은 처리에 최대 30초가 걸릴 수 있고, 여기에 데이터베이스 단계가 더해집니다. id는 생성 응답에서만 전달되므로, 클라이언트가 너무 일찍 포기하면 완료되는 프로세스를 놓칠 수 있습니다.

2. 나중에 필요한 항목 저장​

저장할 항목이유
idGET 호출에 사용하는 식별자입니다
Journey token과 link (있는 경우)생성 응답에서만 반환되며 Human Plugin은 저장하지 않습니다
사용자의 correlationId고유해야 합니다. 503 이후를 제외하고, 재시도를 포함해 모든 시도마다 새로 생성하세요

3. 결과 확인​

  1. state가 PROCESS_STATE_FINISHED이면 data에서 결과를 읽습니다. humanToken(재검증에서는 humanTokenMatch), liveness, ndocs가 들어 있습니다. 완료되었다고 해서 승인된 것은 아닙니다.
  2. state가 PROCESS_STATE_CREATED이면 상태가 바뀔 때까지 백오프를 두고 GET /v1/processes/{id}를 폴링합니다. 프로세스를 진행시키는 것은 이 외에 없습니다.
  3. state가 PROCESS_STATE_FAILED이면 프로세스가 결과 없이 종료된 것입니다. 플로우가 허용하면 새 프로세스를 시작하세요.

4. 인텔리전스 활용​

data.ndocs는 해당 사용자가 귀사와 어떤 활동을 했는지 알려줍니다. 귀사의 고객사와 문서 중 몇 건에서, 언제 확인되었는지가 담겨 있습니다. 판단에 Human Token과 함께 활용하되, 값이 없을 수 있다는 점을 염두에 두세요. 인텔리전스를 참고하세요.

5. 실패 처리​

  • 생성 시 500 또는 502는 자동으로 재시도하지 마세요. 오류 및 재시도를 참고하세요.
  • 생성 시 503은 동일한 correlationId로, GET의 모든 실패는 백오프를 두고 재시도하세요.
  • 409는 correlationId가 이미 사용 중이라는 의미입니다. 절대 재사용하지 마세요.
  • 503이 반복되면 알림을 설정하세요. Human Plugin이 데이터베이스에 접근하지 못한다는 뜻입니다.

운영 시 유의사항​

  • Human Plugin은 컨테이너와 같은 네트워크에서 호출하세요. 경로가 신뢰할 수 없는 네트워크를 지나는 경우 앞단에서 TLS를 종료하세요.
  • Human Plugin 설치 한 개는 하나의 격리 경계입니다. 인텔리전스를 공유하면 안 되는 서로 다른 고객사, 브랜드, 환경은 각각 별도의 설치와 데이터베이스를 사용해야 하며, 각자의 인텔리전스를 가집니다.
마지막 업데이트 에