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

# Введение в API

> Управляйте QR-кодами, шаблонами, аналитикой и отчётами из собственного кода.

> [!NOTE]
>
> GetQR API находится в бета-версии и доступен для отдельных рабочих пространств. До общего релиза детали могут измениться.

GetQR API — это REST API для того, что вы делаете в панели управления: создание и изменение QR-кодов, скачивание их изображений, чтение аналитики сканирований и экспорт отчётов. Авторизуйтесь API-ключом своего аккаунта и вызывайте версионированные эндпоинты под `/api/v1`.

## Что можно делать

> [card] [QR-коды](https://docs.getqr.com/ru/api/endpoints/qr-codes.md)
>
> Создавайте, получайте списком, изменяйте, приостанавливайте, дублируйте, удаляйте и скачивайте QR-коды.

> [card] [Аналитика](https://docs.getqr.com/ru/api/endpoints/analytics.md)
>
> Итоги и разбивки сканирований для одного QR-кода или всего рабочего пространства.

> [card] [Отчёты](https://docs.getqr.com/ru/api/endpoints/reports.md)
>
> Экспортируйте разовый отчёт или настройте регулярную отправку отчётов на почту.

> [card] [Шаблоны](https://docs.getqr.com/ru/api/endpoints/templates.md)
>
> Сохраняйте дизайны и применяйте их к новым QR-кодам.

> [card] [Массовое создание QR-кодов](https://docs.getqr.com/ru/api/endpoints/bulk-qr-creations.md)
>
> Создавайте до 100 QR-кодов за раз из JSON или CSV-файла.

> [card] [Файлы](https://docs.getqr.com/ru/api/endpoints/files.md)
>
> Загружайте PDF, изображения, видео и логотипы для своих QR-кодов.

> [card] [Проверка состояния](https://docs.getqr.com/ru/api/endpoints/health.md)
>
> Проверьте, что API работает. API-ключ не нужен.

## Руководства

> [card] [Типы QR-кодов](https://docs.getqr.com/ru/api/guides/qr-types.md)
>
> Формат данных для каждого из 16 типов QR-кодов.

> [card] [Оформление](https://docs.getqr.com/ru/api/guides/customization.md)
>
> Стили точек, углы, цвета, рамки и логотипы.

> [card] [Правила доступа](https://docs.getqr.com/ru/api/guides/access-rules.md)
>
> Расписание, лимит сканирований, пароль, приостановка и удаление.

## Базовый URL

Все эндпоинты находятся под одним базовым URL:

```text theme={null}
https://getqr.com/api/v1
```

## Версионирование

Версия API входит в путь: все эндпоинты находятся под `/api/v1/`.

* Несовместимые изменения выходят под новым префиксом версии, например `/api/v2/`, а `/api/v1/` продолжает работать.
* Совместимые дополнения, например новые необязательные поля или новые эндпоинты, могут появляться и в v1. Игнорируйте поля ответа, которые ваш код не знает.

## Быстрый старт

**1. Получите API-ключ**

Создайте или покажите ключ в настройках аккаунта. См. [Аутентификация](https://docs.getqr.com/ru/api/authentication.md).

**2. Проверьте, что API доступен**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

Ответ: `{ "status": "ok", "version": "v1" }`.

**3. Создайте первый QR-код**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

API отвечает `201` с новым QR-кодом, включая его `id` и `shortLink`.

**4. Скачайте изображение**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## Запросы и ответы

* **Формат.** Отправляйте тело запроса в JSON с `Content-Type: application/json`. Исключение — загрузка CSV для [массового создания](https://docs.getqr.com/ru/api/endpoints/bulk-qr-creations.md): она использует `multipart/form-data`.
* **Ответы.** Ответы приходят в JSON. Скачивания, например изображения QR-кодов и ZIP-архивы массового создания, возвращают сам файл.
* **Даты.** Даты — строки ISO 8601 в UTC, например `2026-08-01T10:00:00.000Z`.
* **Параметры запроса.** Булевы параметры принимают строки `true` или `false`.
* **Частичное обновление.** Эндпоинты `PATCH` меняют только те поля, которые вы передали.
* **Секреты.** Ответы никогда не содержат паролей и внутренних идентификаторов. QR-код с паролем сообщает только `passwordProtected: true`.
* **Рабочее пространство.** Каждый запрос выполняется в рабочем пространстве, к которому относится ваш API-ключ. ID рабочего пространства передавать не нужно. См. [Доступ и роли](https://docs.getqr.com/ru/api/authentication.md#доступ-и-роли).
* **Ошибки.** Неудачные запросы возвращают объект `error` со стабильным `code`. См. [Ошибки](https://docs.getqr.com/ru/api/errors.md).

## Пагинация

Эндпоинты списков (QR-коды, шаблоны и запланированные отчёты) принимают два параметра запроса:

| Параметр | Описание |
| - | - |
| `page` | Возвращаемая страница. По умолчанию `1`. |
| `pageSize` | Результатов на странице, не больше `100`. По умолчанию `100`. |

Они отвечают массивом `data` и объектом `pagination`:

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| Поле | Описание |
| - | - |
| `page` | Полученная страница. |
| `pageSize` | Размер полученной страницы. |
| `total` | Число результатов на всех страницах. |
| `hasMore` | `true`, пока есть следующая страница. |

Запрашивайте следующую страницу, пока `hasMore` равно `true`. Значение `pageSize` больше `100` возвращает [`422`](https://docs.getqr.com/ru/api/errors#ошибки-валидации).

## Идемпотентность

После сетевой ошибки бывает непонятно, прошёл ли запрос. Чтобы безопасно повторить [Создание QR-кода](https://docs.getqr.com/ru/api/endpoints/qr-codes.md#создание-qr-кода), передайте заголовок `Idempotency-Key` с уникальным значением на ваш выбор:

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* Повтор запроса с тем же ключом в течение 24 часов возвращает исходный ответ, а не создаёт второй QR-код.
* Заголовок ответа `x-idempotent-replay` равен `true` для повторённого ответа и `false` для нового.
* Если первый запрос с этим ключом ещё выполняется, API отвечает `409 conflict`. Повторите запрос, когда он завершится.
* Повторное использование ключа с другим телом запроса возвращает `422 unprocessable_entity`.
* Без этого заголовка одинаковое тело запроса, отправленное в течение 30 секунд, считается дубликатом.

Массовое создание вместо заголовка принимает поле `idempotencyKey` в теле запроса. См. [Массовое создание QR-кодов](https://docs.getqr.com/ru/api/endpoints/bulk-qr-creations.md).

## Ограничения частоты запросов

Каждый API-ключ может отправлять до 600 запросов в минуту. См. [Ограничения частоты запросов](https://docs.getqr.com/ru/api/rate-limits.md).

## Скоро

Пакеты для печати появятся в одном из следующих релизов.

## Что дальше

> [card] [Аутентификация](https://docs.getqr.com/ru/api/authentication.md)

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


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