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

이 엔드포인트를 사용하여 새로운 문서 캡처 플로우를 시작하기 전에 사용자에게 이미 재사용 가능한 문서가 있는지 확인합니다. 문서가 발견되면, 해당 `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>` ([인증](../authentication) 참조)|
| `APIKEY` | 문서 캡처 및 재사용이 활성화된 프로비저닝된 API 키. |

## 쿼리 파라미터

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

:::note
위의 `type` 값은 이 엔드포인트에 특화된 것입니다. 다음과 혼동하지 마세요:
- POST 요청의 `subject.duiType` - `DUI_TYPE_*` 접두사를 사용하며 문서 유형이 아닌 *사람*을 식별합니다 (예: `DUI_TYPE_BR_CPF`).
- 응답의 `documentType` - 전체 레지스트리 경로를 사용합니다 (예: `unico.moja.dictionary.br.cnh.v2.Cnh`).
:::

### 예제

### cURL

```bash
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

```javascript
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

```json
{
  "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`가 있으면, 캡처를 건너뛰기 위해 문서 프로세스 요청에 전달합니다:

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

전체 문서 프로세스 요청 스키마는 [문서 프로세스 생성](./post-processes-document)을 참조하세요.

### 오류 코드

### 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

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. | 만료된 액세스 토큰입니다. |
| `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. | 제공된 파라미터에 대한 문서를 찾을 수 없습니다. |

### 429 Too Many Requests

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

**모범 사례:**

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

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

기본 제한, 요청 증가 및 추가 세부사항은 [속도 제한](../rate-limits)을 참조하세요.

### 500 Internal Server Error

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