--- title: 프로세스 조회 description: 검증 프로세스의 현재 상태와 결과를 조회합니다. canonical: https://developer.unico.io/ko/developers/api-reference/get-process locale: ko generated_by: markdown-export --- - [/ko/](/ko/) - API 레퍼런스 - 프로세스 조회 **이 페이지에서프로세스 조회GET식별자로 기존 프로세스를 조회합니다. API 계약에 따라 결과는 프로세스 생성 시 이미 동기적으로 반환됩니다 — 이 엔드포인트는 재조회, 감사, 지원 용도로 사용하세요. 경고프로세스를 조회하기 전에 webhook 설정과 fallback 전략을 검토하세요 — [여기를 클릭하세요](/ko/developers/webhooks-and-events/setup). ### 엔드포인트​ 환경URL**프로덕션**`GET https://api.idcloud.unico.app/client/v1/process/{processId}`**샌드박스**`GET https://api.idcloud.uat.unico.app/client/v1/process/{processId}` ### 요청​ 헤더 헤더값`Authorization``Bearer ` 경로 매개변수 매개변수유형필수설명`processId`string (UUID)예[프로세스 생성](/ko/developers/api-reference/post-processes)에서 반환된 프로세스 식별자입니다. ### 예제​ cURLNode.js``` curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \ -H "Authorization: Bearer $TOKEN" ``` ``` import fetch from 'node-fetch';const res = await fetch( `https://api.idcloud.unico.app/client/v1/process/${processId}`, { headers: { Authorization: `Bearer ${accessToken}` } });const { process: proc } = await res.json(); ``` ### 응답​ 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`, `FAILED`, `FINISHED`, `AWAITING_FOR_DOCUMENT`, `UNSPECIFIED`).`result`평가의 최종 판정 결과입니다. `PROCESS_RESULT_*` 값(예: `APPROVED`, `AUTHENTICATED`, `NOT_APPROVED`, ...). `state = PROCESS_STATE_FINISHED`인 경우에만 확정적입니다.`createdAt`프로세스 생성 시각입니다(UTC).`finishedAt`프로세스 완료 시각입니다(UTC).`person`검증 대상 인물의 데이터를 담은 하위 객체입니다.`purpose`프로세스의 목적입니다(예: `personAuthentication`, 인물 등록).`services`프로세스에 연결된 추가 서비스 목록입니다. 없으면 비어 있습니다.`authenticationInfo.​authenticationId`flow에서 생성된 신원 인증 이벤트의 ID입니다.`capacities`사용된 기능/제품입니다. `PROCESS_CAPACITY_*` 값(예: `IDCLOUDONE`).`expiresAt`프로세스/링크의 만료 시각입니다(UTC).`token`프로세스에 연결된 세션/액세스 토큰입니다(비어 있을 수 있습니다).`companyData`프로세스를 소유한 회사/테넌트의 데이터를 담은 하위 객체입니다.`simulated`불리언 값으로, 시뮬레이션/샌드박스 프로세스인지(`true`) 실제 프로세스인지(`false`)를 나타냅니다. person 필드 필드의미`duiType`고유 식별 문서의 유형입니다. `DUI_TYPE_*` 값(예: `BR_CPF`).`duiValue`문서 값입니다(예: CPF 번호).`friendlyName`사용자를 위한 친근한 이름/별칭입니다(자유 텍스트로, 검증되지 않습니다).`email`사용자의 이메일입니다. 비어 있을 수 있습니다.`phone`E.164 형식의 전화번호입니다(국가 코드 + 지역 코드 + 번호).`notifications`알림 채널 목록입니다. 각 항목은 `NOTIFICATION_CHANNEL_*` 값(예: `WHATSAPP`, `SMS`, `EMAIL`)을 담은 `notificationChannel`을 가집니다.`phoneCountryCodeAlpha3`전화번호의 ISO 알파-3 국가 코드입니다(예: `BRA`). 비어 있을 수 있습니다. companyData 필드 필드의미`branchId`테넌트 지점의 식별자입니다. 지점으로 구분되지 않는 경우 비어 있습니다.`countryCode`ISO 알파-3 형식의 회사 국가 코드입니다(예: `BRA`). 문서 유형 및 OCR 필드 통합 스키마를 사용하는 문서 유형 — [필드 참조](/ko/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)의 `unified_schema` — 는 캡처 중에 식별된 유형 식별자를 대문자로 변환하여 보고됩니다: `IDCARD`, `DRIVERLICENSE`, `PASSPORT`, `VOTERID`. 미국 여권은 `PASSPORT`로 통합되지 않고 자체 변형을 유지하므로, `POLYCARBONATEPASSPORT`, `PASSPORTCARD`, `PAPERPASSPORT` 같은 값도 반환됩니다. 예를 들어 `unico.moja.dictionary.ar.generic.v1.IdCard`와 `unico.moja.dictionary.us.generic.v1.PolycarbonatePassport`는 각각 `IDCARD`와 `POLYCARBONATEPASSPORT`로 보고됩니다. `process.services[].documents[].doc.code`는 문서 유형을 짧은 대문자 코드로 보고합니다. `unico.moja.dictionary.br.cnh.v2.Cnh`는 `CNH`가 됩니다. 이 코드는 국가나 스키마 버전을 포함하지 않으며, 버전은 `doc.version`으로 별도 반환됩니다. 특정 스키마 자체 필드 스키마를 사용하는 문서 유형 — [필드 참조](/ko/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)의 `specific_document_schemas`에 나열됨 — 은 아래 표에 표시됩니다. 딕셔너리 유형을 사용하여 해당 파일에서 각 스키마를 조회하세요. 국가`doc.code`딕셔너리 유형문서BR`RG``unico.​moja.​dictionary.​br.​rg.​v2.​Rg`RGBR`CNH``unico.​moja.​dictionary.​br.​cnh.​v2.​Cnh`CNH(운전면허증)BR`CIN``unico.​moja.​dictionary.​br.​cin.​v1.​Cin`CINBR`PASSAPORTE``unico.​moja.​dictionary.​br.​passaporte.​v1.​Passaporte`여권MX`INE``unico.​moja.​dictionary.​mx.​ine.​v1.​Ine`INE 유권자 신분증MX`LPC``unico.​moja.​dictionary.​mx.​lpc.​v1.​Lpc`Licencia para conducir(운전면허증)MX`PASAPORTE``unico.​moja.​dictionary.​mx.​pasaporte.​v1.​Pasaporte`여권—`UNKNOWN``unico.​moja.​dictionary.​other.​unknown.​v1.​Unknown`유형을 식별할 수 없음 — `doc.data`가 비어 있습니다 `PASSAPORTE`와 `PASAPORTE`는 서로 다른 문서입니다브라질 여권은 `PASSAPORTE`(S 두 개)이고 멕시코 여권은 `PASAPORTE`(S 한 개)로, 각각 자신의 딕셔너리 표기를 그대로 따릅니다. 이는 오타가 아니므로 두 값을 동일하게 취급하지 마세요. `doc.code`가 `UNKNOWN`인 경우 OCR 추출이 수행되지 않으며 `doc.data`에 어떤 필드도 보고되지 않습니다. 브라질의 클라이언트는 전체 프로세스 페이로드를 받을 수 있습니다전체 응답 구조는 동일하게 유지됩니다 — 단일 결과가 기본값입니다.브라질의 통합은 아래의 전체 프로세스 객체를 받을 수 있으며, 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": "BR" }, "bioTokenData": { "referenceProcessId": "ref-proc-123", "authenticationId": "auth-ref-123" }, "services": [ { "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47", "documentIds": ["doc-abc-123"], "consent_granted": true, "documents": [ { "doc_id": "doc-abc-123", "typified": true, "cpf_match": true, "face_match": true, "validate_doc": true, "reused_doc": false, "signed_url": "https://example.com/doc?token=xyz", "doc": { "version": 1, "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.id`string (UUID)프로세스 식별자입니다.`process.flow`string생성 시 전송된 flow 식별자입니다.`process.callbackUri`string프로세스 이벤트를 위해 설정된 콜백 URL입니다.`process.​userRedirectUrl`string여정 완료 후 사용자를 리디렉션할 URL입니다.`process.state`enum현재 프로세스 상태입니다. 아래 값을 참조하세요.`process.result`enum검증 결과입니다. `state = PROCESS_STATE_FINISHED`인 경우에만 존재합니다.`process.createdAt`string (datetime)프로세스가 생성된 시각의 ISO 8601 타임스탬프입니다.`process.finishedAt`string (datetime)프로세스가 완료된 시각의 ISO 8601 타임스탬프입니다. `state = PROCESS_STATE_FINISHED`인 경우에만 존재합니다.`process.expiresAt`string (datetime)프로세스가 만료되는 시각의 ISO 8601 타임스탬프입니다.`process.purpose`stringflow에서 설정된 프로세스의 목적입니다.`process.​clientReference`string포털에서 인덱싱하기 위한 선택적 클라이언트 측 참조값입니다.`process.useCase`stringflow와 연관된 시나리오 식별자입니다.`process.capacities`array of strings이 프로세스에서 활성화된 기능 목록입니다.`process.token`stringSDK 통합을 위한 서명된 JWT입니다.`process.person`object생성 시 제공된 신원 정보입니다.`process.​person.​notifications`array여정에 설정된 알림 채널입니다(예: `email`).`process.​authenticationInfo`object기능별 결과입니다. 아래를 참조하세요.`process.companyData`object회사 및 지점 컨텍스트입니다.`process.​companyData.​branchId`string지점 식별자입니다.`process.​companyData.​countryCode`stringISO 3166-1 알파-2 국가 코드입니다.`process.​bioTokenData`object참조 프로세스 정보입니다 — 1:1 검증 및 스마트 재검증 flow에서만 존재합니다.`process.services`array서명된 envelope, 캡처된 문서 및 기타 서비스 결과입니다. 아래를 참조하세요.process.state 값값의미`PROCESS_STATE_CREATED`프로세스가 생성되었으며 사용자가 아직 여정을 완료하지 않았습니다.`AWAITING_FOR_DOCUMENT`신분증 없이 프로세스가 생성된 상태입니다. Custom Flow가 선택적 문서를 허용하는 경우에만 존재합니다. [프로세스 문서 설정](/ko/developers/api-reference/set-process-document)으로 문서를 전송하세요.`PROCESS_STATE_FINISHED`여정이 완료되었습니다. `result`와 `authenticationInfo`를 확인하세요.`PROCESS_STATE_FAILED`처리 중 오류가 발생했습니다.상태 명명 불일치`AWAITING_FOR_DOCUMENT`는 다른 상태들이 따르는 `PROCESS_STATE_*` 접두사 규칙을 따르지 않습니다. 이는 현재 API에서 알려진 명명 불일치입니다.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`[라이브니스](/ko/capabilities/liveness)`LIVENESS_RESULT_LIVE`, `LIVENESS_RESULT_NOT_LIVE`, `LIVENESS_RESULT_UNSPECIFIED``authenticationResult`[신원 확인](/ko/capabilities/identity-verification)`AUTHENTICATION_RESULT_POSITIVE`, `AUTHENTICATION_RESULT_NEGATIVE`, `AUTHENTICATION_RESULT_INCONCLUSIVE`, `AUTHENTICATION_RESULT_UNSPECIFIED``identityFraudstersResult`[사기 위험 분류](/ko/capabilities/fraud-risk-classification)`TRUST_RESULT_YES`, `TRUST_RESULT_INCONCLUSIVE`, `TRUST_RESULT_UNSPECIFIED``bioTokenEngineResult`[1:1 검증](/ko/capabilities/1-1-validation)`BIO_TOKEN_ENGINE_RESULT_POSITIVE`, `BIO_TOKEN_ENGINE_RESULT_NEGATIVE`, `BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED``smartRevalidationResult`[스마트 재검증](/ko/capabilities/smart-revalidation)`SMART_REVALIDATION_RESULT_POSITIVE`, `SMART_REVALIDATION_RESULT_NEGATIVE`, `SMART_REVALIDATION_RESULT_UNSPECIFIED``idAgeResult`[연령 인증](/ko/capabilities/age-verification)`ID_AGE_RESULT_POSITIVE`, `ID_AGE_RESULT_NEGATIVE`, `ID_AGE_RESULT_INCONCLUSIVE`, `ID_AGE_RESULT_UNSPECIFIED``scoreEngineResult.​scoreEnabled`[위험 점수](/ko/capabilities/risk-score)`SCORE_ENABLED_TRUE`, `SCORE_ENABLED_FALSE`, `SCORE_ENABLED_UNSPECIFIED``scoreEngineResult.​score`[위험 점수](/ko/capabilities/risk-score)-100에서 +100 사이의 숫자입니다. `authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE`이고 위험 점수가 활성화된 경우에 존재합니다.`serproResult.score`[Serpro 유사도 반환](/ko/capabilities/serpro-similarity-return)`0`–`100`(유사도); `-1`(해당 CPF에 등록된 얼굴 없음); `-2`(통합 오류).process.services 필드`services`의 명명 규칙 혼용`services` 배열은 envelope 레벨 필드(`envelopeId`, `documentIds`)에는 camelCase를, 문서 레벨 필드(`doc_id`, `consent_granted`, `face_match` 등)에는 snake_case를 사용합니다. 이는 실제 API 응답을 그대로 반영한 것으로, 두 표기 방식 모두 의도된 것이며 문서 오류가 아닙니다.필드유형설명`envelopeId`string (UUID)서명된 envelope 식별자입니다.`documentIds`array of strings이 서비스에서 캡처된 문서들의 ID입니다.`consent_granted`boolean사용자가 데이터 공유 동의를 부여했는지 여부입니다.`documents`arrayOCR 데이터와 검증 결과가 포함된 캡처된 문서들입니다.`documents[].doc_id`string문서 식별자입니다.`documents[].​typified`boolean문서 유형이 성공적으로 식별되었는지 여부입니다.`documents[].​cpf_match`boolean문서의 CPF가 제공된 CPF와 일치하는지 여부입니다(브라질에만 해당).`documents[].​face_match`boolean셀피가 문서의 사진과 일치하는지 여부입니다.`documents[].​validate_doc`boolean문서가 진위성 검증을 통과했는지 여부입니다.`documents[].​reused_doc`boolean이 문서가 이전 프로세스에서 재사용되었는지 여부입니다.`documents[].​signed_url`string문서 PDF를 다운로드하기 위한 사전 서명된 URL입니다(5분간 유효 — 갱신하려면 다시 조회하세요).`documents[].​doc.​version`integerOCR 스키마 버전입니다.`documents[].​doc.​code`string짧은 문서 유형 코드입니다(예: `CNH`). 모든 값과 코드가 도출되는 방식은 [문서 유형 및 OCR 필드](#document-type-values)를 참조하세요.`documents[].​doc.​data`object추출된 OCR 필드입니다. 내용은 문서 유형에 따라 다릅니다 — 전체 카탈로그는 [전체 필드 참조](/ko/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)를 참조하세요. `doc.data` 내부의 필드 이름(예: `nomeCivil`, `dataNascimento`)은 포르투갈어로 반환됩니다 — 이는 OCR 엔진이 실제로 생성하는 값입니다. ### 오류 코드​ 400 Bad Request401 Unauthorized404 Not Found429 Too Many Requests500 Internal Server Error코드메시지설명`3`process id is invalid프로세스 ID가 유효하지 않을 때.코드메시지설명—Jwt header is an invalid JSON사용된 access token에 잘못된 문자가 포함되어 있을 때.—Jwt is expired사용된 access token이 만료되었을 때.코드메시지설명`5`error getting process: rpc error: code = NotFound desc = process not found프로세스 ID를 찾을 수 없을 때.레이트 리밋에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄적인 장애를 방지하고 제한이 악화되지 않도록 메커니즘을 구현해야 합니다. **모범 사례:** **쿨다운 기간(backoff):** 시스템에서 후속 요청을 즉시 중지하거나 줄이세요. 실패한 요청을 촘촘한 루프에서 지속적으로 재시도하지 마세요. **큐잉 및 스로틀링(Queueing & throttling):** 재전송하기 전에 발신 요청을 버퍼링하거나 대기열에 넣어 트래픽 흐름을 제어하세요. **지터를 포함한 지수 백오프(Exponential backoff with jitter):** 재시도 시 시도 간 대기 시간을 기하급수적으로 늘리고(예: 1초, 2초, 4초, 8초) 작은 무작위 지연("지터")을 추가하여 대기열의 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요. 경고백오프 없이 레이트 리밋이 적용된 엔드포인트에 지속적으로 요청을 보내면 **제한 기간이 연장되고** 시스템의 운영 처리량에 심각한 영향을 미칠 수 있습니다. 요청을 적절히 스로틀링하면 더 원활하고 탄력적인 통합이 보장됩니다. 기본 제한, 요청 증가 및 추가 세부 정보는 [레이트 리밋](/ko/developers/start/rate-limits)을 참조하세요.코드메시지설명`99999`Internal failure! Try again later내부 오류가 발생했을 때. ### 폴링과 webhook​ 이 엔드포인트를 폴링하여 진행 상황을 확인할 수 있지만, 권장되는 방식은 **webhook을 구독**하고 이 엔드포인트는 fallback으로만 호출하는 것입니다. [Webhooks and Events](/ko/developers/webhooks-and-events)를 참조하세요. ### 다음 단계​ 캡처된 셀피는 [셀피 조회](/ko/developers/api-reference/get-selfie)를 참조하세요. 증거 감사 묶음은 [증거 세트 조회](/ko/developers/api-reference/get-evidence-set)를 참조하세요. 마지막 업데이트 2026년 10월 8일**에