Розробникам

Довідка з API та інтеграцій

Усе потрібне, щоб викликати Business API, керувати ключами та отримувати вебхуки.

← Назад до кабінету
АвтентифікаціяБазовий URLAPI-ключіПрикладиВебхукиЕкспортиПоради та помилки

Автентифікація

Business API автентифікує кожен запит API-ключем. Передавайте його в заголовку X-Api-Key або як Bearer-токен у заголовку Authorization.

Ключі мають префікс qrg_ і показуються лише раз під час створення. Зберігайте їх безпечно — повторно отримати ключ неможливо.

Запити без дійсного ключа повертають 401. Запити до ресурсу, який вам не належить, повертають 403.

Базовий URL

Усі ендпойнти Business API живуть під префіксом /v1.

Наприклад, список ваших QR-кодів — за адресою https://qr-global.com/api/v1/qr-codes.

Розв'язаний базовий URL
https://qr-global.com

API-ключі

Створюйте та відкликайте ключи на сторінці API-ключів у кабінеті.

Кожен ключ належить вашому воркспейсу й успадковує ліміт запитів вашого плану.

Відкликання ключа набуває чинності негайно.

API-ключі

Приклади

Готові 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": {
    "scan_id": 42,
    "qr_code_id": 7,
    "scanned_at": "2026-04-03T12:00:00+00:00",
    "ip_address": "203.0.113.10",
    "device_type": "mobile"
  }
}

Вебхуки

Вебхуки надсилають події на ваш ендпойнт у міру їх настання, тож не треба опитувати сервер.

Налаштуйте ендпойнти на сторінці Вебхуки у кабінеті.

Кожна доставка підписана й повторюється при збої з експоненційною затримкою.

Подія сканування спрацьовує, коли хтось сканує один з ваших QR-кодів.

Переглядайте спроби доставки, payload та відповіді в журналі доставок.

Поверніть статус 2xx, щоб підтвердити доставку; будь-який інший статус вважається збоєм.

Доставки вебхуків
Вебхуки доступні на тарифі Бізнес. Оновіть план, щоб їх увімкнути.

Експорти

Експортуйте QR-коди, сканування, локації та активність як CSV зі сторінки Експорти.

Експорти використовують сесію кабінету, а не API-ключ — відкривайте їх залогіненими.

Експорти

Поради та типові помилки

  • 401 Unauthorized — ключ відсутній або недійсний. Перевірте заголовок X-Api-Key.
  • 403 Forbidden — ключ дійсний, але ресурс належить іншому воркспейсу.
  • Деякі функції (як-от вебхуки) залежать від плану. Оновіть план, якщо ендпойнт повертає помилку функції.
  • Ще немає доставок вебхуків? Проскануйте один зі своїх QR-кодів, щоб згенерувати доставку.
  • Невдалі доставки вебхуків повторюються автоматично; їх також можна повторити вручну з журналу доставок.
  • Учасники команди діють у вашому воркспейсі; ключі та дані прив'язані до власника воркспейсу.

Корисні посилання