API za QR kode: samodejno ustvarjanje, spreminjanje in analiza QR kod

Čemu služi API za QR kode

API za QR kode je programski vmesnik: namesto klikanja v brskalniku tvoj program pošilja zahteve storitvi za QR kode in dobiva odgovore. Tako QR kode nastajajo neposredno iz spletne trgovine, skladiščnega programa, skripte ali preglednice.

To se splača, brž ko se delo ponavlja: sto QR kod za mize ali izdelke, mesečna poročila o skenih, preusmeritev številnih ciljev po prenovi spletne strani. Deluje pa samo z dinamičnimi QR kodami. Dinamična QR koda Same-QR vsebuje kratek, nespremenljiv naslov, cilj za njim pa je shranjen pri nas in ga lahko kadar koli spremeniš brez novega tiska.

Kaj pokriva API Same-QR

REST API je na naslovu https://sameqr.com/api/v1. Kliče iste funkcije kot nadzorna plošča, z istimi omejitvami tarife in preverjanji:

• Izpis, branje, ustvarjanje, spreminjanje in brisanje QR kod.
• Statistika QR kode: skeni, datum ustvarjanja, število sprememb cilja.
• Ustvarjanje, spreminjanje, objava in umik gostujočih strani, kot so jedilnik, cenik, delovni čas, stran s povezavami, akcija, vinska klet, e-etiketa vina in kontakt.
• Branje jedilnika iz največ sedmih fotografij ali iz PDF-ja.
• Upravljanje oznak in projektov strank ter branje sporočil iz kontaktnih obrazcev.

Strojno berljiv opis vseh zahtev je na /api/v1/openapi.json, navodila pa na sameqr.com/entwickler.

API ključ in pravice

Ključ ustvariš v nadzorni plošči pod Račun, v razdelku »Dostop za CLI, skripte in agente«. Izbereš eno od treh stopenj, »samo branje«, »branje + pisanje« (ustvarjanje, spreminjanje imen in besedil) ali »polno« (dodatno spreminjanje ciljev, umik, brisanje), in veljavnost 30, 90, 180 ali 365 dni, po potrebi tudi neomejeno. Ključ se začne s sqr_live_ in se prikaže natanko enkrat. Pri nas se shrani samo kontrolna vsota.

Ključ, ki sme samo brati, ob vsaki zahtevi za spremembo dobi jasno zavrnitev. Za poročila in analize je to prava izbira. Vse, kar spremeni, kam vodi natisnjena QR koda, je dodatno zaščiteno: spremembe ciljev, umik in brisanje zahtevajo stopnjo »polno« in potrditev s prej prebranim stanjem, prek API-ja pa je teh največ 10 na uro in 30 na dan. V nadzorni plošči te omejitve ni. Vsak ključ lahko kadar koli prekličeš in takoj postane neveljaven.

Tipičen potek

Ključ sodi v glavo Authorization, nikoli v naslov. Ključ si prej shrani kot spremenljivko okolja. Tako izpišeš svoje QR kode in spremeniš cilj ene QR kode:

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

Vrednost za X-Confirm, torej stanje, vrne zahteva za branje na /api/v1/qr/<id>. Spremeni se samo to, kar pošlješ. Kdor se želi prepričati, da med tem nihče ni spremenil iste QR kode, pošlje prebrano stanje kot _rev. Če se je kaj spremenilo, se nič ne prepiše, odgovor pa vsebuje aktualno stanje. Napake se vedno vrnejo v isti obliki, s statusom, QR kodo in razumljivim sporočilom.

Omejitve in dobra praksa

Na ključ je dovoljenih največ 120 zahtev na minuto. Poleg tega velja omejitev na uro, ki je odvisna od tarife: 60 v brezplačni tarifi, 300 v tarifi Start, 1.000 v Pro in 5.000 v Agentur. Omejitve ujamejo napake, na primer skripto v neskončni zanki, poštene uporabe pa ne motijo.

• Najprej preizkusi s ključem za branje, šele nato piši.
• Nove poteke preizkusi na eni sami QR kodi in jo skeniraj s telefonom.
• Brisanju se izogni, kjer zadošča nov cilj. Izbrisane QR kode in njihove kratke povezave se ne vrnejo.
• Za vsak program ustvari svoj ključ in ga hrani v upravitelju gesel ali v spremenljivki okolja.

Zaključek: zakaj Same-QR

Same-QR ti API ne ponuja kot drag dodatek, ampak v vsaki tarifi, z enakimi funkcijami kot nadzorna plošča: QR kode, statistika, jedilniki, gostujoče strani, oznake in projekti. Poleg tega so tu jasne pravice za vsak ključ, poštena sporočila o napakah in nočno preverjanje vseh ciljev, ki ti po e-pošti sporoči, če kateri ni dosegljiv.

Začni takoj: brezplačno se registriraj na sameqr.com, 20 dinamičnih QR kod je trajno brezplačnih. API, CLI in strežnik MCP so na voljo v vsaki tarifi, dokumentacija je na sameqr.com/entwickler.

Pogosta vprašanja