> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 파일

> QR 코드에 사용할 PDF, 이미지, 동영상, 로고를 업로드하세요.

> [!NOTE]
>
> GetQR API는 베타 버전이며 일부 워크스페이스에서만 사용할 수 있습니다. 정식 출시 전에 세부 사항이 변경될 수 있습니다.

PDF, Image, Video QR 코드는 파일을 가리키며, 직접 만든 로고도 파일입니다. 업로드는 두 단계로 진행됩니다. 파일을 등록하여 URL을 받은 다음, 그 URL로 파일 바이트를 보냅니다.

| 메서드 | 경로 | 설명 |
| - | - | - |
| `POST` | `/api/v1/files` | [파일 업로드 등록](#파일-업로드-등록) |

## 파일 업로드

**1. 파일 등록**

파일의 `target`, `contentType`, `size`를 담아 [파일 업로드 등록](#파일-업로드-등록)을 호출합니다. `target`에 따라 허용되는 콘텐츠 타입과 크기 제한이 정해집니다. `fileId`와 `uploadUrl`을 받습니다.

**2. 파일 보내기**

`uploadUrl`로 `PUT` 요청을 보내 파일을 전송합니다. `Content-Type`과 `Content-Length`는 등록한 `contentType`, `size`와 정확히 일치해야 하며, 그렇지 않으면 거부됩니다. URL은 사전 서명되어 있으므로 API 키를 추가하지 마세요. URL은 10분 후에 만료됩니다.

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @menu.pdf
```

**3. 파일 ID 사용**

[QR 코드를 생성](https://docs.getqr.com/ko/api/endpoints/qr-codes.md)할 때 `fileId`를 전달합니다.

* `pdf`, `image`, `video` QR 코드의 `fileId`로 사용합니다. 일치하는 용도로 업로드하세요.
* `vcard`, `social`, `multilink`, `event` QR 코드 프로필 이미지의 `fileId`로 사용합니다. `logo` 용도로 업로드하세요.
* 직접 만든 로고에는 `logoOptions.type`을 `uploaded`로 설정하고 `logoOptions.fileId`로 사용합니다. `logo` 용도로 업로드하세요. [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)을 참조하세요.

## 제한

| `target` | 허용되는 콘텐츠 타입 | 최대 크기 |
| - | - | - |
| `pdf` | `application/pdf` | 20 MB(20,971,520바이트) |
| `image` | `image/*` | 5 MB(5,242,880바이트) |
| `video` | `video/*` | 50 MB(52,428,800바이트) |
| `logo` | `image/*` | 5 MB(5,242,880바이트) |

* **매개변수 없는 MIME 타입.** `image/png`처럼 소문자 타입과 하위 타입 하나만 보내세요. `;charset=` 같은 매개변수나 목록은 거부됩니다.
* **SVG 불가.** `image/svg+xml` 같은 XML 기반 타입은 허용되지 않습니다. `image/png`나 `image/jpeg` 같은 래스터 이미지를 업로드하세요.

## 헤더

**Authorization** `string` *required*

`Bearer` 뒤에 API 키를 붙입니다. [인증](https://docs.getqr.com/ko/api/authentication.md)을 참조하세요.

**Content-Type** `string` *required*

`application/json`.

## 파일 업로드 등록

`POST /api/v1/files`

파일을 등록하고 업로드할 사전 서명된 URL을 반환합니다. 이 호출 자체는 파일을 업로드하지 않습니다.

**target** `string` *required*

파일의 용도: `pdf`, `image`, `video`, `logo`. 허용되는 콘텐츠 타입과 크기 제한이 정해집니다. [제한](#제한)을 참조하세요.

**contentType** `string` *required*

매개변수 없는 파일의 MIME 타입입니다. 예: `application/pdf`. 업로드 요청은 정확히 이 `Content-Type`을 보내야 합니다.

**size** `integer` *required*

바이트 단위의 정확한 파일 크기로, 양의 정수입니다. 용도별 제한과 대조됩니다. 업로드 요청은 정확히 이 `Content-Length`를 보내야 합니다.

**name** `string`

원본 파일 이름으로, 최대 255자입니다. 대시보드 표시용으로 보관됩니다. `/` 또는 `\`가 포함된 경로는 거부됩니다.

**fileId** `string`

`fileId` 또는 `logoOptions.fileId`로 전달할 ID입니다.

**uploadUrl** `string`

파일을 `PUT`할 사전 서명된 URL입니다.

**expiresIn** `integer`

`uploadUrl`이 만료될 때까지 남은 초: `600`.

**method** `string`

업로드에 사용할 HTTP 메서드: `PUT`.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/files" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "pdf",
    "contentType": "application/pdf",
    "size": 248000,
    "name": "menu.pdf"
  }'
```

```json 200 theme={null}
{
  "fileId": "file_7bQ2xR9mKp",
  "uploadUrl": "https://storage.getqr.com/qrs-content/pdf/file_7bQ2xR9mKp?X-Amz-...",
  "expiresIn": 600,
  "method": "PUT"
}
```

## 자주 발생하는 문제

> [accordion] 422 "Content type … is not allowed for target"
>
> 콘텐츠 타입이 용도와 맞지 않습니다. 예를 들어 `pdf`는 `application/pdf`만 받습니다. [제한](#제한)을 참조하세요.

> [accordion] 422 "must be a single lowercase type/subtype"
>
> 콘텐츠 타입은 소문자로, 매개변수 없이 보내세요. `Image/PNG`나 `image/png; charset=utf-8`이 아니라 `image/png`입니다.

> [accordion] 422 "File is too large for target"
>
> 선언한 `size`가 용도별 제한을 초과합니다. 등록하기 전에 파일을 압축하세요.

> [accordion] uploadUrl로의 업로드가 실패합니다
>
> URL은 파일을 등록하고 10분 후에 만료되며, 요청은 등록한 `Content-Type`과 `Content-Length`를 정확히 보내야 합니다. 새 URL을 받으려면 파일을 다시 등록하세요.

> [accordion] QR 코드 생성 시 422 "is registered but its content was never uploaded"
>
> 파일을 등록했지만 `uploadUrl`로의 `PUT`이 완료되지 않았습니다. 파일을 업로드한 다음 QR 코드를 만드세요.

> [accordion] QR 코드 생성 시 422 "was uploaded to …"
>
> 파일이 다른 용도로 등록되었습니다. 예를 들어 `pdf` QR 코드에 `image` 파일을 사용한 경우입니다. 일치하는 용도로 새 업로드를 등록하세요.

> [accordion] QR 코드 생성 시 404 "File … was not found"
>
> 해당 `fileId`가 존재하지 않습니다. [파일 업로드 등록](#파일-업로드-등록)의 응답에서 가져오세요.

## 다음 단계

> [card] [QR 코드](https://docs.getqr.com/ko/api/endpoints/qr-codes.md)

> [card] [QR 코드 유형](https://docs.getqr.com/ko/api/guides/qr-types.md)

> [card] [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)

> [card] [오류](https://docs.getqr.com/ko/api/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.