프로세스 조회

경고

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

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

엔드포인트

환경	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

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

필드	유형	설명
id	string (UUID)	프로세스 식별자.
status	integer	1 (처리 중), 2 (불일치), 3 (성공적으로 완료), 4 (취소됨), 5 (오류).
unicoId.result	string	yes, no, inconclusive — 신원 확인 참조.
identityFraudsters.result	string	yes, inconclusive — 위험 분류 참조.
government.serpro	integer	Serpro 유사도 점수 (0–100, -1, -2). Serpro 유사도 참조.
liveness	integer	1 (통과), 2 (실패) — Liveness 참조.
score	integer	확률적 위험 점수. unicoId.result = inconclusive이고 위험 점수 오케스트레이션이 활성화된 경우에 존재합니다. 양수 값은 보유자일 가능성이 높음을 나타내고, 음수 값은 위험도가 높음을 나타냅니다.

400 Bad Request

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

403 Forbidden

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

404 Not Found

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

410 Gone

프로세스가 존재하지만 오류로 종료되었습니다. id와 status: 5만 반환됩니다.

429 Too Many Requests

속도 제한에 도달했습니다. 속도 제한 참조.

500 Internal Server Error

예상치 못한 서버 오류입니다.

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

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만 반환됩니다.

500 Internal Server Error

코드	메시지	설명
99999	Internal failure! Try again later	내부 오류가 발생한 경우.