QR kod API: automatski izrađuj, mijenjaj i analiziraj QR kodove

Čemu služi API za QR kodove

API za QR kodove programsko je sučelje: umjesto da klikaš u pregledniku, tvoj program šalje zahtjeve usluzi za QR kodove i dobiva odgovore. Tako QR kodovi nastaju izravno iz web-trgovine, skladišnog sustava, skripte ili tablice.

To se isplati čim se posao ponavlja: stotinu QR kodova za stolove ili proizvode, mjesečna izvješća o skeniranju, preusmjeravanje mnogih odredišta nakon redizajna. 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 nalazi se kod nas i može se u svakom trenutku promijeniti, bez novog ispisa.

Što pokriva Same-QR API

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

• Popis, čitanje, izrada, izmjena i brisanje QR kodova.
• Statistika QR koda: skeniranja, datum izrade, broj promjena odredišta.
• Gostinske stranice poput jelovnika, cjenika, radnog vremena, stranice s poveznicama, akcije, vinarije, e-etikete vina i kontakta: izrada, izmjena, objava i isključivanje.
• Očitavanje jelovnika iz do sedam fotografija ili jednog PDF-a.
• Upravljanje oznakama i projektima klijenata te čitanje upita iz kontaktnih obrazaca.

Strojno čitljiv opis svih zahtjeva nalazi se na /api/v1/openapi.json, a upute na sameqr.com/entwickler.

API ključ i prava

Ključ izrađuješ na nadzornoj ploči pod Račun, u odjeljku „Pristup za CLI, skripte i agente“. Biraš jednu od tri razine, „samo čitanje“, „čitanje + pisanje“ (izrada, izmjena naziva i tekstova) ili „potpuno“ (dodatno promjena odredišta, isključivanje, brisanje), te rok trajanja od 30, 90, 180 ili 365 dana, po potrebi i neograničeno. Ključ počinje s sqr_live_ i prikazuje se točno jednom. Kod nas se sprema samo kontrolni zbroj.

Ključ koji smije samo čitati dobiva jasno odbijanje za svaki zahtjev koji nešto mijenja. Za izvješća i analize to je pravi izbor. Sve što mijenja kamo vodi ispisani QR kod dodatno je zaštićeno: promjene odredišta, isključivanje i brisanje traže razinu „potpuno“ i potvrdu s prethodno pročitanim stanjem, a preko API-ja od toga je moguće najviše 10 na sat i 30 na dan. Na nadzornoj ploči tog ograničenja nema. Svaki ključ može se u svakom trenutku opozvati i tada odmah prestaje vrijediti.

Tipičan tijek

Ključ pripada u zaglavlje Authorization, nikad u adresu. Ključ prije toga spremi kao varijablu okruženja. Ovako izlistavaš svoje QR kodove i mijenjaš odredište jednog 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, tj. stanje, daje zahtjev za čitanje na /api/v1/qr/<id>. Mijenja se samo ono što pošalješ. Tko želi biti siguran da u međuvremenu nitko 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 aktualno stanje. Pogreške uvijek stižu u istom formatu, sa statusom, QR kodom i razumljivom porukom.

Ograničenja i dobra praksa

Po ključu je moguće najviše 120 zahtjeva u minuti. Uz to postoji ograničenje po satu koje ovisi o paketu: 60 u besplatnom paketu, 300 u paketu Start, 1.000 u paketu Pro i 5.000 u paketu Agentur. Ograničenja hvataju pogreške, primjerice skriptu u beskonačnoj petlji, a poštenu uporabu ne ometaju.

• Prvo isprobaj s ključem za čitanje, tek onda piši.
• Nove tijekove testiraj na jednom QR kodu i skeniraj ga mobitelom.
• Izbjegavaj brisanje tamo gdje je dovoljno novo odredište. Izbrisani QR kodovi i njihove kratke poveznice ne vraćaju se.
• Za svaki program izradi zaseban ključ i čuvaj ga u upravitelju zaporki ili u varijabli okruženja.

Zaključak: zašto Same-QR

Same-QR ti API ne daje kao skupi dodatak, nego u svakom paketu, s istim funkcijama kao nadzorna ploča: QR kodovi, statistika, jelovnici, gostinske stranice, oznake i projekti. Tu su još jasna prava po ključu, iskrene poruke o pogreškama i noćna provjera svih odredišta koja ti e-poštom javlja ako neko nije dostupno.

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

Često postavljana pitanja