메인 콘텐츠로 건너뛰기
프로세스 조회GET

식별자로 기존 프로세스를 조회합니다. API 계약에 따라 결과는 프로세스 생성 시 이미 동기적으로 반환됩니다 — 이 엔드포인트는 재조회, 감사, 지원 용도로 사용하세요.

Markdown
경고

프로세스를 조회하기 전에 webhook 설정과 fallback 전략을 검토하세요 — 여기를 클릭하세요.

엔드포인트​

환경URL
프로덕션GET https://api.idcloud.unico.app/client/v1/process/{processId}
샌드박스GET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

요청​

헤더
헤더값
AuthorizationBearer <access_token>
경로 매개변수
매개변수유형필수설명
processIdstring (UUID)예프로세스 생성에서 반환된 프로세스 식별자입니다.

예제​

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
-H "Authorization: Bearer $TOKEN"

응답​

200 OK
{
"process": {
"id": "226fd950-4b80-4da6-a476-ba9d397ddc91",
"flow": "id_r2",
"callbackUri": "/",
"userRedirectUrl": "https://cadastro.uat.unico.app/flow?collect-data=true&dynamic-wrapper=true&id=226fd950-4b80-4da6-a476-ba9d397ddc91",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_APPROVED",
"createdAt": "2026-08-06T01:42:21.693615Z",
"finishedAt": "2026-08-06T01:43:03.080508Z",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "40*******50",
"friendlyName": "teste",
"email": "",
"phone": "5511999999999",
"notifications": [
{ "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP" }
],
"phoneCountryCodeAlpha3": ""
},
"purpose": "personAuthentication",
"services": [],
"authenticationInfo": { "authenticationId": "55cba227-9828-49df-a16f-bcdaa7bdaa4d" },
"capacities": ["PROCESS_CAPACITY_IDCLOUDONE"],
"expiresAt": "2026-08-13T01:42:21.536500Z",
"token": "",
"companyData": { "branchId": "", "countryCode": "BRA" },
"simulated": false
}
}
프로세스 필드
필드의미
id프로세스 UUID입니다. flow를 조회하고 추적하는 데 사용되는 키입니다.
flow실행된 여정의 유형입니다(예: id_r2, idlivetrust_r2, idtrust_r2, ...).
callbackUri플로우 종료 시 클라이언트 앱이 리디렉션되는 콜백 URI입니다.
userRedirectUrl사용자가 여정을 진행하기 위해 여는 CbU 페이지의 전체 URL입니다(id와 동작 플래그를 포함합니다).
state프로세스의 생명주기 상태입니다(예: PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED).
result평가의 최종 판정 결과입니다. PROCESS_RESULT_* 값(예: APPROVED, AUTHENTICATED, NOT_APPROVED, ...). state = PROCESS_STATE_FINISHED인 경우에만 확정적입니다.
createdAt프로세스 생성 시각입니다(UTC).
finishedAt프로세스 완료 시각입니다(UTC).
person검증 대상 인물의 데이터를 담은 하위 객체입니다.
purpose프로세스의 목적입니다(예: personAuthentication, 인물 등록).
services프로세스에 연결된 추가 서비스 목록입니다. 없으면 비어 있습니다.
authenticationInfo.​authenticationIdflow에서 생성된 신원 인증 이벤트의 ID입니다.
capacities사용된 기능/제품입니다. PROCESS_CAPACITY_* 값(예: IDCLOUDONE).
expiresAt프로세스/링크의 만료 시각입니다(UTC).
token프로세스에 연결된 세션/액세스 토큰입니다(비어 있을 수 있습니다).
companyData프로세스를 소유한 회사/테넌트의 데이터를 담은 하위 객체입니다.
simulated불리언 값으로, 시뮬레이션/샌드박스 프로세스인지(true) 실제 프로세스인지(false)를 나타냅니다.
person 필드
필드의미
duiType고유 식별 문서의 유형입니다. DUI_TYPE_* 값(예: BR_CPF).
duiValue문서 값입니다(예: CPF 번호).
friendlyName사용자를 위한 친근한 이름/별칭입니다(자유 텍스트로, 검증되지 않습니다).
email사용자의 이메일입니다. 비어 있을 수 있습니다.
phoneE.164 형식의 전화번호입니다(국가 코드 + 지역 코드 + 번호).
notifications알림 채널 목록입니다. 각 항목은 NOTIFICATION_CHANNEL_* 값(예: WHATSAPP, SMS, EMAIL)을 담은 notificationChannel을 가집니다.
phoneCountryCodeAlpha3전화번호의 ISO 알파-3 국가 코드입니다(예: BRA). 비어 있을 수 있습니다.
companyData 필드
필드의미
branchId테넌트 지점의 식별자입니다. 지점으로 구분되지 않는 경우 비어 있습니다.
countryCodeISO 알파-3 형식의 회사 국가 코드입니다(예: BRA).
문서 유형 및 OCR 필드

process.services[].documents[].doc.code는 문서 유형을 두 가지 형식 중 하나로 보고합니다. 재사용된 문서를 포함해 Unico의 문서 모듈에서 처리된 문서는 짧은 대문자 코드(CNH)를 가집니다. API 전용으로 생성된 프로세스는 보통 전체 딕셔너리 유형(unico.moja.dictionary.br.cnh.v2.Cnh)을 가지지만, 짧은 코드를 가질 수도 있습니다. 어떤 통합 방식이든 두 형식을 모두 처리하세요. 짧은 코드는 국가나 스키마 버전을 포함하지 않으며, 버전은 doc.version으로 별도 반환됩니다.

짧은 형식에서 통합 스키마를 사용하는 문서 유형 — 필드 참조의 unified_schema — 는 캡처 중에 식별된 유형을 대문자로 변환하여 보고됩니다. 가장 일반적인 값은 IDCARD, DRIVERLICENSE, PASSPORT, VOTERID이지만, 이 목록은 열려 있습니다. 캡처 중에 식별된 다른 유형도 대문자로 변환된 그대로 반환됩니다. 이 목록에 없는 값도 처리하세요. 미국 여권은 PASSPORT로 통합되지 않고 자체 변형을 유지합니다. POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT, REFUGEEPASSPORT도 반환됩니다. 예를 들어 unico.moja.dictionary.ar.generic.v1.IdCard와 unico.moja.dictionary.us.generic.v1.PolycarbonatePassport는 각각 IDCARD와 POLYCARBONATEPASSPORT로 보고됩니다.

특정 스키마

자체 필드 스키마를 사용하는 문서 유형 — 필드 참조의 specific_document_schemas에 나열됨 — 은 아래 표에 표시됩니다. 딕셔너리 유형을 사용하여 해당 파일에서 각 스키마를 조회하세요.

국가doc.code딕셔너리 유형문서
BRRGunico.​moja.​dictionary.​br.​rg.​v2.​RgRG
BRCNHunico.​moja.​dictionary.​br.​cnh.​v2.​CnhCNH(운전면허증)
BRCINunico.​moja.​dictionary.​br.​cin.​v1.​CinCIN
BRPASSAPORTEunico.​moja.​dictionary.​br.​passaporte.​v1.​Passaporte여권
MXINEunico.​moja.​dictionary.​mx.​ine.​v1.​IneINE 유권자 신분증
MXLPCunico.​moja.​dictionary.​mx.​lpc.​v1.​LpcLicencia para conducir(운전면허증)
MXPASAPORTEunico.​moja.​dictionary.​mx.​pasaporte.​v1.​Pasaporte여권
—UNKNOWNunico.​moja.​dictionary.​other.​unknown.​v1.​Unknown유형을 식별할 수 없거나, 자체 스키마가 없는 브라질 또는 멕시코 유형 — doc.data가 비어 있습니다

브라질 및 멕시코 문서는 위의 특정 스키마만 사용합니다. 그 외 유형의 브라질 또는 멕시코 문서(예: 멕시코 거주자 카드)는 통합 스키마가 아닌 UNKNOWN으로 보고됩니다.

PASSAPORTE와 PASAPORTE는 서로 다른 문서입니다

브라질 여권은 PASSAPORTE(S 두 개)이고 멕시코 여권은 PASAPORTE(S 한 개)로, 각각 자신의 딕셔너리 표기를 그대로 따릅니다. 이는 오타가 아니므로 두 값을 동일하게 취급하지 마세요.

doc.code가 UNKNOWN인 경우 OCR 추출이 수행되지 않으며 doc.data에 어떤 필드도 보고되지 않습니다.

Brazil브라질의 클라이언트는 전체 프로세스 페이로드를 받을 수 있습니다

전체 응답 구조는 동일하게 유지됩니다 — 단일 결과가 기본값입니다.

브라질의 통합은 아래의 전체 프로세스 객체를 받을 수 있으며, authenticationInfo에 기능별 결과가 포함됩니다.

{
"process": {
"id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
"flow": "iddocs_r2",
"callbackUri": "https://example.com/callback",
"userRedirectUrl": "https://example.com/redirect",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_OK",
"createdAt": "2024-01-01T10:00:00Z",
"finishedAt": "2024-01-01T10:15:00Z",
"expiresAt": "2024-01-08T10:00:00Z",
"purpose": "VERIFICATION",
"clientReference": "client-ref-abc",
"useCase": "USE_CASE_LOGIN",
"capacities": ["liveness", "face_match"],
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909",
"friendlyName": "Luke Skywalker",
"notifications": [
{
"notificationChannel": "email"
}
]
},
"authenticationInfo": {
"authenticationId": "auth-123",
"livenessResult": "LIVENESS_RESULT_LIVE",
"authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
"identityFraudstersResult": "TRUST_RESULT_UNSPECIFIED",
"bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
"smartRevalidationResult": "SMART_REVALIDATION_RESULT_UNSPECIFIED",
"idAgeResult": "ID_AGE_RESULT_UNSPECIFIED",
"scoreEngineResult": {
"scoreEnabled": "SCORE_ENABLED_TRUE",
"score": 85.5
}
},
"companyData": {
"branchId": "branch-123",
"countryCode": "BRA"
},
"bioTokenData": {
"referenceProcessId": "ref-proc-123",
"authenticationId": "auth-ref-123"
},
"services": [
{
"consent_granted": true,
"documents": [
{
"doc_id": "doc-abc-123",
"share_id": "share-abc-123",
"typified": true,
"cpf_match": true,
"validate_doc": true,
"face_match": true,
"verified": true,
"reused_doc": false,
"signed_url": "https://example.com/doc?token=xyz",
"doc": {
"version": 2,
"code": "CNH",
"data": {
"numero": "044589731564",
"cpfNumero": "12345678909",
"nomeCivil": "Luke Skywalker",
"dataNascimento": "1990-05-12T00:00:00Z",
"dataExpiracao": "2027-12-07T00:00:00Z",
"categoria": "B"
}
}
}
]
}
]
}
}
최상위 필드
필드유형설명
process.idstring (UUID)프로세스 식별자입니다.
process.flowstring생성 시 전송된 flow 식별자입니다.
process.callbackUristring프로세스 이벤트를 위해 설정된 콜백 URL입니다.
process.​userRedirectUrlstring여정 완료 후 사용자를 리디렉션할 URL입니다.
process.stateenum현재 프로세스 상태입니다. 아래 값을 참조하세요.
process.resultenum검증 결과입니다. state = PROCESS_STATE_FINISHED인 경우에만 존재합니다.
process.createdAtstring (datetime)프로세스가 생성된 시각의 ISO 8601 타임스탬프입니다.
process.finishedAtstring (datetime)프로세스가 완료된 시각의 ISO 8601 타임스탬프입니다. state = PROCESS_STATE_FINISHED인 경우에만 존재합니다.
process.expiresAtstring (datetime)프로세스가 만료되는 시각의 ISO 8601 타임스탬프입니다.
process.purposestringflow에서 설정된 프로세스의 목적입니다.
process.​clientReferencestring포털에서 인덱싱하기 위한 선택적 클라이언트 측 참조값입니다.
process.useCasestringflow와 연관된 시나리오 식별자입니다.
process.capacitiesarray of strings이 프로세스에서 활성화된 기능 목록입니다.
process.tokenstringSDK 통합을 위한 서명된 JWT입니다.
process.personobject생성 시 제공된 신원 정보입니다.
process.​person.​notificationsarray여정에 설정된 알림 채널입니다(예: email).
process.​authenticationInfoobject기능별 결과입니다. 아래를 참조하세요.
process.companyDataobject회사 및 지점 컨텍스트입니다.
process.​companyData.​branchIdstring지점 식별자입니다.
process.​companyData.​countryCodestringISO 3166-1 alpha-3 국가 코드입니다(예: BRA).
process.​bioTokenDataobject참조 프로세스 정보입니다 — 1:1 검증 및 스마트 재검증 flow에서만 존재합니다.
process.servicesarray서명된 envelope, 캡처된 문서 및 기타 서비스 결과입니다. 아래를 참조하세요.
process.state 값
값의미
PROCESS_STATE_CREATED프로세스가 생성되었으며 사용자가 아직 여정을 완료하지 않았습니다.
PROCESS_STATE_AWAITING_FOR_DOCUMENT신분증 없이 프로세스가 생성된 상태입니다. Custom Flow가 선택적 문서를 허용하는 경우에만 존재합니다. 프로세스 문서 설정으로 문서를 전송하세요.
PROCESS_STATE_FINISHED여정이 완료되었습니다. result와 authenticationInfo를 확인하세요.
PROCESS_STATE_FAILED처리 중 오류가 발생했습니다.
process.result 값
값의미
PROCESS_RESULT_OK모든 기능이 긍정적인 결과를 반환했습니다.
PROCESS_RESULT_INVALID_IDENTITY최소 하나의 기능이 확정적인 부정 결과를 반환했습니다(예: liveness 실패, 신원 불일치).
PROCESS_RESULT_ERROR결과 처리 중 오류가 발생했습니다.
PROCESS_RESULT_EXPIRED여정이 완료되기 전에 프로세스가 만료되었습니다.
PROCESS_RESULT_UNSPECIFIED프로세스가 아직 완료되지 않았습니다.
authenticationInfo의 기능별 결과

모든 필드는 flow와 관계없이 항상 반환됩니다. flow에서 사용되지 않은 기능의 필드는 *_UNSPECIFIED를 반환합니다.

축약된 enum 값

축약된 값(예: livenessResult = LIVE, authenticationResult = INCONCLUSIVE)은 여기에 문서화된 전체 enum 값(LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE 등)에 직접 대응됩니다 — 접두사는 간결함을 위해 생략됩니다.

필드기능가능한 값
authenticationId—이 인증 시도의 고유 식별자입니다.
livenessResult라이브니스LIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED
authenticationResult신원 확인AUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResult사기 위험 분류TRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED
bioTokenEngineResult1:1 검증BIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResult스마트 재검증SMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResult연령 인증ID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.​scoreEnabled위험 점수SCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.​score위험 점수-100에서 +100 사이의 숫자입니다. authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE이고 위험 점수가 활성화된 경우에 존재합니다.
serproResult.scoreSerpro 유사도 반환0–100(유사도); -1(해당 CPF에 등록된 얼굴 없음); -2(통합 오류).
deviceMetadata디바이스 메타데이터status(found, not_found, unavailable)와 디바이스 데이터를 포함하는 객체. 플로우에서 이 기능이 활성화되지 않은 경우 존재하지 않습니다.
process.services 필드
모듈당 항목 하나

services에는 프로세스에서 완료된 모듈마다 항목이 하나씩 들어갑니다. 각 모듈의 가장 최근 완료된 실행만 들어가며, 프로세스가 PROCESS_STATE_FINISHED 또는 PROCESS_STATE_AWAITING_FOR_DOCUMENT 상태일 때만 들어갑니다. API 전용으로 생성된 프로세스는 어떤 상태에서든 문서 항목을 가집니다. 문서 캡처 항목에는 documents와 consent_granted가 포함됩니다. 전자 서명 항목에는 envelope_id와 document_ids가 포함됩니다. 항목에는 유형 필드가 없고 순서도 고정되어 있지 않으므로, 위치가 아닌 키로 각 항목을 식별하고 인식하지 못하는 항목은 무시하세요. 키는 snake_case이지만, doc.data 안의 키는 문서 스키마를 따릅니다(예: nomeCivil).

필드유형설명
consent_grantedboolean문서 캡처 항목입니다. 사용자가 귀사와 문서를 공유하는 데 동의했는지 여부입니다.
documentsarray문서 캡처 항목입니다. OCR 데이터와 검증 결과가 포함된 캡처된 문서들입니다.
documents[].doc_idstring문서 식별자입니다.
documents[].​share_idstring이 프로세스에 대해 사용자가 귀사에 부여한 공유의 식별자입니다.
documents[].​typifiedboolean문서 유형이 식별되었는지 여부입니다.
documents[].​cpf_matchboolean브라질에만 해당합니다. 문서의 CPF가 생성 시 전송된 CPF와 일치하는지 여부입니다. 국가가 브라질로 설정된 회사에는 항상 포함되며, 다른 국가와 국가가 설정되지 않은 회사에서는 생략됩니다.
documents[].​validate_docboolean브라질에만 해당합니다. 문서가 Unico의 문서 검증을 통과했는지 여부입니다. 국가가 브라질로 설정된 회사에는 항상 포함되며(검증이 실행되지 않은 경우 false), 다른 국가와 국가가 설정되지 않은 회사에서는 생략됩니다.
documents[].​face_matchboolean or null셀피가 문서의 사진과 일치하는지 여부입니다. null은 검사가 실행되지 않았음을 의미하며, 부정적인 결과가 아닙니다.
documents[].​verifiedboolean or null문서 유형이 알려져 있고, 문서가 삭제되지 않았으며, face_match가 true이고, 문서가 품질 검사를 통과한 경우에만 true입니다. face_match가 실행되지 않은 경우를 포함해 그 외에는 false입니다. 프로세스가 문서 모듈을 거치지 않은 경우 null입니다.
documents[].​reused_docboolean이 문서가 이전 프로세스에서 재사용되었는지 여부입니다.
documents[].​signed_urlstring문서 이미지를 다운로드하기 위한 단기 서명 URL입니다. 이 URL은 만료되므로 저장하거나 고정된 유효 기간에 의존하지 말고, 새 URL이 필요하면 이 엔드포인트를 다시 호출하세요.
documents[].​doc.​versioninteger문서 유형 딕셔너리의 버전입니다(예: unico.moja.dictionary.br.cnh.v2.Cnh의 경우 2).
documents[].​doc.​codestring문서 유형으로, 짧은 코드(예: CNH) 또는 전체 딕셔너리 유형(예: unico.moja.dictionary.br.cnh.v2.Cnh)으로 반환됩니다. 문서 모듈에서 처리된 문서는 짧은 코드를 가집니다. 두 형식을 모두 처리하세요. 모든 값과 코드가 도출되는 방식은 문서 유형 및 OCR 필드를 참조하세요.
documents[].​doc.​dataobject추출된 OCR 필드입니다. 내용은 문서 유형에 따라 다릅니다 — 전체 카탈로그는 전체 필드 참조를 참조하세요. 필드 이름은 문서의 스키마를 따릅니다. 브라질 문서는 포르투갈어(예: nomeCivil, dataNascimento), 멕시코 문서는 스페인어, 통합 스키마는 영어입니다.
envelope_idstring (UUID)전자 서명 항목입니다. 서명된 envelope 식별자입니다.
document_idsarray of strings전자 서명 항목입니다. envelope에 포함된 문서들의 ID입니다.
API 전용으로 생성된 프로세스

API 전용으로 생성된 프로세스에서는 문서 항목이 Unico의 문서 모듈이 아닌 API 호출에서 오며, 일부 값이 위 표와 다릅니다.

  • consent_granted는 항상 false입니다. 동의는 귀사가 수집하며 Unico는 이를 추적하지 않습니다.
  • share_id와 signed_url은 비어 있습니다.
  • face_match는 항상 true 또는 false이며, null이 되지 않습니다.
  • verified는 항상 null입니다.
  • doc.version은 0입니다.
  • doc.code는 보통 전체 딕셔너리 유형(예: unico.moja.dictionary.br.cnh.v2.Cnh)을 가지지만, 짧은 코드를 가질 수도 있습니다.
  • OCR 데이터를 읽을 수 없는 경우 doc.data는 null입니다.

오류 코드​

코드메시지설명
3process id is invalid프로세스 ID가 유효하지 않을 때.

폴링과 webhook​

이 엔드포인트를 폴링하여 진행 상황을 확인할 수 있지만, 권장되는 방식은 webhook을 구독하고 이 엔드포인트는 fallback으로만 호출하는 것입니다. Webhooks and Events를 참조하세요.

다음 단계​