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

Korak 1: Izradi ključ

U nadzornoj ploči pod Račun, u odjeljku „Pristup za CLI, skripte i agente“, izrađuješ ključ. Za prve pokušaje dovoljno je „samo čitanje“. Odaberi kratko trajanje, primjerice 30 dana. Ključ počinje s sqr_live_ i prikazuje se samo jednom. Pohrani ga kao varijablu okoline kako ne bi završio u povijesti tvoje ljuske, na primjer preko svog upravitelja zaporki.

Korak 2: Prvi upit

API se nalazi na https://sameqr.com/api/v1. Ključ ide u zaglavlje Authorization, 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 upit prikazuje tvoj račun, tvoj paket i tvoja ograničenja, drugi tvoje QR kodove s identifikatorom, imenom, odredištem, oznakama, brojem skeniranja i stanjem _rev.

Korak 3: Izradi QR kod

Za izradu trebaš drugi ključ s „čitanje + pisanje“. S ključem za čitanje API na upite 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 što nastaviš. Za izradu tvoja e-adresa mora biti potvrđena, a QR kod se računa u kvotu tvog paketa.

Korak 4: Promijeni odredište

Promjene odredišta posebno su zaštićene. Trebaš ključ „puni“ i šalješ trenutno stanje QR koda kao zaglavlje X-Confirm. Stanje isporučuje upit 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 poslana polja. Ako se stanje razlikuje jer je netko u međuvremenu promijenio QR kod, ništa se ne prepisuje. Preko API-ja ide najviše 10 promjena odredišta na sat i 30 na dan, u nadzornoj ploči to ograničenje ne postoji. U besplatnom paketu broj promjena odredišta po QR kodu je ograničen.

Korak 5: Razumij pogreške i ograničenja

Pogreš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 potrebna razina ili tvoj paket ne dopušta tu radnju.
• 400 s BESTAETIGUNG_FEHLT: Za promjenu odredišta, offline ili brisanje nedostaje X-Confirm s trenutnim stanjem.
• 409: Netko je u međuvremenu promijenio QR kod.
• 429: Previše upita. Po ključu ide 120 u minuti, na sat 60 u besplatnom paketu, 300 u paketu Start, 1.000 u paketu Pro i 5.000 u paketu Agentur.

Sve upite opisuje /api/v1/openapi.json, vodič se nalazi na sameqr.com/entwickler.

Zaključak: Zašto Same-QR

REST API tvrtke Same-QR uredan je, dobro dokumentiran i dolazi uz svaki paket. Može sve što i nadzorna ploča, štiti tiskane QR kodove potvrdom i ograničenjima od slučajnih promjena odredišta, dopušta ključeve u tri razine i odgovara razumljivim pogreškama.

Kreni odmah: registriraj se besplatno na sameqr.com, 20 dinamičkih QR kodova trajno je besplatno. API, CLI i MCP poslužitelj dostupni su u svakom paketu, dokumentacija se nalazi na sameqr.com/entwickler.

Često postavljana pitanja