메인 콘텐츠로 건너뛰기

프로세스 조회

경고

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

엔드포인트​

환경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": "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, RG).
documents[].doc.dataobject추출된 OCR 필드. 내용은 문서 유형과 사용 가능한 데이터에 따라 다릅니다. doc.data 내의 필드 이름(예: nomeCivil, dataNascimento)은 포르투갈어로 반환됩니다 — 이는 OCR 엔진이 실제로 생성하는 값입니다.
400 Bad Request

processId 경로 파라미터가 누락되었거나 형식이 잘못되었습니다.

401 Unauthorized

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

404 Not Found

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

429 Too Many Requests

속도 제한에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄 장애를 방지하고 제한을 악화시키지 않기 위한 메커니즘을 구현해야 합니다.

모범 사례:

  • 쿨다운 기간 (백오프): 시스템에서 후속 요청을 즉시 중지하거나 조절하세요. 실패한 요청을 타이트한 루프에서 지속적으로 재시도하지 마세요.
  • 큐잉 및 조절: 발신 요청을 버퍼링하거나 큐에 넣어 다시 보내기 전에 트래픽 흐름을 제어하세요.
  • 지터를 포함한 지수 백오프: 재시도할 때 시도 간 대기 시간을 지수적으로 늘리고 (예: 1초, 2초, 4초, 8초) 작은 랜덤 지연("지터")을 추가하여 큐에 있는 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요.
경고

백오프 없이 속도 제한된 엔드포인트에 지속적으로 요청하면 제한 기간이 연장되고 시스템의 운영 처리량에 심각한 영향을 줄 수 있습니다. 요청을 적절히 조절하면 더 부드럽고 탄력적인 통합을 보장할 수 있습니다.

기본 제한, 요청 증가 및 추가 세부사항은 속도 제한을 참조하세요.

오류 코드​

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

폴링 vs 웹훅​

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

다음 단계​

마지막 업데이트 에