QR-kód API: QR-kódok automatikus létrehozása, módosítása és kiértékelése

Mire való egy QR-kód API

A QR-kód API programozási felület: ahelyett, hogy a böngészőben kattintgatnál, a programod kéréseket küld a QR-kód szolgáltatásnak, és válaszokat kap vissza. Így jönnek létre QR-kódok közvetlenül egy webshopból, egy készletnyilvántartásból, egy szkriptből vagy egy táblázatból.

Akkor éri meg, amikor a munka ismétlődik: száz QR-kód asztalokhoz vagy termékekhez, havi beolvasási jelentések, sok cél átállítása egy újraindítás után. És csak dinamikus QR-kódokkal működik. A Same-QR dinamikus QR-kódja egy rövid, változatlan címet tartalmaz, a mögötte lévő cél nálunk van, és bármikor módosítható újranyomtatás nélkül.

Mit fed le a Same-QR API

A REST API a https://sameqr.com/api/v1 címen érhető el. Ugyanazokat a funkciókat hívja meg, mint a vezérlőpult, ugyanazokkal a csomaghatárokkal és ellenőrzésekkel:

• QR-kódok listázása, olvasása, létrehozása, módosítása és törlése.
• Egy QR-kód statisztikája: beolvasások, létrehozás dátuma, a célmódosítások száma.
• Vendégoldalak, például étlap, árlista, nyitvatartás, linkoldal, akció, borászat, bor-e-címke és kapcsolat létrehozása, módosítása, közzététele és offline állapotba helyezése.
• Étlap beolvasása legfeljebb hét fényképből vagy egy PDF-ből.
• Címkék és ügyfélprojektek kezelése, valamint a kapcsolati űrlapokból érkező kérések olvasása.

Az összes kérés géppel olvasható leírása a /api/v1/openapi.json címen van, az útmutató pedig a sameqr.com/entwickler oldalon.

API-kulcs és jogosultságok

A kulcsot a vezérlőpulton a Fiók alatt, a „Hozzáférés CLI-hez, szkriptekhez és ügynökökhöz” szakaszban hozod létre. Három szint közül választasz: „csak olvasás”, „olvasás + írás” (létrehozás, nevek és szövegek módosítása) vagy „teljes” (emellett célok módosítása, offline állapotba helyezés, törlés), valamint 30, 90, 180 vagy 365 napos érvényességet, szükség esetén korlátlant is. A kulcs sqr_live_ előtaggal kezdődik, és pontosan egyszer jelenik meg. Nálunk csak egy ellenőrző összeg kerül tárolásra.

Az a kulcs, amely csak olvashat, minden módosító kérésre egyértelmű elutasítást kap. Jelentésekhez és kiértékelésekhez ez a helyes választás. Minden, ami megváltoztatja, hová vezet egy kinyomtatott QR-kód, külön védett: a célmódosítás, az offline állapotba helyezés és a törlés a „teljes” szintet és az előzőleg beolvasott állapottal való megerősítést igényli, és ezekből az API-n keresztül óránként legfeljebb 10, naponta legfeljebb 30 mehet. A vezérlőpulton ez a korlát nincs. Minden kulcs bármikor visszavonható, és ekkor azonnal érvénytelenné válik.

Egy tipikus folyamat

A kulcs az Authorization fejlécbe való, soha nem egy címbe. A kulcsot előtte környezeti változóként teszed el. Így listázod a QR-kódjaidat, és így módosítod egy QR-kód célját:

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

Az X-Confirm értékét, az állapotot, az /api/v1/qr/<id> címre küldött olvasási kérés adja. Csak az változik, amit elküldesz. Aki biztosra akar menni, hogy közben senki sem módosította ugyanazt a QR-kódot, az olvasott állapotot _rev néven elküldi. Ha időközben bármi megváltozott, semmi sem íródik felül, és a válasz tartalmazza az aktuális állapotot. A hibák mindig ugyanabban a formátumban érkeznek, állapottal, QR-kóddal és érthető üzenettel.

Korlátok és jó gyakorlat

Kulcsonként percenként legfeljebb 120 kérés mehet. Emellett van egy óránkénti korlát, amely a csomagtól függ: 60 az ingyenes csomagban, 300 a Startban, 1.000 a Próban és 5.000 az Agenturban. A korlátok kiszűrik a hibákat, például egy végtelen ciklusban futó szkriptet, és nem zavarják a tisztességes használatot.

• Először olvasási kulccsal próbáld ki, csak utána írj.
• Az új folyamatokat egyetlen QR-kódon teszteld, és olvasd be telefonnal.
• Kerüld a törlést, ahol elég egy új cél. A törölt QR-kódok és rövid linkjeik nem térnek vissza.
• Minden programhoz hozz létre külön kulcsot, és jelszókezelőben vagy környezeti változóban tárold.

Összegzés: miért a Same-QR

A Same-QR nem drága extraként adja az API-t, hanem minden csomagban, ugyanazokkal a funkciókkal, mint a vezérlőpulton: QR-kódok, statisztika, étlapok, vendégoldalak, címkék és projektek. Ehhez jönnek a kulcsonkénti egyértelmű jogosultságok, az őszinte hibaüzenetek, és az összes cél éjszakai ellenőrzése, amely e-mailben szól, ha valamelyik nem érhető el.

Kezdj bele most: regisztrálj ingyen a sameqr.com oldalon, 20 dinamikus QR-kód tartósan ingyenes. Az API, a CLI és az MCP-szerver minden csomagban benne van, a dokumentáció a sameqr.com/entwickler oldalon van.

Gyakran ismételt kérdések