Розробникам
Довідка з API та інтеграцій
Усе потрібне, щоб викликати Business API, керувати ключами та отримувати вебхуки.
Автентифікація
Business API автентифікує кожен запит API-ключем. Передавайте його в заголовку X-Api-Key або як Bearer-токен у заголовку Authorization.
Ключі мають префікс qrg_ і показуються лише раз під час створення. Зберігайте їх безпечно — повторно отримати ключ неможливо.
Запит без дійсного ключа отримує 401. Ключ без потрібного дозволу отримує 403 з помилкою insufficient_scope. Ресурси поза вашим воркспейсом повертають 404 — так, ніби їх не існує.
Базовий URL
Усі ендпойнти Business API живуть під префіксом /v1.
Наприклад, список ваших QR-кодів — за адресою https://qr-global.com/api/v1/qr-codes.
- Розв'язаний базовий URL
- https://qr-global.com
Ендпоінти
Усі ендпоінти — під /api/v1, і кожному потрібен ключ із зазначеним дозволом.
| Метод | Шлях | Дозвіл | Що робить |
|---|---|---|---|
| GET | /qr-codes | qr:read | Список QR-кодів (фільтри: type, search, folder_id, tag, archived) |
| POST | /qr-codes | qr:write | Створити QR-код |
| POST | /qr-codes/bulk | qr:write | Створити до 100 QR-кодів за раз |
| GET | /qr-codes/{id} | qr:read | Отримати один QR-код |
| PUT | /qr-codes/{id} | qr:write | Оновити QR-код, його папку й теги |
| DELETE | /qr-codes/{id} | qr:write | Видалити QR-код |
| GET | /qr-codes/{id}/image | qr:read | Зображення коду (PNG або SVG) |
| GET | /qr-codes/{id}/stats | analytics:read | Статистика сканувань |
| GET | /qr-codes/{id}/scans | analytics:read | Журнал сканувань |
| GET | /folders | qr:read | Список папок |
| GET | /tags | qr:read | Список тегів |
| GET | /webhooks | webhooks:manage | Список підписок на вебхуки |
| POST | /webhooks | webhooks:manage | Підписатися на події |
| DELETE | /webhooks/{id} | webhooks:manage | Відписатися |
Машиночитний опис (OpenAPI 3.1) для Postman, генераторів коду й no-code-інструментів: Завантажити openapi.json
API-ключі
Створюйте та відкликайте ключи на сторінці API-ключів у кабінеті.
Кожен ключ належить вашому воркспейсу й успадковує ліміт запитів вашого плану.
Відкликання ключа набуває чинності негайно.
Дозволи (скоупи)
Створюючи ключ, дайте йому повний доступ або лише ті дозволи, які потрібні інтеграції. Ключ без дозволу отримує 403 з помилкою insufficient_scope і полем required_scope у відповіді.
qr:read— Читання QR-кодів- Список і перегляд QR-кодів, їхніх зображень, папок і тегів.
qr:write— Керування QR-кодами- Створення QR-кодів (зокрема масове), редагування, перенесення між папками, теги й видалення.
analytics:read— Читання аналітики- Статистика й журнал сканувань кожного QR-коду.
webhooks:manage— Керування вебхуками- Підписка адрес на події та відписка (Zapier, Make).
Ключі, створені до появи дозволів, зберігають повний доступ. Повний доступ охоплює й дозволи, що з’являться пізніше.
Приклади
Готові curl-команди для старту. Замініть YOUR_API_KEY на ключ зі сторінки API-ключів.
Список QR-кодів
curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \ "https://qr-global.com/api/v1/qr-codes"
Створити QR-код
Надішліть тип і вміст QR; сервер згенерує та збереже код.
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"url","content":"https://example.com","display_name":"Example link"}'Отримати зображення
Завантажте готовий PNG або SVG — параметри ?format=png
curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=png&size=512" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.png # SVG (vector, no size limit on scale): curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=svg" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.svg
Приклад payload вебхука
{
"event": "qr.scan.created",
"timestamp": "2026-04-03T12:00:00+00:00",
"data": {
"qr_code_id": 7,
"qr_code_uuid": "9b2f0c1e-4d4a-4f7e-9a51-2a7c3c1d8e10",
"type": "url",
"scan_id": 42,
"country": "UA",
"device_type": "mobile",
"scanned_at": "2026-04-03T12:00:00+00:00"
}
}Аналітика сканувань
GET /qr-codes/{id}/stats повертає підсумки, унікальних відвідувачів, топ країн, пристрої, браузери й скани по днях. GET /qr-codes/{id}/scans повертає журнал сканувань від найновіших, по 50 на сторінку (per_page — до 100).
Обидва приймають from і to (дату на кшталт 2026-10-01 або повну позначку часу) і timezone (за замовчуванням UTC). Дата без часу — це весь день у цьому поясі.
Доступна лише історія за вікном вашого тарифу: старіші скани видаляються. IP-адреси й User-Agent відвідувачів не повертаються ніколи.
Статистика сканувань за період
curl -sS "https://qr-global.com/api/v1/qr-codes/123/stats?from=2026-10-01&to=2026-10-31&timezone=Europe/Kyiv" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Журнал сканувань, друга сторінка
curl -sS "https://qr-global.com/api/v1/qr-codes/123/scans?per_page=100&page=2" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Папки й теги
GET /folders і GET /tags повертають папки й теги вашого воркспейсу. Передавайте folder_id і tags (slug-и тегів), коли створюєте чи оновлюєте QR-код: folder_id null виймає код із папки, а tags замінює весь набір.
Фільтруйте список QR-кодів через ?folder_id= або ?tag=.
Перенести QR-код у папку й позначити тегами
curl -sS -X PUT "https://qr-global.com/api/v1/qr-codes/123" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"folder_id": 4,
"tags": [
"campaign",
"priority"
]
}'Масове створення
POST /qr-codes/bulk створює до 100 QR-кодів одним запитом. Потрібен тариф із масовим створенням — як для CSV-імпорту в кабінеті, — і враховується ліміт активних QR-кодів.
Кожен елемент обробляється окремо: у відповіді є кожен елемент зі статусом created (і новим кодом) або failed (з error і errors). Не надсилайте весь пакет повторно — лише невдалі елементи.
Створити два QR-коди
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes/bulk" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"codes": [
{
"type": "url",
"content": "https://example.com/spring",
"display_name": "Spring flyer",
"tags": [
"campaign"
]
},
{
"type": "url",
"content": "https://example.com/menu",
"display_name": "Table menu",
"folder_id": 4
}
]
}'Підписки на вебхуки (REST hooks)
Zapier, Make і ваші сервіси можуть підписуватися на події через API: POST /webhooks з url і events, а DELETE /webhooks/{id} — щоб відписатися. Це ті самі адреси, що на сторінці «Вебхуки».
Відповідь на POST містить secret — його показано лише раз: ним перевіряйте заголовок X-Webhook-Signature. Якщо не передати власний secret (від 16 символів), ми згенеруємо його.
Події: qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted. Для підписки потрібен тариф із вебхуками; відписка працює завжди. У воркспейсі може бути до 25 адрес.
Підписатися на скани
curl -sS -X POST "https://qr-global.com/api/v1/webhooks" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"qr.scan.created"
]
}'Відписатися
curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Вебхуки
Вебхуки надсилають події на ваш ендпойнт у міру їх настання, тож не треба опитувати сервер.
Налаштуйте ендпойнти на сторінці Вебхуки у кабінеті.
Кожна доставка підписана й повторюється при збої з експоненційною затримкою.
Подія сканування спрацьовує, коли хтось сканує один з ваших QR-кодів.
Переглядайте спроби доставки, payload та відповіді в журналі доставок.
Поверніть статус 2xx, щоб підтвердити доставку; будь-який інший статус вважається збоєм.
Відстеження конверсій
Конверсії показують A/B-тесту, яка ціль приносить замовлення чи реєстрації, а не лише скани. З увімкненою авто-оптимізацією трафік переходить на варіант із найкращою конверсією.
Додайте скрипт на сторінку, яку відвідувач бачить після конверсії: підтвердження замовлення, сторінку подяки чи успіху. Він працює на будь-якому домені й не потребує API-ключа.
Сніпет
<script src="https://qr-global.com/c.js" async></script>
- Кожен скан додає до цільового URL підписаний параметр qrg_v, тож конверсія прив'язується до QR-коду й варіанта.
- Скрипт зберігає токен у cookie вашого сайту на 30 днів, тож конверсія зарахується, навіть якщо відвідувач спершу перегляне інші сторінки.
- Кожен скан рахується один раз: перезавантаження сторінки подяки не додає конверсій.
- Працює для QR-кодів, що ведуть на сторінку http(s).
Експорти
Експортуйте QR-коди, сканування, локації та активність як CSV зі сторінки Експорти.
Експорти використовують сесію кабінету, а не API-ключ — відкривайте їх залогіненими.
Поради та типові помилки
- 401 Unauthorized — ключ відсутній або недійсний. Перевірте заголовок X-Api-Key.
- 403 Forbidden — у ключа немає потрібного дозволу (insufficient_scope) або ваш тариф не містить функції (api_access_required, bulk_not_available, webhooks_not_available).
- 404 Not Found — ресурсу не існує або він належить іншому воркспейсу.
- 429 Too Many Requests — вичерпано хвилинний ліміт тарифу. Зачекайте стільки секунд, скільки вказано в заголовку Retry-After.
- Деякі функції (як-от вебхуки) залежать від плану. Оновіть план, якщо ендпойнт повертає помилку функції.
- Ще немає доставок вебхуків? Проскануйте один зі своїх QR-кодів, щоб згенерувати доставку.
- Невдалі доставки вебхуків повторюються автоматично; їх також можна повторити вручну з журналу доставок.
- Учасники команди діють у вашому воркспейсі; ключі та дані прив'язані до власника воркспейсу.