Отчёты

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"
  }'

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

{
  "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"
    }
  ]
}

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"
  }'

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

{
  "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"
    }
  ]
}

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}`	Удаление запланированного отчёта

Заголовки

string

обязательно

Bearer и ваш API-ключ. См. Аутентификация.

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 Формирует отчёт за последний завершённый период и возвращает его в ответе.

string

обязательно

all, selected или single. См. Охват.

string

обязательно

daily, weekly или monthly. См. Период.

string

обязательно

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

string[]

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

string

по умолчанию:"UTC"

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

string

по умолчанию:"en"

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

string

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

Ответ в JSON

string

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

string

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

object[]

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

Показать properties

string

ID QR-кода.

string

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

string

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

integer

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

integer

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

string

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

string

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

string

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

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.

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"
  }'

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

{
  "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"
    }
  ]
}

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

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

string

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

string | null

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

string

daily, weekly или monthly.

string

all, selected или single.

string[] | null

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

null

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

boolean

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

string

active или paused.

string

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

string

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

string

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

string | null

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

string

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

string

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

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

GET /api/v1/reports/schedules Возвращает запланированные отчёты вашего рабочего пространства, включая созданные другими участниками, начиная с самых новых. Список постраничный: см. Пагинация.

integer

по умолчанию:"1"

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

integer

по умолчанию:"100"

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

curl "https://getqr.com/api/v1/reports/schedules?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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 рассчитывается по частоте и часовому поясу.

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

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

string

обязательно

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

string

обязательно

all, selected или single. См. Охват.

string

обязательно

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

string

обязательно

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

string[]

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

string

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

boolean

по умолчанию:"false"

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

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"
  }'

{
  "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.

string

обязательно

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

string

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

string

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

string

daily, weekly или monthly.

string

all, selected или single.

string[]

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

boolean

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

string

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

string

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

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"
  }'

{
  "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} Удаляет расписание и прекращает все дальнейшие письма.

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

string

обязательно

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

curl -X DELETE "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "clx8f2k9a0001qk0c8vhd3xyz", "deleted": true }

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

404 при экспорте отчёта

С охватом selected или single ни один из qrIds не совпал с QR-кодом с короткой ссылкой в вашем рабочем пространстве. Проверьте ID.

404 "QR not found." при планировании отчёта

Один из qrIds не является QR-кодом вашего рабочего пространства или был удалён. Проверьте ID через Список QR-кодов.

409 при планировании отчёта

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

404 "Scheduled report not found."

id не совпадает ни с одним запланированным отчётом вашего рабочего пространства. Возьмите его из Списка запланированных отчётов.

В отчёте нет сегодняшних сканирований

Отчёты охватывают только последний завершённый период. Для актуальных цифр используйте Аналитику.

API

Заголовки

Охват

Период

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

Ответ в JSON

Ответы в CSV и PDF

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

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

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

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

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

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

Что дальше

Аналитика

Запланированные отчёты в приложении

Чтение отчётов

Ошибки

​Заголовки

​Охват

​Период

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

​Ответ в JSON

​Ответы в CSV и PDF

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

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

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

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

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

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

​Что дальше

Аналитика

Запланированные отчёты в приложении

Чтение отчётов

Ошибки

Заголовки

Охват

Период

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

Ответ в JSON

Ответы в CSV и PDF

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

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

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

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

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

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

Что дальше