API kodów QR: automatyczne tworzenie, zmienianie i analizowanie kodów QR

Do czego służy API kodów QR

API kodów QR to interfejs programistyczny: zamiast klikać w przeglądarce, twój program wysyła zapytania do usługi kodów QR i dostaje odpowiedzi. Dzięki temu kody QR powstają bezpośrednio ze sklepu, systemu magazynowego, skryptu albo arkusza.

Opłaca się to, gdy tylko praca zaczyna się powtarzać: sto kodów QR do stolików lub produktów, miesięczne raporty skanów, zmiana wielu celów po relaunchu. Działa to tylko z dynamicznymi kodami QR. Dynamiczny kod QR od Same-QR zawiera krótki, niezmienny adres, a cel kryjący się za nim leży u nas i można go zmienić w każdej chwili, bez ponownego drukowania.

Co obejmuje API Same-QR

API REST znajdziesz pod adresem https://sameqr.com/api/v1. Wywołuje te same funkcje co panel, z tymi samymi limitami planów i tymi samymi kontrolami:

• Wyświetlanie, odczyt, tworzenie, zmienianie i usuwanie kodów QR.
• Statystyki kodu QR: skany, data utworzenia, liczba zmian celu.
• Tworzenie, zmienianie, publikowanie i wyłączanie stron gościnnych, takich jak karta dań, cennik, godziny otwarcia, strona z linkami, promocja, winnica, e-etykieta wina i kontakt.
• Wczytanie karty dań z maksymalnie siedmiu zdjęć albo z pliku PDF.
• Zarządzanie etykietami i projektami klientów oraz odczyt zapytań z formularzy kontaktowych.

Opis wszystkich zapytań w formie czytelnej dla maszyn znajdziesz pod /api/v1/openapi.json, a instrukcję na sameqr.com/entwickler.

Klucze API i uprawnienia

Klucz tworzysz w panelu w sekcji Konto, w części „Dostęp dla CLI, skryptów i agentów“. Wybierasz jeden z trzech poziomów: „tylko odczyt“, „odczyt + zapis“ (tworzenie, zmiana nazw i tekstów) albo „pełny“ (dodatkowo zmiana celów, wyłączanie i usuwanie), a także okres ważności 30, 90, 180 lub 365 dni, a w razie potrzeby także bez ograniczeń. Klucz zaczyna się od sqr_live_ i jest wyświetlany dokładnie raz. U nas zapisywana jest tylko suma kontrolna.

Klucz, który może tylko czytać, przy każdym zapytaniu zmieniającym dane dostaje jednoznaczną odmowę. Do raportów i analiz to właściwy wybór. Wszystko, co zmienia miejsce, do którego prowadzi wydrukowany kod QR, jest dodatkowo chronione: zmiana celu, wyłączenie i usunięcie wymagają poziomu „pełny“ oraz potwierdzenia za pomocą wcześniej odczytanego stanu, a przez API można wykonać takich operacji najwyżej 10 na godzinę i 30 na dobę. W panelu tego limitu nie ma. Każdy klucz możesz w każdej chwili unieważnić i wtedy przestaje działać natychmiast.

Typowy przebieg

Klucz należy do nagłówka Authorization, nigdy do adresu. Wcześniej zapisz klucz jako zmienną środowiskową. W ten sposób wyświetlisz swoje kody QR i zmienisz cel jednego kodu QR:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr

curl -X PATCH https://sameqr.com/api/v1/qr/<id> \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -H "X-Confirm: <stand>" \
  -d '{"targetUrl":"https://example.com/karte-neu"}'

Wartość dla X-Confirm, czyli stan, zwraca zapytanie odczytujące na /api/v1/qr/<id>. Zmieniane jest tylko to, co wyślesz. Kto chce mieć pewność, że nikt w międzyczasie nie zmienił tego samego kodu QR, wysyła odczytany stan jako _rev. Jeśli coś się zmieniło, nic nie zostanie nadpisane, a odpowiedź zawiera aktualny stan. Błędy zawsze wracają w tym samym formacie, ze statusem, kodem QR i zrozumiałym komunikatem.

Limity i dobre praktyki

Na jeden klucz przypada najwyżej 120 zapytań na minutę. Do tego dochodzi limit na godzinę, zależny od planu: 60 w planie bezpłatnym, 300 w Start, 1.000 w Pro i 5.000 w Agentur. Limity wychwytują błędy, na przykład skrypt w nieskończonej pętli, i nie przeszkadzają w uczciwym korzystaniu.

• Najpierw wypróbuj z kluczem do odczytu, dopiero potem zapisuj.
• Nowe procesy testuj na jednym kodzie QR i skanuj go telefonem.
• Unikaj usuwania tam, gdzie wystarczy nowy cel. Usunięte kody QR i ich krótkie linki nie wracają.
• Dla każdego programu utwórz osobny klucz i trzymaj go w menedżerze haseł albo w zmiennej środowiskowej.

Podsumowanie: dlaczego Same-QR

Same-QR nie daje ci API jako drogiego dodatku, tylko w każdym planie, z tymi samymi funkcjami co w panelu: kody QR, statystyki, karty dań, strony gościnne, etykiety i projekty. Do tego jasne uprawnienia dla każdego klucza, uczciwe komunikaty o błędach i nocna kontrola wszystkich celów, która wysyła ci e-mail, gdy któryś jest nieosiągalny.

Zacznij od razu: zarejestruj się bezpłatnie na sameqr.com, 20 dynamicznych kodów QR jest na stałe za darmo. API, CLI i serwer MCP są w każdym planie, a dokumentacja znajduje się na sameqr.com/entwickler.

Najczęściej zadawane pytania