재사용 가능한 문서 가져오기

이 엔드포인트를 사용하여 새로운 문서 캡처 플로우를 시작하기 전에 사용자에게 이미 재사용 가능한 문서가 있는지 확인합니다. 문서가 발견되면, 해당 documentId를 POST /processes/v1 (Document 유형)에 직접 전달하여 캡처 단계를 건너뛸 수 있습니다.

엔드포인트

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

요청

헤더

헤더	값
Authorization	Bearer <access_token> (인증 참조)
APIKEY	문서 캡처 및 재사용이 활성화된 프로비저닝된 API 키.

쿼리 파라미터

파라미터	유형	필수	설명
code	string	예	사용자 식별자 (CPF 또는 CURP, 포맷팅 없이).
type	string	예	조회할 문서 유형. 허용 값: BR_RG, BR_CNH, BR_CIN, BR_PASSPORT.

참고

위의 type 값은 이 엔드포인트에 특화된 것입니다. 다음과 혼동하지 마세요:

• POST 요청의 subject.duiType - DUI_TYPE_* 접두사를 사용하며 문서 유형이 아닌 사람을 식별합니다 (예: DUI_TYPE_BR_CPF).
• 응답의 documentType - 전체 레지스트리 경로를 사용합니다 (예: unico.moja.dictionary.br.cnh.v2.Cnh).

예제

cURL

curl -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.id.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → pass to POST /processes/v1 for reuse

응답

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

필드	유형	설명
items	array	사용자에 대해 발견된 재사용 가능한 문서 목록. 주어진 code와 type에 대해 재사용 가능한 문서가 없으면 빈 배열입니다.
items[].documentType	string	문서 유형 식별자. 가능한 값: unico.moja.dictionary.br.rg.v2.Rg, unico.moja.dictionary.br.cnh.v2.Cnh, unico.moja.dictionary.br.cin.v1.Cin, unico.moja.dictionary.br.passaporte.v1.Passaporte.
items[].documentId	string	문서 식별자. POST /processes/v1의 document.documentId에 이 값을 전달하여 문서를 재사용합니다.

403 Forbidden

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

429 Too Many Requests

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

모범 사례:

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

경고

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

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

documentId를 사용한 재사용

documentId가 있으면, 캡처를 건너뛰기 위해 문서 프로세스 요청에 전달합니다:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

필드	설명
document.purpose	이 문서 프로세스의 비즈니스 목적. 허용 값: creditprocess, carpurchase, paybypaycheck, onboarding, fgts. 이 값들은 Document API에 특화되어 있으며 생체인식 SDK의 purpose 열거형과 다릅니다.
document.authProcessId	이 사용자에 대해 이전에 생성된 생체인식 프로세스의 ID (POST /processes/v1에서 획득).
document.documentId	이 엔드포인트의 응답에서 얻은 문서 ID. 제공되면 document.files를 생략할 수 있으며, 플랫폼이 이전에 캡처된 문서를 자동으로 검색합니다.

전체 문서 프로세스 요청 스키마는 문서 프로세스 생성을 참조하세요.

오류 코드

400 Bad Request

코드	메시지	설명
20507	O parâmetro subject.code é inválido.	잘못된 형식이거나 존재하지 않는 식별자 값 (CPF 또는 CURP).
20002	O parâmetro APIKey não foi informado.	APIKEY 헤더가 누락되었습니다.
20001	O parâmetro authtoken não foi informado.	인증 토큰 헤더가 누락되었습니다.

403 Forbidden

코드	메시지	설명
30020	The provided authorization token does not have permission to perform this action.	토큰에 문서 셀피 접근 권한이 없습니다.
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입니다.

404 Not Found

코드	메시지	설명
99987	Attachment not found.	문서와 관련된 첨부파일을 찾을 수 없습니다.
50001	The process is not found.	제공된 파라미터에 대한 문서를 찾을 수 없습니다.

500 Internal Server Error

코드	메시지	설명
99999	Internal failure! Try again later.	서버 측 처리 오류입니다.