Tworzenie kodu QR przez REST API: instrukcja z przykładami curl

Krok 1: utwórz klucz

W panelu w sekcji Konto, w części „Dostęp dla CLI, skryptów i agentów”, tworzysz klucz. Na pierwsze próby wystarczy „tylko odczyt”. Wybierz krótki okres ważności, na przykład 30 dni. Klucz zaczyna się od sqr_live_ i jest pokazywany tylko raz. Zapisz go jako zmienną środowiskową, żeby nie trafił do historii powłoki, na przykład przez menedżer haseł.

Krok 2: pierwsze zapytanie

API znajduje się pod adresem https://sameqr.com/api/v1. Klucz należy do nagłówka Authorization, nigdy do adresu:

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

Pierwsze zapytanie pokazuje twoje konto, taryfę i limity, drugie twoje kody QR z identyfikatorem, nazwą, celem, etykietami, liczbą skanowań i stanem _rev.

Krok 3: załóż kod QR

Do zakładania potrzebujesz drugiego klucza z uprawnieniem „odczyt + zapis”. Przy kluczu tylko do odczytu API odpowiada na zapytania zmieniające dane kodem 403 i kodem błędu NUR_LESEN. Nowy kod QR potrzebuje przynajmniej nazwy i celu:

curl -X POST https://sameqr.com/api/v1/qr \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Speisekarte","targetUrl":"https://example.com/karte"}'

Zanim pójdziesz dalej, zeskanuj nowy kod QR telefonem. Do zakładania twój adres e-mail musi być potwierdzony, a kod QR wlicza się do limitu twojej taryfy.

Krok 4: zmień cel

Zmiany celu są szczególnie chronione. Potrzebujesz klucza „pełny” i wysyłasz aktualny stan kodu QR w nagłówku X-Confirm. Stan podaje zapytanie odczytu:

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

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

Zmieniane są tylko wysłane pola. Jeśli stan się różni, bo ktoś w międzyczasie zmienił kod QR, nic nie zostanie nadpisane. Przez API możliwych jest najwyżej 10 zmian celu na godzinę i 30 na dobę, w panelu tego limitu nie ma. W taryfie bezpłatnej liczba zmian celu na kod QR jest ograniczona.

Krok 5: zrozum błędy i limity

Błędy wracają zawsze w tej samej formie: obiekt error ze statusem, kodem i komunikatem. Obsłuż je w swoim programie, zamiast po prostu iść dalej.

• 401: klucza brakuje, jest błędny, wygasł lub został unieważniony.
• 403: kluczowi brakuje potrzebnego poziomu albo twoja taryfa nie pozwala na tę akcję.
• 400 z BESTAETIGUNG_FEHLT: przy zmianie celu, wyłączeniu lub usunięciu brakuje X-Confirm z aktualnym stanem.
• 409: ktoś w międzyczasie zmienił kod QR.
• 429: za dużo zapytań. Na klucz przypada 120 na minutę, na godzinę 60 w taryfie bezpłatnej, 300 w Start, 1.000 w Pro i 5.000 w Agentur.

Wszystkie zapytania opisuje /api/v1/openapi.json, instrukcja jest na sameqr.com/entwickler.

Podsumowanie: dlaczego Same-QR

REST API Same-QR jest uporządkowane, dobrze udokumentowane i dostępne w każdej taryfie. Potrafi wszystko, co panel, chroni wydrukowane kody QR potwierdzeniem i limitami przed przypadkową zmianą celu, pozwala na klucze w trzech poziomach i odpowiada błędami, które da się zrozumieć.

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

Najczęściej zadawane pytania