QR-kód létrehozása REST API-val: útmutató curl-példákkal

1. lépés: Kulcs létrehozása

Az irányítópulton a Fiók menüben, a „Hozzáférés CLI-hez, szkriptekhez és ágensekhez” szakaszban hozol létre egy kulcsot. Az első próbákhoz a „csak olvasás” elég. Válassz rövid érvényességi időt, például 30 napot. A kulcs sqr_live_ előtaggal kezdődik, és csak egyszer jelenik meg. Tedd környezeti változóba, hogy ne kerüljön be a shell előzményeibe, például a jelszókezelődön keresztül.

2. lépés: Az első kérés

Az API a https://sameqr.com/api/v1 címen érhető el. A kulcsnak az Authorization fejlécbe kell kerülnie, soha nem a címbe:

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

Az első kérés megmutatja a fiókodat, a csomagodat és a határaidat, a második a QR-kódjaidat azonosítóval, névvel, céllal, címkékkel, beolvasási számmal és a _rev állapottal.

3. lépés: QR-kód létrehozása

A létrehozáshoz egy második kulcsra van szükséged „olvasás + írás” jogosultsággal. Olvasókulccsal az API a módosító kérésekre 403-as hibával és a NUR_LESEN kóddal válaszol. Egy új QR-kódhoz legalább egy név és egy cél kell:

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

Mielőtt továbblépsz, olvasd be az új QR-kódot a telefonoddal. A létrehozáshoz az e-mail-címednek megerősítettnek kell lennie, és a QR-kód a csomagod keretébe számít bele.

4. lépés: A cél módosítása

A célmódosítások különösen védettek. „Teljes” kulcs kell hozzá, és a QR-kód aktuális állapotát X-Confirm fejlécként küldöd el. Az állapotot az olvasási kérés adja meg:

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

Csak a megküldött mezők módosulnak. Ha az állapot eltér, mert közben valaki módosította a QR-kódot, semmi sem íródik felül. Az API-n keresztül óránként legfeljebb 10, naponta legfeljebb 30 célmódosítás lehetséges, az irányítópulton ez a határ nincs meg. Az ingyenes csomagban a QR-kódonkénti célmódosítások száma korlátozott.

5. lépés: A hibák és a határok megértése

A hibák mindig ugyanabban a formában érkeznek vissza: egy error objektum status, code és message mezővel. Értékeld ki őket a programodban, ahelyett hogy egyszerűen továbbmennél.

• 401: A kulcs hiányzik, hibás, lejárt vagy visszavonták.
• 403: A kulcsnak hiányzik a szükséges szintje, vagy a csomagod nem engedélyezi a műveletet.
• 400 BESTAETIGUNG_FEHLT kóddal: A célmódosításhoz, az offline állapothoz vagy a törléshez hiányzik az X-Confirm az aktuális állapottal.
• 409: Valaki közben módosította a QR-kódot.
• 429: Túl sok kérés. Kulcsonként percenként 120 lehetséges, óránként 60 az ingyenes csomagban, 300 a Startban, 1.000 a Proban és 5.000 az Agenturban.

Az összes kérést a /api/v1/openapi.json írja le, az útmutató a sameqr.com/entwickler oldalon található.

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

A Same-QR REST API-ja rendezett, jól dokumentált, és minden csomagban benne van. Mindent tud, amit az irányítópult, megerősítéssel és határokkal védi a kinyomtatott QR-kódokat a véletlen célmódosításoktól, három szinten engedi a kulcsokat, és érthető hibákkal válaszol.

Vágj bele rögtön: 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 elérhető, a dokumentáció a sameqr.com/entwickler címen található.

Gyakran ismételt kérdések