QR kod preko REST API-ja: uputstvo sa curl primerima

Korak 1: Napravi ključ

U kontrolnoj tabli, u odeljku Nalog, pod „Pristup za CLI, skripte i agente“, praviš ključ. Za prve probe dovoljno je „samo čitanje“. Izaberi kratak rok važenja, na primer 30 dana. Ključ počinje sa sqr_live_ i prikazuje se samo jednom. Sačuvaj ga kao promenljivu okruženja da ne završi u istoriji komandi, na primer preko menadžera lozinki.

Korak 2: Prvi upit

API se nalazi na https://sameqr.com/api/v1. Ključ ide u Authorization zaglavlje, nikada 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 nalog, paket i ograničenja, a drugi tvoje QR kodove sa oznakom, imenom, ciljem, labelama, brojem skeniranja i stanjem _rev.

Korak 3: Napravi QR kod

Za pravljenje ti treba drugi ključ sa pravom „čitanje + pisanje“. Sa ključem za čitanje API na upite koji nešto menjaju odgovara sa 403 i kodom NUR_LESEN. Novi QR kod traži najmanje ime i 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"}'

Skeniraj novi QR kod telefonom pre nego što nastaviš. Za pravljenje mora da bude potvrđena tvoja imejl adresa, a QR kod se računa u kvotu tvog paketa.

Korak 4: Promeni cilj

Promene cilja su posebno zaštićene. Treba ti ključ sa pravom „puno“ i šalješ aktuelno stanje QR koda u zaglavlju X-Confirm. Stanje dobijaš upitom 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"}'

Menjaju se samo polja koja pošalješ. Ako se stanje razlikuje jer je neko u međuvremenu izmenio QR kod, ništa se ne prepisuje. Preko API-ja je moguće najviše 10 promena cilja na sat i 30 na dan, u kontrolnoj tabli tog ograničenja nema. U besplatnom paketu broj promena cilja po QR kodu je ograničen.

Korak 5: Razumevanje grešaka i ograničenja

Greške uvek stižu u istom obliku: objekat error sa poljima status, code i message. Obradi ih u svom programu umesto da jednostavno nastaviš dalje.

• 401: Ključ nedostaje, pogrešan je, istekao je ili je opozvan.
• 403: Ključu nedostaje potreban nivo ili tvoj paket ne dozvoljava radnju.
• 400 sa BESTAETIGUNG_FEHLT: Za promenu cilja, isključivanje ili brisanje nedostaje X-Confirm sa aktuelnim stanjem.
• 409: Neko je u međuvremenu izmenio QR kod.
• 429: Previše upita. Po ključu je moguće 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, a uputstvo se nalazi na sameqr.com/entwickler.

Zaključak: Zašto Same-QR

REST API servisa Same-QR je uredan, dobro dokumentovan i dostupan u svakom paketu. Može sve što može i kontrolna tabla, štiti odštampane QR kodove potvrdom i ograničenjima od slučajnih promena cilja, nudi ključeve u tri nivoa i odgovara greškama koje se razumeju.

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

Često postavljana pitanja