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

# Отчёты

> Экспортируйте разовый отчёт о сканированиях или настройте регулярную отправку отчётов на почту.

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

Отчёты подводят итоги сканирований по каждому QR-коду за завершённый день, неделю или месяц. Экспортируйте отчёт сразу или настройте его регулярную отправку на почту.

| Метод | Путь | Описание |
| - | - | - |
| `POST` | `/api/v1/reports` | [Экспорт отчёта](#экспорт-отчёта) |
| `GET` | `/api/v1/reports/schedules` | [Список запланированных отчётов](#список-запланированных-отчётов) |
| `POST` | `/api/v1/reports/schedules` | [Планирование отчёта](#планирование-отчёта) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Обновление запланированного отчёта](#обновление-запланированного-отчёта) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Удаление запланированного отчёта](#удаление-запланированного-отчёта) |

## Заголовки

**Authorization** `string` *required*

`Bearer` и ваш API-ключ. См. [Аутентификация](https://docs.getqr.com/ru/api/authentication.md).

**Content-Type** `string`

`application/json`. Обязателен в запросах `POST` и `PATCH`.

## Охват

И разовые, и запланированные отчёты принимают `scope`:

| `scope` | Что охватывает | `qrIds` |
| - | - | - |
| `all` | QR-коды вашего рабочего пространства | Не передавайте |
| `selected` | Выбранный набор QR-кодов | Один или несколько ID |
| `single` | Ровно один QR-код | Ровно один ID |

В отчёте не больше 50 QR-кодов. С `all` это последние созданные активные QR-коды; приостановленные коды не включаются. С `selected` и `single` приостановленные коды включаются. QR-коды без короткой ссылки не имеют сканирований и пропускаются.

## Период

Период — всегда последний завершённый, поэтому отчёт никогда не содержит неполных данных за сегодня. Его границы — полночь в часовом поясе отчёта.

| `period` или `frequency` | Что охватывает |
| - | - |
| `daily` | Предыдущий день |
| `weekly` | Предыдущую неделю, с понедельника по воскресенье |
| `monthly` | Предыдущий календарный месяц |

## Экспорт отчёта

`POST /api/v1/reports`

Формирует отчёт за последний завершённый период и возвращает его в ответе.

**scope** `string` *required*

`all`, `selected` или `single`. См. [Охват](#охват).

**period** `string` *required*

`daily`, `weekly` или `monthly`. См. [Период](#период).

**format** `string` *required*

`json` возвращает отчёт в теле ответа. `csv` и `pdf` возвращают файл для скачивания.

**qrIds** `string[]`

QR-коды, которые нужно включить. Обязательно для `selected` (один или несколько ID) и `single` (ровно один ID). Для `all` не передавайте.

**timezone** `string` (default: UTC)

Часовой пояс IANA, по которому выравниваются границы периода, например `America/New_York`. Неизвестный часовой пояс возвращает `422`.

**locale** `string` (default: en)

Язык PDF, например `en` или `de`. При неподдерживаемом значении используется английский. Игнорируется для `csv` и `json`.

**name** `string`

Заголовок в PDF, до 40 символов. Игнорируется для `csv` и `json`.

### Ответ в JSON

**periodStart** `string`

Первый день периода, `YYYY-MM-DD`.

**periodEnd** `string`

Первый день после периода, `YYYY-MM-DD`. Период заканчивается в полночь в начале этого дня.

**qrs** `object[]`

По одной записи на QR-код.

**properties**

**qrId** `string`

ID QR-кода.

**name** `string`

Название QR-кода или `Untitled QR`.

**type** `string`

Тип QR-кода, например `website`.

**totalScans** `integer`

Всего сканирований за период.

**uniqueScans** `integer`

Уникальных сканирований за период.

**topGeography** `string`

Код страны с наибольшим числом сканирований или `—`, если сканирований нет.

**topDevice** `string`

Устройство с наибольшим числом сканирований или `—`.

**topOs** `string`

Операционная система с наибольшим числом сканирований или `—`.

**topBrowser** `string`

Браузер с наибольшим числом сканирований или `—`.

### Ответы в CSV и PDF

Тело ответа — это файл. `Content-Disposition` называет его по периоду, например `report-2026-08-10_2026-08-17.csv`. В CSV по одной строке на QR-код со столбцами `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS` и `Top browser`.

```bash JSON theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "period": "weekly",
    "format": "json",
    "timezone": "America/New_York"
  }'
```

```bash PDF theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "all", "period": "monthly", "format": "pdf", "locale": "de" }' \
  --output report.pdf
```

```json 200 theme={null}
{
  "periodStart": "2026-08-10",
  "periodEnd": "2026-08-17",
  "qrs": [
    {
      "qrId": "clw3n7t1x0002ab0d5mqe8pkr",
      "name": "Landing page",
      "type": "website",
      "totalScans": 128,
      "uniqueScans": 96,
      "topGeography": "US",
      "topDevice": "Mobile",
      "topOs": "iOS",
      "topBrowser": "Safari"
    }
  ]
}
```

## Объект запланированного отчёта

Запланированный отчёт отправляется на почту аккаунта, который его создал, в полночь по его часовому поясу.

**id** `string`

ID запланированного отчёта.

**name** `string | null`

Название, которое отображается в теме письма и в панели управления.

**frequency** `string`

`daily`, `weekly` или `monthly`.

**scope** `string`

`all`, `selected` или `single`.

**qrIds** `string[] | null`

QR-коды, которые охватывает отчёт с охватом `selected` и `single`. `null`, если ID не передавались.

**filters** `null`

Всегда `null`. Зарезервировано.

**includePdf** `boolean`

Прикладывается ли к письму PDF.

**status** `string`

`active` или `paused`.

**timezone** `string`

Часовой пояс IANA, по которому выравниваются время отправки и период.

**locale** `string`

Язык письма и PDF.

**nextRunAt** `string`

Когда должно уйти следующее письмо, ISO 8601: ближайшая полночь (`daily`), ближайший понедельник (`weekly`) или 1-е число следующего месяца (`monthly`) по часовому поясу отчёта.

**lastRunAt** `string | null`

Когда было отправлено последнее письмо, ISO 8601.

**createdAt** `string`

Дата создания, ISO 8601.

**updatedAt** `string`

Дата последнего обновления, ISO 8601.

## Список запланированных отчётов

`GET /api/v1/reports/schedules`

Возвращает запланированные отчёты вашего рабочего пространства, включая созданные другими участниками, начиная с самых новых. Список постраничный: см. [Пагинация](https://docs.getqr.com/ru/api/introduction.md#пагинация).

**page** `integer` (default: 1)

Возвращаемая страница, 1 или больше.

**pageSize** `integer` (default: 100)

Результатов на странице, от 1 до 100.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/reports/schedules?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "clx8f2k9a0001qk0c8vhd3xyz",
      "name": "Weekly campaign digest",
      "frequency": "weekly",
      "scope": "selected",
      "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr", "clw3n7t1x0004ab0d9rzu2wfh"],
      "filters": null,
      "includePdf": true,
      "status": "active",
      "timezone": "America/New_York",
      "locale": "en",
      "nextRunAt": "2026-08-10T04:00:00.000Z",
      "lastRunAt": "2026-08-03T04:00:12.000Z",
      "createdAt": "2026-07-01T12:34:56.000Z",
      "updatedAt": "2026-07-28T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## Планирование отчёта

`POST /api/v1/reports/schedules`

Создаёт отчёт, который регулярно отправляется на почту. `nextRunAt` рассчитывается по частоте и часовому поясу.

> [!NOTE]
>
> QR-код может входить только в один запланированный отчёт для каждой частоты. Пересекающееся расписание возвращает `409 conflict`.

Отчёт с охватом `all` пересекается со всеми остальными отчётами той же частоты. Приостановленные отчёты тоже учитываются.

**frequency** `string` *required*

Как часто отправляется отчёт: `daily`, `weekly` или `monthly`. Этим же задаётся охватываемый период. См. [Период](#период).

**scope** `string` *required*

`all`, `selected` или `single`. См. [Охват](#охват).

**timezone** `string` *required*

Часовой пояс IANA, по которому выравниваются время отправки и период, например `America/New_York`. Неизвестный часовой пояс возвращает `422`.

**locale** `string` *required*

Язык письма и PDF, например `en` или `de`. При неподдерживаемом значении используется английский. PDF на `zh`, `ja`, `ko` и `ar` формируются на английском.

**qrIds** `string[]`

QR-коды, которые нужно включить. Обязательно для `selected` (один или несколько ID) и `single` (ровно один ID). Каждый ID должен быть QR-кодом вашего рабочего пространства, иначе запрос возвращает `404`.

**name** `string`

Название, которое отображается в теме письма и в панели управления, до 40 символов.

**includePdf** `boolean` (default: false)

Прикладывать к письму PDF-версию отчёта.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/reports/schedules" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly campaign digest",
    "frequency": "weekly",
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "includePdf": true,
    "timezone": "America/New_York",
    "locale": "en"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Weekly campaign digest",
  "frequency": "weekly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-08-10T04:00:00.000Z",
  "lastRunAt": null,
  "createdAt": "2026-08-03T12:34:56.000Z",
  "updatedAt": "2026-08-03T12:34:56.000Z"
}
```

## Обновление запланированного отчёта

`PATCH /api/v1/reports/schedules/{id}`

Изменяет запланированный отчёт или приостанавливает и возобновляет его. Передавайте только поля, которые хотите изменить, но хотя бы одно. Изменение частоты или часового пояса, а также возобновление приостановленного отчёта пересчитывает `nextRunAt`. Правило «один отчёт на частоту» продолжает действовать, поэтому пересекающееся изменение возвращает `409`.

**id** `string` *required*

ID запланированного отчёта. Возьмите его из ответа на запрос списка или создания.

**status** `string`

`paused` останавливает отправку писем, не удаляя расписание. `active` возобновляет её.

**name** `string`

Название, до 40 символов.

**frequency** `string`

`daily`, `weekly` или `monthly`.

**scope** `string`

`all`, `selected` или `single`.

**qrIds** `string[]`

QR-коды, которые нужно включить. Каждый ID должен быть QR-кодом вашего рабочего пространства.

**includePdf** `boolean`

Прикладывать к письму PDF.

**timezone** `string`

Часовой пояс IANA.

**locale** `string`

Язык письма и PDF.

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly campaign digest",
    "frequency": "monthly",
    "status": "active"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Monthly campaign digest",
  "frequency": "monthly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-09-01T04:00:00.000Z",
  "lastRunAt": "2026-08-03T04:00:12.000Z",
  "createdAt": "2026-07-01T12:34:56.000Z",
  "updatedAt": "2026-08-05T10:15:00.000Z"
}
```

## Удаление запланированного отчёта

`DELETE /api/v1/reports/schedules/{id}`

Удаляет расписание и прекращает все дальнейшие письма.

> [!WARNING]
>
> Удаление запланированного отчёта нельзя отменить.

**id** `string` *required*

ID запланированного отчёта.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{ "id": "clx8f2k9a0001qk0c8vhd3xyz", "deleted": true }
```

## Частые проблемы

> [accordion] 404 при экспорте отчёта
>
> С охватом `selected` или `single` ни один из `qrIds` не совпал с QR-кодом с короткой ссылкой в вашем рабочем пространстве. Проверьте ID.

> [accordion] 404 "QR not found." при планировании отчёта
>
> Один из `qrIds` не является QR-кодом вашего рабочего пространства или был удалён. Проверьте ID через [Список QR-кодов](https://docs.getqr.com/ru/api/endpoints/qr-codes.md).

> [accordion] 409 при планировании отчёта
>
> Один из QR-кодов уже входит в запланированный отчёт с той же частотой, или отчёт с этой частотой использует охват `all`. Измените или удалите тот отчёт либо выберите другую частоту.

> [accordion] 404 "Scheduled report not found."
>
> `id` не совпадает ни с одним запланированным отчётом вашего рабочего пространства. Возьмите его из [Списка запланированных отчётов](#список-запланированных-отчётов).

> [accordion] В отчёте нет сегодняшних сканирований
>
> Отчёты охватывают только последний завершённый период. Для актуальных цифр используйте [Аналитику](https://docs.getqr.com/ru/api/endpoints/analytics.md).

## Что дальше

> [card] [Аналитика](https://docs.getqr.com/ru/api/endpoints/analytics.md)

> [card] [Запланированные отчёты в приложении](https://docs.getqr.com/ru/analytics/scheduled-reports.md)

> [card] [Чтение отчётов](https://docs.getqr.com/ru/analytics/reading-reports.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.