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

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

MarkdownChatGPTClaude
경고

프로세스를 조회하기 전에 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, 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.​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 필드

통합 스키마를 사용하는 문서 유형 — 필드 참조의 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으로 별도 반환됩니다.

특정 스키마

자체 필드 스키마를 사용하는 문서 유형 — 필드 참조의 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가 비어 있습니다
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": "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.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 알파-2 국가 코드입니다.
process.​bioTokenDataobject참조 프로세스 정보입니다 — 1:1 검증 및 스마트 재검증 flow에서만 존재합니다.
process.servicesarray서명된 envelope, 캡처된 문서 및 기타 서비스 결과입니다. 아래를 참조하세요.
process.state 값
값의미
PROCESS_STATE_CREATED프로세스가 생성되었으며 사용자가 아직 여정을 완료하지 않았습니다.
AWAITING_FOR_DOCUMENT신분증 없이 프로세스가 생성된 상태입니다. Custom Flow가 선택적 문서를 허용하는 경우에만 존재합니다. 프로세스 문서 설정으로 문서를 전송하세요.
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라이브니스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(통합 오류).
process.services 필드
services의 명명 규칙 혼용

services 배열은 envelope 레벨 필드(envelopeId, documentIds)에는 camelCase를, 문서 레벨 필드(doc_id, consent_granted, face_match 등)에는 snake_case를 사용합니다. 이는 실제 API 응답을 그대로 반영한 것으로, 두 표기 방식 모두 의도된 것이며 문서 오류가 아닙니다.

필드유형설명
envelopeIdstring (UUID)서명된 envelope 식별자입니다.
documentIdsarray of strings이 서비스에서 캡처된 문서들의 ID입니다.
consent_grantedboolean사용자가 데이터 공유 동의를 부여했는지 여부입니다.
documentsarrayOCR 데이터와 검증 결과가 포함된 캡처된 문서들입니다.
documents[].doc_idstring문서 식별자입니다.
documents[].​typifiedboolean문서 유형이 성공적으로 식별되었는지 여부입니다.
documents[].​cpf_matchboolean문서의 CPF가 제공된 CPF와 일치하는지 여부입니다(브라질에만 해당).
documents[].​face_matchboolean셀피가 문서의 사진과 일치하는지 여부입니다.
documents[].​validate_docboolean문서가 진위성 검증을 통과했는지 여부입니다.
documents[].​reused_docboolean이 문서가 이전 프로세스에서 재사용되었는지 여부입니다.
documents[].​signed_urlstring문서 PDF를 다운로드하기 위한 사전 서명된 URL입니다(5분간 유효 — 갱신하려면 다시 조회하세요).
documents[].​doc.​versionintegerOCR 스키마 버전입니다.
documents[].​doc.​codestring짧은 문서 유형 코드입니다(예: CNH). 모든 값과 코드가 도출되는 방식은 문서 유형 및 OCR 필드를 참조하세요.
documents[].​doc.​dataobject추출된 OCR 필드입니다. 내용은 문서 유형에 따라 다릅니다 — 전체 카탈로그는 전체 필드 참조를 참조하세요. doc.data 내부의 필드 이름(예: nomeCivil, dataNascimento)은 포르투갈어로 반환됩니다 — 이는 OCR 엔진이 실제로 생성하는 값입니다.

오류 코드​

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

폴링과 webhook​

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

다음 단계​

마지막 업데이트 에