Vytvoření QR kódu přes REST API: návod s příklady v curl

Krok 1: vytvoř klíč

V dashboardu v části Účet, oddíl „Přístup pro CLI, skripty a agenty“, vytvoříš klíč. Na první pokusy stačí „jen čtení“. Zvol krátkou platnost, třeba 30 dní. Klíč začíná sqr_live_ a zobrazí se jen jednou. Ulož ho do proměnné prostředí, aby nezůstal v historii tvého shellu, například přes správce hesel.

Krok 2: první dotaz

API je na https://sameqr.com/api/v1. Klíč patří do hlavičky Authorization, nikdy do adresy:

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

První dotaz ukáže tvůj účet, tarif a limity, druhý tvé QR kódy s identifikátorem, názvem, cílem, štítky, počtem skenů a stavem _rev.

Krok 3: založ QR kód

Na vytváření potřebuješ druhý klíč s úrovní „čtení + zápis“. S klíčem pro čtení odpoví API na požadavky, které něco mění, kódem 403 a kódem NUR_LESEN. Nový QR kód potřebuje minimálně název a cíl:

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

Než budeš pokračovat, naskenuj nový QR kód mobilem. Na vytváření musí být potvrzená tvoje e-mailová adresa a QR kód se počítá do kvóty tvého tarifu.

Krok 4: změň cíl

Změny cíle jsou chráněné obzvlášť. Potřebuješ klíč s úrovní „plný“ a aktuální stav QR kódu pošleš jako hlavičku X-Confirm. Stav vrací dotaz na čtení:

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

Změní se jen pole, která pošleš. Pokud se stav liší, protože QR kód mezitím někdo změnil, nic se nepřepíše. Přes API jde nejvýše 10 změn cíle za hodinu a 30 za den, v dashboardu tento limit není. V bezplatném tarifu je počet změn cíle na jeden QR kód omezený.

Krok 5: pochop chyby a limity

Chyby se vracejí vždy ve stejné podobě: objekt error s položkami status, code a message. Vyhodnocuj je ve svém programu, místo abys prostě pokračoval dál.

• 401: klíč chybí, je špatný, vypršel nebo byl odvolán.
• 403: klíči chybí potřebná úroveň, nebo tvůj tarif akci nepovoluje.
• 400 s BESTAETIGUNG_FEHLT: u změny cíle, vypnutí nebo smazání chybí X-Confirm s aktuálním stavem.
• 409: někdo QR kód mezitím změnil.
• 429: příliš mnoho požadavků. Na jeden klíč jde 120 za minutu, za hodinu 60 v bezplatném tarifu, 300 ve Startu, 1.000 v Pro a 5.000 v Agentuře.

Všechny požadavky popisuje /api/v1/openapi.json, návod najdeš na sameqr.com/entwickler.

Závěr: proč Same-QR

REST API od Same-QR je přehledné, dobře zdokumentované a je součástí každého tarifu. Zvládne všechno, co dashboard, chrání vytištěné QR kódy potvrzením a limity před nechtěnými změnami cíle, nabízí klíče ve třech úrovních a odpovídá chybami, kterým se rozumí.

Začni hned: zaregistruj se zdarma na sameqr.com, 20 dynamických QR kódů je trvale zdarma. API, CLI a server MCP jsou v každém tarifu, dokumentace je na sameqr.com/entwickler.

Často kladené otázky