> ## 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]
>
> GetQR API находится в бета-версии и доступен для отдельных рабочих пространств. До общего релиза детали могут измениться.

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/ru/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/ru/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/ru/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/ru/api/endpoints/qr-codes.md)

> [card] [Типы QR-кодов](https://docs.getqr.com/ru/api/guides/qr-types.md)

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

> [card] [Ошибки](https://docs.getqr.com/ru/api/errors.md)


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