API za QR kodove: automatski pravi, mijenjaj i analiziraj QR kodove

Čemu služi API za QR kodove

API za QR kodove je programski interfejs: umjesto klikanja u pregledniku, tvoj program šalje zahtjeve servisu za QR kodove i dobija odgovore. Tako QR kodovi nastaju direktno iz web-shopa, robnog poslovanja, skripte ili tabele.

To se isplati čim se posao ponavlja: stotinu QR kodova za stolove ili proizvode, mjesečni izvještaji o skeniranju, mijenjanje mnogih odredišta nakon relaunča. I radi samo s dinamičkim QR kodovima. Dinamički QR kod iz Same-QR sadrži kratku adresu koja se ne mijenja, odredište iza nje je kod nas i može se bilo kada promijeniti bez ponovnog štampanja.

Šta pokriva Same-QR API

REST API nalazi se na https://sameqr.com/api/v1. Poziva iste funkcije kao kontrolna tabla, s istim ograničenjima paketa i provjerama:

• Listanje, čitanje, pravljenje, mijenjanje i brisanje QR kodova.
• Statistika QR koda: skeniranja, datum kreiranja, broj promjena odredišta.
• Gostinjske stranice poput jelovnika, cjenovnika, radnog vremena, stranice s linkovima, akcije, vinarije, vinske e-etikete i kontakta praviš, mijenjaš, objavljuješ i skidaš s mreže.
• Učitavanje jelovnika iz do sedam fotografija ili jednog PDF-a.
• Upravljanje oznakama i projektima klijenata i čitanje upita iz kontakt obrazaca.

Opis svih zahtjeva čitljiv mašini nalazi se na /api/v1/openapi.json, a uputstvo na sameqr.com/entwickler.

API ključevi i prava

Ključ praviš u kontrolnoj tabli pod Račun, odjeljak „Pristup za CLI, skripte i agente“. Biraš jedan od tri nivoa, „samo čitanje“, „čitanje + pisanje“ (pravljenje, mijenjanje naziva i tekstova) ili „potpuno“ (dodatno mijenjanje odredišta, skidanje s mreže, brisanje), te trajanje od 30, 90, 180 ili 365 dana, po potrebi i neograničeno. Ključ počinje sa sqr_live_ i prikazuje se tačno jednom. Kod nas se čuva samo kontrolni zbir.

Ključ koji smije samo čitati na svaki zahtjev za promjenu dobija jasno odbijanje. Za izvještaje i analize to je pravi izbor. Sve što mijenja kuda vodi odštampani QR kod dodatno je zaštićeno: promjena odredišta, skidanje s mreže i brisanje traže nivo „potpuno“ i potvrdu s prethodno pročitanim stanjem, a preko API-ja od toga je dozvoljeno najviše 10 na sat i 30 na dan. U kontrolnoj tabli tog ograničenja nema. Svaki ključ se može bilo kada opozvati i tada odmah prestaje važiti.

Tipičan tok

Ključ pripada u Authorization header, nikad u adresu. Ključ prethodno spremi kao varijablu okruženja. Ovako listaš svoje QR kodove i mijenjaš odredište QR koda:

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

Vrijednost za X-Confirm, stanje, vraća zahtjev za čitanje na /api/v1/qr/<id>. Mijenja se samo ono što pošalješ. Ko želi biti siguran da niko u međuvremenu nije promijenio isti QR kod, šalje pročitano stanje kao _rev. Ako se nešto promijenilo, ništa se ne prepisuje, a odgovor sadrži aktuelno stanje. Greške uvijek stižu u istom formatu, sa statusom, QR kodom i razumljivom porukom.

Ograničenja i dobra praksa

Po ključu je dozvoljeno najviše 120 zahtjeva u minuti. Uz to postoji ograničenje po satu koje zavisi od paketa: 60 u besplatnom paketu, 300 u paketu Start, 1.000 u Pro i 5.000 u paketu Agentur. Ograničenja hvataju greške, na primjer skriptu u beskonačnoj petlji, a ne smetaju poštenoj upotrebi.

• Prvo isprobaj s ključem za čitanje, pa tek onda piši.
• Nove tokove testiraj na jednom QR kodu i skeniraj ga mobitelom.
• Izbjegavaj brisanje tamo gdje je dovoljno novo odredište. Obrisani QR kodovi i njihovi kratki linkovi ne vraćaju se.
• Za svaki program napravi poseban ključ i čuvaj ga u upravitelju lozinki ili u varijabli okruženja.

Zaključak: zašto Same-QR

Same-QR ti API ne daje kao skup dodatak, nego u svakom paketu, s istim funkcijama kao kontrolna tabla: QR kodovi, statistika, jelovnici, gostinjske stranice, oznake i projekti. Tu su još jasna prava po ključu, poštene poruke o greškama i noćna provjera svih odredišta koja ti mailom javlja ako neko odredište nije dostupno.

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

Često postavljana pitanja