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

Звіти підсумовують сканування кожного 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/ua/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/ua/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/ua/api/endpoints/qr-codes.md).

> [accordion] 409 під час планування звіту
>
> Один із QR-кодів уже входить до запланованого звіту з тією самою частотою, або звіт цієї частоти використовує охоплення `all`. Змініть або видаліть той звіт чи виберіть іншу частоту.

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

> [accordion] У звіті немає сьогоднішніх сканувань
>
> Звіти охоплюють лише останній завершений період. Для актуальних чисел використовуйте [Аналітику](https://docs.getqr.com/ua/api/endpoints/analytics.md).

## Що далі

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

> [card] [Заплановані звіти в застосунку](https://docs.getqr.com/ua/analytics/scheduled-reports.md)

> [card] [Читання звітів](https://docs.getqr.com/ua/analytics/reading-reports.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.