메인 콘텐츠로 건너뛰기

프로세스 조회

경고

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

엔드포인트​

환경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": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idunicosign",
    "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
      },
      "serproResult": {
        "score": 92
      }
    },
    "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 필드
필드타입설명
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, RG).
documents[].doc.dataobject추출된 OCR 필드. 내용은 문서 유형 및 이용 가능한 데이터에 따라 다름.
400 Bad Request

processId 경로 파라미터가 없거나 잘못된 형식입니다.

401 Unauthorized

Bearer 토큰이 없거나, 만료되었거나, 유효하지 않습니다.

404 Not Found

processId가 존재하지 않거나 인증된 테넌트에 속하지 않습니다.

429 Too Many Requests

요청 한도에 도달했습니다.

오류 코드​

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

폴링 vs 웹훅​

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

다음 단계​

마지막 업데이트 에