API pro QR kódy: automaticky vytvářej, měň a vyhodnocuj QR kódy

K čemu je API pro QR kódy

API pro QR kódy je programovací rozhraní: místo klikání v prohlížeči posílá tvůj program požadavky službě pro QR kódy a dostává odpovědi. QR kódy tak vznikají přímo z e-shopu, skladového systému, skriptu nebo tabulky.

Vyplatí se to, jakmile se práce opakuje: sto QR kódů pro stoly nebo produkty, měsíční zprávy o skenech, přepnutí mnoha cílů po redesignu webu. A funguje to jen s dynamickými QR kódy. Dynamický QR kód od Same-QR obsahuje krátkou, neměnnou adresu, cíl za ní je uložený u nás a dá se kdykoli změnit, aniž bys musel znovu tisknout.

Co API od Same-QR pokrývá

REST API najdeš na https://sameqr.com/api/v1. Volá stejné funkce jako dashboard, se stejnými limity tarifů a stejnými kontrolami:

• Vypisovat, číst, vytvářet, měnit a mazat QR kódy.
• Statistika QR kódu: skeny, datum vytvoření, počet změn cíle.
• Stránky pro hosty, například jídelní lístek, ceník, otevírací doba, stránka s odkazy, akce, vinařství, vinný E-label a kontakt vytvářet, měnit, publikovat a stahovat z provozu.
• Načíst jídelní lístek až ze sedmi fotek nebo z PDF.
• Spravovat štítky a zákaznické projekty a číst dotazy z kontaktních formulářů.

Strojově čitelný popis všech požadavků je na /api/v1/openapi.json, návod na sameqr.com/entwickler.

Klíče API a oprávnění

Klíč vytvoříš v dashboardu v části Účet, oddíl „Přístup pro CLI, skripty a agenty“. Vybereš jednu ze tří úrovní, „jen čtení“, „čtení + zápis“ (vytvářet, měnit názvy a texty) nebo „plná“ (navíc měnit cíle, stahovat z provozu, mazat), a platnost 30, 90, 180 nebo 365 dnů, v případě potřeby i neomezenou. Klíč začíná na sqr_live_ a zobrazí se právě jednou. U nás se ukládá jen kontrolní součet.

Klíč, který smí jen číst, dostane na každý požadavek, který něco mění, jasné odmítnutí. Pro zprávy a vyhodnocení je to správná volba. Všechno, co mění, kam vede vytištěný QR kód, je navíc chráněno: změny cíle, stažení z provozu a smazání vyžadují úroveň „plná“ a potvrzení dříve přečteným stavem a přes API jich projde nejvýše 10 za hodinu a 30 za den. V dashboardu tento limit není. Každý klíč můžeš kdykoli odvolat a hned přestane platit.

Typický postup

Klíč patří do hlavičky Authorization, nikdy do adresy. Klíč si předem ulož do proměnné prostředí. Takto vypíšeš své QR kódy a změníš cíl jednoho QR kódu:

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

Hodnotu pro X-Confirm, tedy stav, vrátí čtecí požadavek na /api/v1/qr/<id>. Změní se jen to, co pošleš. Kdo chce mít jistotu, že mezitím nikdo jiný stejný QR kód neupravil, pošle přečtený stav jako _rev. Pokud se něco změnilo, nic se nepřepíše a odpověď obsahuje aktuální stav. Chyby se vracejí vždy ve stejném formátu, se stavem, QR kódem a srozumitelnou zprávou.

Limity a dobrá praxe

Na jeden klíč připadá nejvýše 120 požadavků za minutu. K tomu přichází limit za hodinu, který závisí na tarifu: 60 v bezplatném tarifu, 300 ve Start, 1.000 v Pro a 5.000 v Agentur. Limity zachytí chyby, například skript v nekonečné smyčce, a poctivému používání nepřekážejí.

• Nejdřív zkus čtecí klíč, teprve potom zapisuj.
• Nové postupy testuj na jednom QR kódu a naskenuj ho mobilem.
• Mazání nepoužívej tam, kde stačí nový cíl. Smazané QR kódy a jejich krátké odkazy se nevrátí.
• Pro každý program vytvoř vlastní klíč a uchovávej ho ve správci hesel nebo v proměnné prostředí.

Závěr: Proč Same-QR

Same-QR ti API nedává jako drahý doplněk, ale v každém tarifu, se stejnými funkcemi jako dashboard: QR kódy, statistiky, jídelní lístky, stránky pro hosty, štítky a projekty. K tomu jasná oprávnění pro každý klíč, poctivá chybová hlášení a noční kontrola všech cílů, která ti e-mailem oznámí, když některý není dostupný.

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