프로세스 생성POST

프로세스를 시작하고 Human Token과 해당 사용자의 인텔리전스를 받습니다.

Markdown

POST /v1/processes

플로우 중 하나로 프로세스를 시작하고, id, state, 그리고 data에 담긴 결과(Human Token과 해당 사용자의 인텔리전스, data.ndocs)로 응답합니다.

호출 전 확인 사항

• Human Plugin이 실행 중이고 GET /health/ready가 200으로 응답합니다.
• 액세스 키가 사용하려는 플로우에 대해 활성화되어 있습니다.
• 문서를 보내는 경우, 해당 type이 속성 카탈로그에 있습니다.

플로우

flow 필드는 프로세스가 수행할 작업을 선택합니다. Human Plugin은 두 가지 통합 모델로 다음 플로우를 실행합니다.

• API Only: 백엔드가 imageBase64로 셀피를 보내고, 생성 요청이 결과를 응답합니다.
• Human Token Journey: 사용자가 캡처 저니에서 셀피를 촬영한 뒤 callbackUri로 돌아옵니다. 생성 요청은 token과 link로 응답하며, 결과는 프로세스 조회로 읽습니다.

Flow	Description	Possible result	Integration components required	Example
api+humantoken	백엔드를 통해 셀피를 받아 고유한 얼굴 식별자인 Human Token을 생성합니다. 응답이 최종 결과이며, 캡처도 두 번째 호출도 없습니다.	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	캡처 저니에서 라이브니스 확인과 함께 셀피를 캡처하고 Human Token을 생성합니다. 생성 요청은 `token`과 `link`를 반환하며, 캡처가 끝나면 결과를 읽습니다.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
humantoken+revalidation	셀피를 캡처하여 기대하는 Human Token과 얼굴을 비교합니다. 예를 들어 민감한 작업 전에 동일인인지 여부를 반환합니다.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

clientId, correlationId, credential은 모든 플로우에서 동일합니다.

요청

{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}

공통 필드

필드	필수	제한(바이트)	비고
flow	예	64	플로우 중 하나
clientId	예	128	고객에 대한 사용자의 id. 인텔리전스는 서로 다른 값의 개수를 셉니다
correlationId	예	128	이 프로세스에 대한 사용자의 참조값. 고유해야 함: 상태와 관계없이 다른 프로세스가 이미 가진 값은 409로 거부됩니다
credential	예(비어 있어도 됨)		키는 반드시 있어야 합니다. 아래를 참고하세요
credential.type	문서와 함께		속성 카탈로그의 코드. 정확히, 대소문자를 구분하여 일치해야 합니다
credential.value	문서와 함께	64	문서 번호

flow, clientId, correlationId는 제어 문자와 앞뒤 공백이 없는 문자열이어야 합니다. 유효하지 않은 값은 거부되며, 임의로 수정되지 않습니다.

credential 필드

• 문서가 있는 경우: 정확히 type과 value만 가진 객체로, 둘 다 문자열이며 함께 보내야 합니다.
• 문서가 없는 경우: null 또는 {}. 이 경우에도 프로세스는 인텔리전스에서 하나의 트랜잭션이자 하나의 고객으로 집계됩니다.
• 생략했거나 빈 문자열로 된 객체: 400 MISSING_CREDENTIAL_TYPE으로 거부됩니다. 이를 통해 아무것도 처리되기 전에 키 철자 오류를 잡아냅니다.
• credential 안의 다른 키는 모두 거부됩니다.

플로우 필드

각 플로우가 공통 필드에 추가하는 항목:

필드	플로우	필수	값
imageBase64	api+humantoken	예	base64로 인코딩한 셀피. PNG, JPEG 또는 WebP, 최대 800 KB
callbackUri	humantoken, humantoken+revalidation	예	캡처가 끝나면 사용자가 돌아오는 위치: 사용자의 페이지 또는 앱의 URL 스킴
references	humantoken+revalidation	예	위 예시처럼 기대하는 Human Token이 담긴 항목 하나

Human Plugin은 이 필드를 저장하지 않으며, 철자가 틀린 선택 필드는 오류 없이 무시될 수 있습니다.

api+humantoken에는 한 사람의 얼굴이 정면으로, 밝은 조명에서 찍힌 셀피를 사용하세요. 이미지가 아닌 값은 거부되며 프로세스는 실패로 저장됩니다. 플로우 거부 사유를 참고하세요.

humantoken+revalidation에서는 결과에 humanToken 대신 humanTokenMatch가 포함됩니다.

• "true": 동일인입니다. 프로세스는 해당 사용자의 것으로 집계되며, ndocs가 그 사용자를 설명합니다.
• 그 외의 값이거나 라이브가 아닌 캡처: 확인되지 않았습니다. 프로세스는 누구의 것으로도 집계되지 않으며 ndocs도 없습니다.

두 경우 모두 PROCESS_STATE_FINISHED로 응답하므로 humanTokenMatch를 확인하세요. 프로세스 조회를 참고하세요.

일부 이름(예: clientReference)은 Human Plugin이 예약해 두었으며 400 INVALID_REQUEST로 거부됩니다. client_id, correlation_id, Flow처럼 Human Plugin 자체 필드의 다른 표기도 마찬가지입니다. flow, clientId, correlationId, credential만, 정확히 그 철자대로 읽습니다.

본문 규칙

• JSON 객체 하나, 최대 2 MiB(base64 셀피 한 장이 들어갈 정도)입니다. 이보다 큰 본문은 400 REQUEST_TOO_LARGE로 거부됩니다.
• JSON 객체 뒤에 다른 내용이 올 수 없습니다.

응답

201 Created이며 Location: /v1/processes/<id> 헤더가 포함됩니다.

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

• id는 Human Plugin의 UUID입니다. 수락된 요청마다 새 값이 생성됩니다.
• state는 로컬 상태입니다. 수명 주기를 참고하세요.
• humantoken과 humantoken+revalidation은 token 및 link와 함께 PROCESS_STATE_CREATED로 응답합니다. 이 값은 한 번만 반환되고 저장되지 않으므로 직접 보관하세요. Human Token Journey와 사용하는 플랫폼의 캡처 가이드를 참고하세요.
• data.ndocs는 해당 사용자의 인텔리전스입니다. 없을 수도 있습니다. 인텔리전스를 참고하세요.

data의 결과

완료된 프로세스는 data에 다음 필드를 가집니다. Journey 플로우는 캡처 후 프로세스를 조회할 때 이 필드를 반환합니다.

필드	조건	값
humanToken	api+humantoken, humantoken	사용자가 누구인지를 나타냅니다. value는 Human Token이며, 생성된 경우 status는 validated입니다
humanTokenMatch	humantoken+revalidation	references의 Human Token과 동일인이면 "true"
liveness	Journey 플로우처럼 라이브니스를 확인하는 플로우	캡처가 실제 사람에게서 나왔으면 value는 live, 아니면 not_live입니다. 확인이 수행되었으면 status는 validated입니다
ndocs	해당 사용자에 대한 인텔리전스가 있는 경우	해당 사용자의 인텔리전스

Journey 결과는 다음과 같습니다.

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}

결과를 신뢰하기 전에 liveness를 확인하세요. not_live이면 캡처가 실패한 것으로 처리하고 사용자에게 다시 시도하도록 안내하세요. not_live인 프로세스는 누구의 인텔리전스에도 집계되지 않습니다.

오류

상태	message	의미
400	INVALID_REQUEST, REQUEST_TOO_LARGE	JSON 객체 하나가 아니거나, 예약된 필드이거나, 잘못된 타입이거나, 본문이 2 MiB를 초과함
400	MISSING_<FIELD>, INVALID_<FIELD>	필수 필드가 없거나 형식이 잘못됨(예: MISSING_CLIENT_ID)
401	비어 있음("")	Unico가 액세스 키를 거부했습니다: 누락, 오류 또는 더 이상 유효하지 않음. 프로세스는 실패로 저장됩니다. HUMAN_API_ACCESS_KEY를 확인하세요
409	CORRELATION_ID_ALREADY_USED	다른 프로세스가 이미 해당 correlationId를 사용 중입니다. 저장되거나 전송되는 것은 없습니다
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	credential.type이 카탈로그에 없습니다. 저장되거나 전송되는 것은 없습니다
4xx	플로우의 message	플로우가 요청을 거부했습니다(예: 잘못된 이미지). 플로우 거부 사유를 참고하세요
502	UPSTREAM_UNAVAILABLE	시간 내에 프로세스를 확인하지 못했습니다
503	DATABASE_UNAVAILABLE	데이터베이스 오류입니다. 처리된 것은 없습니다
500	INTERNAL	예기치 않은 오류

플로우 거부 사유

플로우가 요청을 거부하면, 생성 요청은 일반적인 엔벨로프에 사유를 message로 담아 4xx로 응답합니다. 가장 흔한 사유:

message	원인
invalid flow	flow가 계정에서 활성화된 플로우가 아님
INVALID_IMAGE (400)	imageBase64 없이 api+humantoken을 호출함
INVALID_REQUEST (400)	imageBase64가 base64 이미지가 아님
IMAGE_TOO_LARGE	이미지가 800 KB를 초과함
UNSUPPORTED_IMAGE_FORMAT	이미지가 PNG, JPEG 또는 WebP가 아님
PERMISSION_DENIED (403)	액세스 키가 이 플로우에 대해 활성화되어 있지 않음

거부된 프로세스는 실패로 저장됩니다. 요청을 수정하고 새 correlationId로 새 프로세스를 생성하세요.

재시도 로직을 추가하기 전에 오류 및 재시도를 읽어 보세요. 새 시도에는 새 correlationId가 필요합니다.

다음 단계

프로세스 조회