메인 콘텐츠로 건너뛰기

프로세스 조회

경고

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

API 계약에서 POST /processes/v1 응답은 이미 최종 결과입니다. 이 엔드포인트는 재조회 목적으로 존재합니다. 예를 들어 이전에 저장한 프로세스를 검사하거나 이전 트랜잭션을 감사할 때 사용합니다. API 계약에서 POST /processes/v1 응답은 이미 최종 결과입니다. 이 엔드포인트는 재조회를 위해 존재합니다. 예를 들어, 이전에 저장한 프로세스를 검사하거나 이전 트랜잭션을 감사해야 하는 경우에 사용합니다.

엔드포인트​

환경URL
프로덕션GET https://api.id.unico.app/processes/v1/{processId}
샌드박스GET https://api.id.uat.unico.app/processes/v1/{processId}

요청​

헤더
헤더값
AuthorizationBearer <access_token>
APIKEY프로비저닝된 API 키.
경로 파라미터
파라미터유형필수설명
processIdstring (UUID)예프로세스 생성에서 반환된 프로세스 식별자.

예제​

curl -X GET https://api.id.unico.app/processes/v1/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

응답​

200 OK
{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}
응답 필드는 APIKey에 따라 다릅니다

위의 예시는 모든 가능한 기능 필드를 보여줍니다. 실제 응답에는 APIKey 설정에서 활성화된 기능의 필드만 포함되며, 비활성화된 기능의 필드는 완전히 생략됩니다. 기능을 활성화하거나 조정하려면 Unico 프로젝트 매니저에게 문의하세요.

필드유형설명
idstring (UUID)프로세스 식별자.
statusinteger1 (처리 중), 2 (불일치), 3 (성공적으로 완료), 4 (취소됨), 5 (오류).
unicoId.resultstringyes, no, inconclusive - 신원 확인 참조.
riskLevel.resultstringnot_approved, critical_risk, high_risk, inconclusive — 사기 위험 분류 참조.
idFace.resultstringFOUND, NOT_FOUND — Face Identifier 참조.
idFace.personIdstring얼굴에 대한 안정적인 불투명 식별자. idFace.result = FOUND일 때만 제공됩니다.
identityFraudsters.resultstring더 이상 사용되지 않습니다. 대신 riskLevel을 사용하세요. 통합이 진행 중인 클라이언트는 프로젝트 팀과 마이그레이션을 조율하면서 계속 사용할 수 있습니다.
government.serprointegerSerpro 유사도 점수 (0-100, -1, -2). 브라질에서만 사용 가능합니다. Serpro 유사도 반환 참조.
livenessinteger1 (통과), 2 (실패) - 라이브니스 참조.
scoreinteger확률적 위험 점수. unicoId.result = inconclusive이고 위험 점수 오케스트레이션이 활성화된 경우 존재합니다. 양수 값은 본인일 확률이 높음을, 음수 값은 위험이 높음을 나타냅니다. 브라질에서만 사용 가능합니다.
400 Bad Request

processId 경로 파라미터가 누락되었거나 형식이 잘못되었습니다. 아래 오류 코드를 참조하세요.

403 Forbidden

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

404 Not Found

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

410 Gone

프로세스가 존재하지만 오류가 발생했습니다. id와 status: 5만 반환됩니다.

429 Too Many Requests

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

모범 사례:

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

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

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

500 Internal Server Error

예기치 않은 서버 오류입니다.

이 엔드포인트를 사용하는 경우​

API 계약은 결과를 동기적으로 반환하므로 대부분의 통합에서는 이 엔드포인트가 필요하지 않습니다. 다음과 같은 경우에 사용하세요:

  • processId만 저장하고 나중에 전체 결과를 검색해야 하는 경우 (감사, 지원).
  • 원래 응답이 전송 중 손실된 것으로 의심되는 경우 (플랫폼이 작업을 완료한 후 네트워크 오류 발생).
  • 이전 프로세스를 검토하는 백오피스 도구를 구축하는 경우.

오류 코드​

코드메시지설명
20023O parâmetro processId não foi informado.processId 파라미터가 누락되었습니다.
20002O parâmetro APIKey não foi informado.요청 헤더에 APIKEY 파라미터가 누락되었습니다.
20001O parâmetro authtoken não foi informado.요청 헤더에 통합 토큰 파라미터가 누락되었습니다.
마지막 업데이트 에