Dla programistów
Dokumentacja API i integracji
Wszystko, czego potrzebujesz, aby wywoływać Business API, zarządzać kluczami i odbierać webhooki.
Uwierzytelnianie
Business API uwierzytelnia każde żądanie kluczem API. Przekaż go w nagłówku X-Api-Key lub jako token Bearer w nagłówku Authorization.
Klucze mają prefiks qrg_ i są wyświetlane tylko raz, przy tworzeniu. Przechowuj je bezpiecznie — później nie da się ponownie odczytać klucza.
Żądania bez prawidłowego klucza zwracają 401. Klucz bez wymaganego uprawnienia otrzymuje 403 z błędem insufficient_scope. Zasoby spoza Twojego obszaru roboczego zwracają 404, jakby nie istniały.
Bazowy URL
Wszystkie endpointy Business API znajdują się pod prefiksem /v1.
Na przykład listę swoich kodów QR pobierzesz pod adresem https://qr-global.com/api/v1/qr-codes.
- Bieżący bazowy URL
- https://qr-global.com
Endpointy
Wszystkie endpointy znajdują się pod /api/v1 i wymagają klucza z podanym uprawnieniem.
| Metoda | Ścieżka | Uprawnienie | Co robi |
|---|---|---|---|
| GET | /qr-codes | qr:read | Lista kodów QR (filtry: type, search, folder_id, tag, archived) |
| POST | /qr-codes | qr:write | Utwórz kod QR |
| POST | /qr-codes/bulk | qr:write | Utwórz do 100 kodów QR naraz |
| GET | /qr-codes/{id} | qr:read | Pobierz jeden kod QR |
| PUT | /qr-codes/{id} | qr:write | Zaktualizuj kod QR, jego folder i tagi |
| DELETE | /qr-codes/{id} | qr:write | Usuń kod QR |
| GET | /qr-codes/{id}/image | qr:read | Wygeneruj obraz (PNG lub SVG) |
| GET | /qr-codes/{id}/stats | analytics:read | Statystyki skanowań |
| GET | /qr-codes/{id}/scans | analytics:read | Dziennik skanowań |
| GET | /folders | qr:read | Lista folderów |
| GET | /tags | qr:read | Lista tagów |
| GET | /webhooks | webhooks:manage | Lista subskrypcji webhooków |
| POST | /webhooks | webhooks:manage | Subskrybuj zdarzenia |
| DELETE | /webhooks/{id} | webhooks:manage | Anuluj subskrypcję |
Opis do odczytu maszynowego (OpenAPI 3.1) dla narzędzi takich jak Postman, generatory kodu i platformy no-code: Pobierz openapi.json
Klucze API
Twórz i unieważniaj klucze na stronie Klucze API w swoim panelu.
Każdy klucz należy do Twojego obszaru roboczego i dziedziczy limit zapytań Twojego planu.
Unieważnienie klucza działa natychmiast.
Uprawnienia (scopes)
Tworząc klucz, nadaj mu pełny dostęp albo tylko uprawnienia potrzebne integracji. Klucz bez uprawnienia otrzymuje 403 z błędem insufficient_scope i polem required_scope w odpowiedzi.
qr:read— Odczyt kodów QR- Lista i podgląd kodów QR, ich obrazów, folderów i tagów.
qr:write— Zarządzanie kodami QR- Tworzenie kodów QR (także masowe), edycja, przenoszenie między folderami, tagowanie i usuwanie.
analytics:read— Odczyt analityki- Statystyki skanowań i dziennik skanowań każdego kodu QR.
webhooks:manage— Zarządzanie webhookami- Subskrybowanie zdarzeń przez endpointy i anulowanie subskrypcji (Zapier, Make).
Klucze utworzone przed wprowadzeniem uprawnień zachowują pełny dostęp. Pełny dostęp obejmuje też uprawnienia dodane w przyszłości.
Przykłady
Gotowe polecenia curl do skopiowania na start. Zastąp YOUR_API_KEY kluczem ze strony Klucze API.
Lista kodów QR
curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \ "https://qr-global.com/api/v1/qr-codes"
Utwórz kod QR
Wyślij typ QR i treść — serwer wygeneruje i zapisze kod.
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"}'Wygeneruj obraz
Pobierz gotowy plik PNG lub SVG — przekaż ?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
Przykładowy payload webhooka
{
"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"
}
}Analityka skanów
GET /qr-codes/{id}/stats zwraca sumy, unikalnych odwiedzających, najczęstsze kraje, urządzenia, przeglądarki i skany dziennie. GET /qr-codes/{id}/scans zwraca dziennik skanowań od najnowszych, po 50 na stronę (per_page do 100).
Oba przyjmują from i to (datę, np. 2026-10-01, lub pełny znacznik czasu) oraz timezone (domyślnie UTC). Data bez godziny obejmuje cały dzień w tej strefie czasowej.
Dostępna jest tylko historia z okresu przewidzianego w Twoim planie: starsze skany są usuwane. Adresy IP i dane User-Agent odwiedzających nigdy nie są zwracane.
Statystyki skanowań za okres
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"
Dziennik skanowań, druga strona
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"
Foldery i tagi
GET /folders i GET /tags zwracają foldery i tagi Twojego obszaru roboczego. Przekaż folder_id i tags (slugi tagów) przy tworzeniu lub aktualizacji kodu QR: folder_id null wyjmuje kod z folderu, a tags zastępuje cały zestaw.
Filtruj listę kodów QR za pomocą ?folder_id= lub ?tag=.
Przenieś kod QR do folderu i oznacz go tagami
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"
]
}'Masowe tworzenie
POST /qr-codes/bulk tworzy do 100 kodów QR w jednym żądaniu. Wymaga planu z masowym tworzeniem, tak jak import CSV w panelu, i uwzględnia Twój limit aktywnych kodów QR.
Każdy element jest przetwarzany osobno: odpowiedź zawiera każdy element ze statusem created (i nowym kodem) lub failed (z error i errors). Nie wysyłaj ponownie całej paczki, tylko elementy zakończone błędem.
Utwórz dwa kody 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
}
]
}'Subskrypcje webhooków (REST hooks)
Zapier, Make i Twoje własne usługi mogą subskrybować zdarzenia przez API: POST /webhooks z url i events, a DELETE /webhooks/{id}, aby anulować subskrypcję. To te same endpointy, które widzisz na stronie Webhooki.
Odpowiedź na POST zawiera secret, wyświetlany tylko raz: użyj go do weryfikacji nagłówka X-Webhook-Signature. Jeśli nie przekażesz własnego secret (co najmniej 16 znaków), wygenerujemy go.
Zdarzenia: qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted. Subskrypcja wymaga planu z webhookami; anulowanie działa zawsze. Limit endpointów w obszarze roboczym: 25.
Subskrybuj skany
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"
]
}'Anuluj subskrypcję
curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Webhooki
Webhooki wysyłają zdarzenia do Twojego endpointu na bieżąco, więc nie musisz odpytywać API.
Skonfiguruj endpointy na stronie Webhooki w swoim panelu.
Każde dostarczenie jest podpisane, a w razie błędu ponawiane z wykładniczym opóźnieniem.
Zdarzenie scan jest wywoływane, gdy ktoś zeskanuje jeden z Twoich kodów QR.
Sprawdzaj próby dostarczenia, payloady i odpowiedzi w dzienniku dostarczeń.
Zwróć status 2xx, aby potwierdzić dostarczenie; każdy inny status jest traktowany jako błąd.
Śledzenie konwersji
Konwersje pokazują testowi A/B, który cel przynosi zamówienia lub rejestracje, a nie tylko skany. Przy włączonej automatycznej optymalizacji ruch przechodzi do wariantu z najlepszą konwersją.
Dodaj skrypt na stronie, którą odwiedzający widzi po konwersji: potwierdzenie zamówienia, strona z podziękowaniem lub sukcesu. Działa w każdej domenie i nie wymaga klucza API.
Fragment kodu
<script src="https://qr-global.com/c.js" async></script>
- Każdy skan dodaje do docelowego URL podpisany parametr qrg_v, dzięki czemu konwersja jest przypisana do kodu QR i wariantu.
- Skrypt przechowuje token w ciasteczku własnym witryny przez 30 dni, więc konwersja zostanie policzona, nawet jeśli odwiedzający najpierw przejrzy inne strony.
- Każdy skan liczy się raz: odświeżenie strony z podziękowaniem nie dodaje konwersji.
- Działa dla kodów QR, które przekierowują na stronę http(s).
Eksporty
Eksportuj swoje kody QR, skanowania, lokalizacje i aktywność do pliku CSV na stronie Eksporty.
Eksporty korzystają z sesji panelu, a nie z klucza API — otwieraj je po zalogowaniu.
Wskazówki i częste błędy
- 401 Unauthorized — brak klucza API lub jest on nieprawidłowy. Sprawdź nagłówek X-Api-Key.
- 403 Forbidden — klucz nie ma wymaganego uprawnienia (insufficient_scope) lub Twój plan nie obejmuje tej funkcji (api_access_required, bulk_not_available, webhooks_not_available).
- 404 Not Found — zasób nie istnieje lub należy do innego obszaru roboczego.
- 429 Too Many Requests — osiągnięto minutowy limit Twojego planu. Odczekaj liczbę sekund podaną w nagłówku Retry-After.
- Niektóre funkcje (np. webhooki) zależą od planu. Ulepsz plan, jeśli endpoint zwraca błąd dostępności funkcji.
- Brak dostarczeń webhooków? Zeskanuj jeden ze swoich kodów QR, aby wywołać pierwsze.
- Nieudane dostarczenia webhooków są ponawiane automatycznie; możesz też ponowić je ręcznie z dziennika dostarczeń.
- Członkowie zespołu działają w Twoim obszarze roboczym; klucze i dane są przypisane do właściciela obszaru roboczego.