프로세스 조회GET

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

경고

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

엔드포인트

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

요청

헤더

헤더	값
Authorization	Bearer <access_token>
APIKEY	프로비저닝된 API 키.

경로 파라미터

파라미터	유형	필수	설명
processId	string (UUID)	예	프로세스 생성에서 반환된 프로세스 식별자.

예제

cURL

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

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.id.unico.app/processes/v1/${processId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const result = await res.json();

응답

200 OK

이 계약은 단일합니다 — idCloud.result 필드가 사용된 기능들의 통합 판정을 전달합니다.

Unico는 실행된 기능들의 결과를 단일 idCloud.result로 통합하여, 개별 결과를 조정할 필요 없이 플로우의 다음 단계를 바로 결정할 수 있게 합니다.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

필드	유형	설명
id	string (UUID)	프로세스 식별자.
status	integer	1 (처리 중), 2 (불일치), 3 (성공적으로 완료), 4 (취소됨), 5 (오류).

가능한 결과 값

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

반환되는 값은 APIKey에 구성된 레시피에 따라 다릅니다. 각 레시피가 반환할 수 있는 결과 값은 플로우를 참조하세요.

브라질의 클라이언트는 기능별 응답을 받을 수 있습니다

전체 응답 구조는 동일하게 유지됩니다 — 단일 결과가 기본값입니다.

브라질의 통합은 개방형의 기능별 결과를 받을 수 있습니다. APIKey에서 활성화된 각 기능은 응답에 자체 블록을 추가하며, 비활성화된 기능의 필드는 생략됩니다.

{
  "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,
  "idAge": {
    "result": "yes"
  },
  "cardholderVerification": {
    "result": "approved"
  }
}

필드	유형	설명
unicoId.result	string	yes, no, inconclusive — 신원 확인 참조.
riskLevel.result	string	not_approved, critical_risk, high_risk, inconclusive — 사기 위험 분류 참조.
idFace.result	string	FOUND — 얼굴 식별자 참조.
idFace.personId	string	얼굴에 대한 안정적인 불투명 식별자로, idFace.result = FOUND와 함께 반환됩니다. 이미지에서 얼굴을 식별할 수 없는 경우, 프로세스는 idFace 블록 대신 오류 20532를 반환합니다.
identityFraudsters.result	string	더 이상 사용되지 않습니다. 대신 riskLevel을 사용하세요. 통합이 진행 중인 클라이언트는 프로젝트 팀과 마이그레이션을 조율하면서 계속 사용할 수 있습니다.
government.serpro	integer	Serpro 유사도 점수 (0–100, -1, -2). 브라질에서만 사용 가능합니다. Serpro 유사도 반환 참조.
liveness	integer	1 (통과), 2 (실패) — 라이브니스 참조.
idAge.result	string	yes, no, inconclusive — 연령 인증 참조. 브라질에서만 사용 가능합니다.
score	integer	확률적 위험 점수. unicoId.result = inconclusive이고 위험 점수 오케스트레이션이 활성화된 경우 존재합니다. 양수 값은 본인일 확률이 높음을, 음수 값은 위험이 높음을 나타냅니다. 브라질에서만 사용 가능합니다.
cardholderVerification.result	string	approved, unsure — Cardholder Verification 참조. status가 아직 3 (완료)이 아닌 동안에는 존재하지 않습니다. 브라질에서만 사용 가능합니다.

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

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

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

오류 코드

400 Bad Request

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

404 Not Found

코드	메시지	설명
50001	O processo informado não foi encontrado.	해당 프로세스가 데이터베이스에 존재하지 않습니다.

403 Forbidden

코드	메시지	설명
30017	User does not have permission to perform this action.	잘못된 형식의 JWT이거나 이 작업을 수행할 권한이 없는 사용자입니다.
10502	O token informado está expirado.	사용된 액세스 토큰이 만료되었습니다.
10501	O token informado é inválido.	인증 토큰이 유효하지 않습니다.
10201	O AppKey informado é inválido.	APIKEY 파라미터가 입력되지 않았거나 존재하지 않습니다.

410 Gone

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

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

• Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
• Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
• Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.

경고

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

500 Internal Server Error

코드	메시지	설명
99999	Internal failure! Try again later	내부 오류가 발생했습니다.

플로우

레시피는 프로젝트의 APIKey에 구성된 기능(라이브니스, 신원 확인, 위험 신호, 문서 등)의 조합입니다. 이는 Unico가 각 프로세스에서 실행하는 작업과 결과가 단일 result로 통합되는 방식을 정의합니다 — 사용자 측에서는 아무것도 조정할 필요가 없습니다.

Unico는 사전 정의되고 이름과 버전이 지정된 레시피 카탈로그를 관리합니다 (예: byunico-idlive-idunico-oneresponse-std). Score, Serpro 또는 연령 인증을 포함하는 레시피와 같이 일부는 브라질 전용입니다.

프로세스가 실행하는 기능은 무엇인가요?

기능의 조합 — 즉 프로젝트의 플로우 — 는 APIKey 설정에서 정의됩니다. 사전 정의된 레시피를 확인하거나, 이를 맞춤화하려면 Unico 프로젝트 담당자에게 문의하세요.