Kreiranje QR koda putem REST API-ja: vodič s curl primjerima

Korak 1: Kreiraj ključ

U kontrolnoj tabli pod Račun, u odjeljku „Pristup za CLI, skripte i agente“, kreiraš ključ. Za prve pokušaje dovoljno je „samo čitanje“. Odaberi kratak rok važenja, na primjer 30 dana. Ključ počinje sa sqr_live_ i prikazuje se samo jednom. Spremi ga kao varijablu okruženja da ne završi u historiji tvog shella, na primjer putem menadžera lozinki.

Korak 2: Prvi zahtjev

API se nalazi na https://sameqr.com/api/v1. Ključ ide u Authorization zaglavlje, nikad u adresu:

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

Prvi zahtjev prikazuje tvoj račun, tvoju tarifu i tvoja ograničenja, drugi tvoje QR kodove s identifikatorom, imenom, odredištem, oznakama, brojem skeniranja i stanjem _rev.

Korak 3: Kreiraj QR kod

Za kreiranje ti treba drugi ključ s „čitanje + pisanje“. S ključem za čitanje API na zahtjeve koji nešto mijenjaju odgovara s 403 i kodom NUR_LESEN. Novi QR kod treba najmanje ime i odredište:

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

Skeniraj novi QR kod mobitelom prije nego nastaviš. Za kreiranje tvoja mejl adresa mora biti potvrđena, a QR kod se računa u kvotu tvoje tarife.

Korak 4: Promijeni odredište

Promjene odredišta posebno su zaštićene. Treba ti ključ „potpuni“ i šalješ trenutno stanje QR koda kao zaglavlje X-Confirm. Stanje daje zahtjev za čitanje:

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

Mijenjaju se samo polja koja pošalješ. Ako se stanje razlikuje jer je neko u međuvremenu promijenio QR kod, ništa se ne prepisuje. Putem API-ja moguće je najviše 10 promjena odredišta na sat i 30 na dan, u kontrolnoj tabli ovog ograničenja nema. U besplatnoj tarifi broj promjena odredišta po QR kodu je ograničen.

Korak 5: Razumij greške i ograničenja

Greške se uvijek vraćaju u istom obliku: objekt error sa status, code i message. Obradi ih u svom programu umjesto da jednostavno nastaviš.

• 401: Ključ nedostaje, pogrešan je, istekao je ili je opozvan.
• 403: Ključu nedostaje potreban nivo, ili tvoja tarifa ne dozvoljava tu radnju.
• 400 s BESTAETIGUNG_FEHLT: Za promjenu odredišta, isključivanje ili brisanje nedostaje X-Confirm s trenutnim stanjem.
• 409: Neko je u međuvremenu promijenio QR kod.
• 429: Previše zahtjeva. Po ključu je dozvoljeno 120 u minuti, na sat 60 u besplatnoj tarifi, 300 u Startu, 1.000 u Pro i 5.000 u Agenturi.

Sve zahtjeve opisuje /api/v1/openapi.json, uputstvo je na sameqr.com/entwickler.

Zaključak: Zašto Same-QR

REST API Same-QR-a je uredan, dobro dokumentovan i dostupan u svakoj tarifi. Može sve što može i kontrolna tabla, štiti odštampane QR kodove potvrdom i ograničenjima od nehotičnih promjena odredišta, dozvoljava ključeve u tri nivoa i odgovara greškama koje se razumiju.

Počni odmah: registruj se besplatno na sameqr.com, 20 dinamičkih QR kodova trajno je besplatno. API, CLI i MCP server dostupni su u svakoj tarifi, dokumentacija je na sameqr.com/entwickler.

Često postavljana pitanja