재사용 가능한 문서 조회

이 엔드포인트를 사용하여 새로운 문서 캡처 흐름을 시작하기 전에 사용자가 이미 재사용 가능한 문서를 보유하고 있는지 확인하세요. 문서가 발견되면, 해당 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
Node.js

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

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

요청 속도 제한에 도달했습니다. Retry-After 응답 헤더에 표시된 간격 후에 다시 시도하세요. 속도 제한을 참조하세요.

documentId를 재사용에 활용하기

documentId를 획득하면, 캡처를 건너뛰기 위해 Document 프로세스 요청에 전달하세요:

{
  "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`를 생략할 수 있으며 플랫폼이 이전에 캡처된 문서를 자동으로 가져옵니다.

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

오류 코드

400 Bad Request
403 Forbidden
404 Not Found
500 Internal Server Error

코드	메시지	설명
`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.	인증 토큰 헤더 누락.

코드	메시지	설명
`30017`	Jwt header is an invalid JSON.	액세스 토큰에 유효하지 않은 문자가 포함되어 있습니다.
`10502`	O token informado está expirado.	액세스 토큰 만료.
`10501`	O token informado é inválido.	유효하지 않은 인증 토큰.
`10201`	O AppKey informado é inválido.	누락되거나 존재하지 않는 APIKEY.

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

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

엔드포인트​

요청​

예시​

응답​

documentId를 재사용에 활용하기​

오류 코드​

엔드포인트

요청

예시

응답

documentId를 재사용에 활용하기

오류 코드