Ustvarjanje QR kode prek REST API-ja: navodila s primeri curl

Korak 1: Ustvari ključ

V nadzorni plošči pod Račun, v razdelku »Dostop za CLI, skripte in agente«, ustvariš ključ. Za prve poskuse zadošča »samo branje«. Izberi kratko veljavnost, na primer 30 dni. Ključ se začne s sqr_live_ in se prikaže samo enkrat. Shrani ga kot okoljsko spremenljivko, da ne konča v zgodovini lupine, na primer prek upravitelja gesel.

Korak 2: Prva poizvedba

API je na https://sameqr.com/api/v1. Ključ sodi v glavo Authorization, nikoli v naslov:

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

Prva poizvedba pokaže tvoj račun, tarifo in omejitve, druga tvoje QR kode z identifikatorjem, imenom, ciljem, oznakami, številom skeniranj in stanjem _rev.

Korak 3: Ustvari QR kodo

Za ustvarjanje potrebuješ drugi ključ z »branje + pisanje«. Če imaš ključ za branje, API na poizvedbe, ki spreminjajo, odgovori s 403 in kodo NUR_LESEN. Nova QR koda potrebuje vsaj ime in cilj:

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

Novo QR kodo skeniraj s telefonom, preden greš naprej. Za ustvarjanje mora biti tvoj e-poštni naslov potrjen, QR koda pa se šteje v kvoto tvoje tarife.

Korak 4: Spremeni cilj

Spremembe ciljev so posebej zaščitene. Potrebuješ ključ »polno« in trenutno stanje QR kode pošlješ kot glavo X-Confirm. Stanje vrne poizvedba za branje:

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

Spremenijo se samo polja, ki jih pošlješ. Če se stanje razlikuje, ker je medtem nekdo spremenil QR kodo, se ne prepiše nič. Prek API-ja je mogočih največ 10 sprememb ciljev na uro in 30 na dan, v nadzorni plošči te omejitve ni. V brezplačni tarifi je število sprememb ciljev na QR kodo omejeno.

Korak 5: Razumi napake in omejitve

Napake vedno pridejo v isti obliki: objekt error s status, code in message. Obdelaj jih v svojem programu, namesto da bi preprosto nadaljeval.

• 401: ključ manjka, je napačen, potekel ali preklican.
• 403: ključu manjka potrebna stopnja ali tvoja tarifa dejanja ne dovoljuje.
• 400 z BESTAETIGUNG_FEHLT: za spremembo cilja, umik s spleta ali brisanje manjka X-Confirm s trenutnim stanjem.
• 409: nekdo je medtem spremenil QR kodo.
• 429: preveč zahtev. Na ključ je dovoljenih 120 na minuto, na uro pa 60 v brezplačni tarifi, 300 v tarifi Start, 1.000 v Pro in 5.000 v Agentur.

Vse zahteve opisuje /api/v1/openapi.json, navodila so na sameqr.com/entwickler.

Zaključek: zakaj Same-QR

REST API storitve Same-QR je pregleden, dobro dokumentiran in vključen v vsako tarifo. Zmore vse, kar zmore nadzorna plošča, natisnjene QR kode s potrditvijo in omejitvami varuje pred nenamernimi spremembami ciljev, omogoča ključe v treh stopnjah in odgovarja z napakami, ki jih je mogoče razumeti.

Začni kar zdaj: 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