---
title: 재사용 가능한 문서 조회
description: 새 캡처 플로우를 시작하기 전에 사용자가 이미 재사용 가능한 문서를 보유하고 있는지 확인합니다.
canonical: https://developer.unico.io/ko/developers/api-reference/get-document
locale: ko
generated_by: markdown-export
---

- [/ko/](/ko/)
- API 레퍼런스
- 재사용 가능한 문서 조회

**이 페이지에서# 재사용 가능한 문서 조회

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

환경URL**프로덕션**`GET https://api.idcloud.unico.app/documents/v1`**샌드박스**`GET https://api.idcloud.uat.unico.app/documents/v1`
### 요청​

헤더
헤더값`Authorization``Bearer <access_token>` ([인증](/ko/developers/start/authentication) 참조)`APIKEY`Document Capture and Reuse가 활성화된 프로비저닝된 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`).

### 예제​

cURLNode.js```
curl -X GET "https://api.idcloud.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.idcloud.unico.app/documents/v1?${params}`,  {    headers: {      Authorization: `Bearer ${accessToken}`,      APIKEY: apiKey    }  });const data = await res.json();// data.items[0].documentId → 재사용을 위해 POST /processes/v1에 전달
```

### 응답​

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`에 이 값을 전달하세요.
### 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`는 생략할 수 있습니다 — 플랫폼이 이전에 캡처된 문서를 자동으로 조회합니다.
### 오류 코드​

400 Bad Request403 Forbidden404 Not Found429 Too Many Requests500 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.인증 토큰 헤더가 누락되었습니다.Bearer 토큰 또는 `APIKEY`가 누락, 만료, 또는 유효하지 않습니다.코드메시지설명`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.Access token이 만료되었습니다.`10501`O token informado é inválido.인증 토큰이 유효하지 않습니다.`10201`O AppKey informado é inválido.APIKEY가 누락되었거나 존재하지 않습니다.코드메시지설명`99987`Attachment not found.문서에 연결된 첨부 파일을 찾을 수 없습니다.`50001`The process is not found.지정된 매개변수에 대한 문서를 찾을 수 없습니다.레이트 리밋에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄적인 장애를 방지하고 제한이 악화되지 않도록 메커니즘을 구현해야 합니다.
**모범 사례:**

**쿨다운 기간(backoff):** 시스템에서 후속 요청을 즉시 중지하거나 줄이세요. 실패한 요청을 촘촘한 루프에서 지속적으로 재시도하지 마세요.
**큐잉 및 스로틀링(Queueing & throttling):** 재전송하기 전에 발신 요청을 버퍼링하거나 대기열에 넣어 트래픽 흐름을 제어하세요.
**지터를 포함한 지수 백오프(Exponential backoff with jitter):** 재시도 시 시도 간 대기 시간을 기하급수적으로 늘리고(예: 1초, 2초, 4초, 8초) 작은 무작위 지연("지터")을 추가하여 대기열의 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요.

경고백오프 없이 레이트 리밋이 적용된 엔드포인트에 지속적으로 요청을 보내면 **제한 기간이 연장되고** 시스템의 운영 처리량에 심각한 영향을 미칠 수 있습니다. 요청을 적절히 스로틀링하면 더 원활하고 탄력적인 통합이 보장됩니다.
기본 제한, 요청 증가 및 추가 세부 정보는 [레이트 리밋](/ko/developers/start/rate-limits)을 참조하세요.코드메시지설명`99999`Internal failure! Try again later.서버 측 처리 오류입니다.마지막 업데이트 2026년 10월 8일**에