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

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

경고

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

엔드포인트​

환경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 엔진이 실제로 생성하는 값입니다.

오류 코드​

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

폴링 vs 웹훅​

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

다음 단계​

마지막 업데이트 에