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

# Файли

> Завантажуйте PDF, зображення, відео й логотипи для своїх QR-кодів.

> [!NOTE]
>
> API GetQR перебуває в бета-версії та доступний для окремих робочих просторів. До загального релізу деталі можуть змінитися.

QR-коди PDF, Image і Video ведуть на файл, і власний логотип — теж файл. Завантаження відбувається у два кроки: зареєструйте файл, щоб отримати URL, а потім надішліть байти на цей URL.

| Метод | Шлях | Опис |
| - | - | - |
| `POST` | `/api/v1/files` | [Реєстрація завантаження файлу](#реєстрація-завантаження-файлу) |

## Завантаження файлу

**1. Зареєструйте файл**

Викличте [Реєстрацію завантаження файлу](#реєстрація-завантаження-файлу) з `target`, `contentType` і `size` файлу. `target` визначає допустимі типи вмісту й обмеження розміру. Ви отримаєте `fileId` і `uploadUrl`.

**2. Надішліть файл**

Надішліть файл запитом `PUT` на `uploadUrl`. Його `Content-Type` і `Content-Length` мають точно збігатися із зареєстрованими `contentType` і `size`: усе інше відхиляється. URL попередньо підписаний, тому не додавайте свій API-ключ. Термін його дії — 10 хвилин.

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

**3. Використайте ID файлу**

Передайте `fileId`, коли [створюєте QR-код](https://docs.getqr.com/ua/api/endpoints/qr-codes.md):

* Як `fileId` для QR-коду `pdf`, `image` або `video`. Завантажуйте з відповідним target.
* Як `fileId` для зображення профілю QR-коду `vcard`, `social`, `multilink` або `event`. Завантажуйте з target `logo`.
* Як `logoOptions.fileId`, з `logoOptions.type` зі значенням `uploaded`, для власного логотипа. Завантажуйте з target `logo`. Див. [Оформлення](https://docs.getqr.com/ua/api/guides/customization.md).

## Обмеження

| `target` | Допустимі типи вмісту | Максимальний розмір |
| - | - | - |
| `pdf` | `application/pdf` | 20 МБ (20 971 520 байтів) |
| `image` | `image/*` | 5 МБ (5 242 880 байтів) |
| `video` | `video/*` | 50 МБ (52 428 800 байтів) |
| `logo` | `image/*` | 5 МБ (5 242 880 байтів) |

* **Лише MIME-тип.** Надсилайте один тип і підтип у нижньому регістрі, наприклад `image/png`. Параметри на кшталт `;charset=` і списки відхиляються.
* **Без SVG.** Типи на основі XML, як-от `image/svg+xml`, не приймаються. Завантажуйте растрове зображення, наприклад `image/png` або `image/jpeg`.

## Заголовки

**Authorization** `string` *required*

`Bearer`, а за ним ваш API-ключ. Див. [Автентифікація](https://docs.getqr.com/ua/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*

Точний розмір файлу в байтах, додатне ціле число. Перевіряється за обмеженням для target. Запит на завантаження має надіслати саме цей `Content-Length`.

**name** `string`

Початкова назва файлу, до 255 символів. Зберігається для відображення в панелі керування. Шлях із `/` або `\` відхиляється.

**fileId** `string`

ID, який потрібно передати як `fileId` або `logoOptions.fileId`.

**uploadUrl** `string`

Попередньо підписаний URL, на який потрібно надіслати файл через `PUT`.

**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"
>
> Тип вмісту не відповідає target. Наприклад, `pdf` приймає лише `application/pdf`. Див. [Обмеження](#обмеження).

> [accordion] 422 "must be a single lowercase type/subtype"
>
> Надсилайте тип вмісту в нижньому регістрі й без параметрів: `image/png`, а не `Image/PNG` чи `image/png; charset=utf-8`.

> [accordion] 422 "File is too large for target"
>
> Заявлений `size` перевищує обмеження для target. Стисніть файл, перш ніж реєструвати його.

> [accordion] Не вдається завантажити файл на uploadUrl
>
> Дія URL завершується через 10 хвилин після реєстрації файлу, а запит має надіслати саме зареєстровані `Content-Type` і `Content-Length`. Зареєструйте файл знову, щоб отримати новий URL.

> [accordion] 422 "is registered but its content was never uploaded" під час створення QR-коду
>
> Ви зареєстрували файл, але `PUT` на `uploadUrl` не завершився. Завантажте файл, а потім створіть QR-код.

> [accordion] 422 "was uploaded to …" під час створення QR-коду
>
> Файл зареєстровано з іншим target, наприклад файл `image` використано для QR-коду `pdf`. Зареєструйте нове завантаження з відповідним target.

> [accordion] 404 "File … was not found" під час створення QR-коду
>
> `fileId` не існує. Візьміть його з відповіді [Реєстрації завантаження файлу](#реєстрація-завантаження-файлу).

## Що далі

> [card] [QR-коди](https://docs.getqr.com/ua/api/endpoints/qr-codes.md)

> [card] [Дані QR-коду за типами](https://docs.getqr.com/ua/api/guides/qr-types.md)

> [card] [Оформлення](https://docs.getqr.com/ua/api/guides/customization.md)

> [card] [Помилки](https://docs.getqr.com/ua/api/errors.md)


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