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

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

MarkdownChatGPTClaude
경고

프로세스를 조회하기 전에 웹훅 설정 및 폴백 전략을 검토하세요 — 여기를 클릭하세요.

엔드포인트​

환경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실행된 여정의 유형입니다 (예: 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플로우에서 생성된 신원 인증 이벤트의 ID입니다.
capacities사용된 기능/제품입니다. PROCESS_CAPACITY_* 값 (예: IDCLOUDONE).
expiresAt프로세스/링크 만료 타임스탬프 (UTC).
token프로세스와 연결된 세션/액세스 토큰입니다 (비어 있을 수 있습니다).
companyData프로세스를 소유한 회사/테넌트의 데이터가 포함된 하위 객체입니다.
simulated불리언; 시뮬레이션/샌드박스 프로세스인지 (true) 실제 프로세스인지 (false) 여부입니다.
사용자 필드
필드의미
duiType고유 식별 문서의 유형입니다. DUI_TYPE_* 값 (예: BR_CPF).
duiValue문서 값입니다 (예: CPF 번호).
friendlyName사용자의 별칭/표시 이름입니다 (자유 텍스트, 검증되지 않음).
email사용자의 이메일입니다; 비어 있을 수 있습니다.
phoneE.164 형식의 전화번호입니다 (국가 코드 + 지역 코드 + 번호).
notifications알림 채널 목록입니다. 각 항목은 NOTIFICATION_CHANNEL_* 값을 가진 notificationChannel을 포함합니다 (예: WHATSAPP, SMS, EMAIL).
phoneCountryCodeAlpha3전화번호의 ISO alpha-3 국가 코드입니다 (예: BRA); 비어 있을 수 있습니다.
회사 데이터 필드
필드의미
branchId테넌트 지점의 식별자입니다; 지점별로 구분되지 않는 경우 비어 있습니다.
countryCodeISO alpha-3 형식의 회사 국가입니다 (예: BRA).
문서 유형 및 OCR 필드

process.services[].documents[].doc.code는 문서 유형을 대문자 약식 코드로 반환합니다. unico.moja.dictionary.br.cnh.v2.Cnh는 CNH가 됩니다. 이 코드에는 국가도 스키마 버전도 포함되지 않으며, 버전은 doc.version에서 별도로 반환됩니다.

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

개별 스키마

자체 필드 스키마를 사용하는 문서 유형 — 필드 레퍼런스의 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": "idchecktrust",
    "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": "smart_revalidation",
    "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_INCONCLUSIVE",
      "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생성 시 전송된 플로우 식별자.
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.purposestring플로우에서 구성된 프로세스의 목적.
process.clientReferencestring포털에서 인덱싱을 위한 선택적 클라이언트 측 참조.
process.useCasestring플로우와 연결된 시나리오 식별자.
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-2 국가 코드.
process.bioTokenDataobject참조 프로세스 정보 — 1:1 검증 및 스마트 재검증 플로우에서만 존재합니다.
process.servicesarray서명된 봉투, 캡처된 문서 및 기타 서비스 출력. 아래를 참조하세요.
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하나 이상의 기능이 확정적 부정 결과를 반환했습니다 (예: 라이브니스 실패, 신원 불일치).
PROCESS_RESULT_ERROR결과 처리 중 오류.
PROCESS_RESULT_EXPIRED여정이 완료되기 전에 프로세스가 만료되었습니다.
PROCESS_RESULT_UNSPECIFIED프로세스가 아직 완료되지 않았습니다.
authenticationInfo의 기능 결과

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

축약된 열거형 값

축약값 (예: livenessResult = LIVE, authenticationResult = INCONCLUSIVE)은 여기에 문서화된 전체 열거형 값 (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 배열은 봉투 수준 필드(envelopeId, documentIds)에는 camelCase를, 문서 수준 필드(doc_id, consent_granted, face_match 등)에는 snake_case를 사용합니다. 이는 실제 API 응답을 반영한 것으로 — 두 규칙 모두 의도적이며 문서 오류가 아닙니다.

필드유형설명
envelopeIdstring (UUID)서명된 봉투 식별자.
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 엔진이 실제로 생성하는 값입니다.
Mexico멕시코의 클라이언트는 RENAPO Verification 블록을 받을 수 있습니다

응답 구조는 동일하게 유지되며 idGov 블록이 추가됩니다.

RENAPO Verification이 활성화된 멕시코의 통합은 authenticationInfo 아래에 사용자의 CURP에 대해 RENAPO가 보유한 기록이 담긴 추가 idGov 블록을 받습니다. 이는 신원 결과와는 별개의 응답입니다.

{
  "process": {
    "id": "11111111-2222-3333-4444-555555555555",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_APPROVED",
    "person": {
      "duiType": "DUI_TYPE_MX_CURP",
      "duiValue": "PUEA880304MDFRJN04"
    },
    "authenticationInfo": {
      "authenticationId": "22222222-3333-4444-5555-666666666666",
      "idGov": {
        "government_valid": true,
        "curp": "PUEA880304MDFRJN04",
        "government_name": "ANA PRUEBA EJEMPLO"
      }
    },
    "companyData": { "countryCode": "MEX" }
  }
}

다른 필드와 나머지 idGov 키는 간결함을 위해 생략했습니다. idGov 필드의 전체 표는 RENAPO Verification을 참조하세요.

필드유형설명
authenticationInfo.idGovobjectCURP에 대한 RENAPO 기록. 기능이 활성화되지 않은 경우 없음. RENAPO가 응답하지 않은 경우 {}. 멕시코 전용. RENAPO Verification 참조.

오류 코드​

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

폴링 vs 웹훅​

이 엔드포인트를 폴링하여 진행 상황을 확인할 수 있지만, 권장 패턴은 웹훅을 구독하고 이 엔드포인트는 폴백으로만 호출하는 것입니다. 웹훅 및 이벤트를 참조하세요.

다음 단계​

마지막 업데이트 에