API pentru coduri QR: creează, modifică și analizează coduri QR automat

La ce folosește un API pentru coduri QR

Un API pentru coduri QR este o interfață de programare: în loc să dai clic în browser, programul tău trimite cereri către serviciul de coduri QR și primește răspunsuri. Așa apar codurile QR direct dintr-un magazin online, dintr-un sistem de gestiune, dintr-un script sau dintr-un tabel.

Merită de îndată ce munca se repetă: o sută de coduri QR pentru mese sau produse, rapoarte lunare de scanări, schimbarea multor destinații după o relansare. Și funcționează doar cu coduri QR dinamice. Un cod QR dinamic de la Same-QR conține o adresă scurtă, care nu se schimbă, iar destinația din spatele ei se află la noi și poate fi modificată oricând, fără o nouă tipărire.

Ce acoperă API-ul Same-QR

API-ul REST se află la https://sameqr.com/api/v1. El apelează aceleași funcții ca panoul de control, cu aceleași limite de tarif și aceleași verificări:

• Listarea, citirea, crearea, modificarea și ștergerea codurilor QR.
• Statistica unui cod QR: scanări, data creării, numărul de schimbări de destinație.
• Crearea, modificarea, publicarea și scoaterea offline a paginilor pentru oaspeți, precum meniul, lista de prețuri, programul, pagina de linkuri, oferta, crama, eticheta electronică de vin și contactul.
• Citirea unui meniu din cel mult șapte fotografii sau dintr-un PDF.
• Administrarea etichetelor și a proiectelor clienților și citirea cererilor din formularele de contact.

O descriere care poate fi citită de mașini a tuturor cererilor se află la /api/v1/openapi.json, iar ghidul la sameqr.com/entwickler.

Chei API și drepturi

Cheia o creezi în panou, la Cont, în secțiunea „Acces pentru CLI, scripturi și agenți”. Alegi una dintre trei trepte, „doar citire”, „citire + scriere” (creare, modificarea numelor și a textelor) sau „complet” (în plus modificarea destinațiilor, scoaterea offline, ștergerea), precum și o durată de 30, 90, 180 sau 365 de zile, la nevoie chiar nelimitată. Cheia începe cu sqr_live_ și este afișată exact o dată. La noi se păstrează doar o sumă de control.

O cheie care are voie doar să citească primește un refuz clar la orice cerere care modifică ceva. Pentru rapoarte și analize aceasta este alegerea potrivită. Tot ce schimbă încotro duce un cod QR tipărit este protejat suplimentar: schimbarea destinației, scoaterea offline și ștergerea cer treapta „complet” și o confirmare cu starea citită în prealabil, iar prin API se pot face cel mult 10 pe oră și 30 pe zi. În panou această limită nu există. Orice cheie poate fi revocată oricând și devine imediat nevalidă.

Un flux tipic

Cheia se pune în antetul Authorization, niciodată într-o adresă. Salvează cheia în prealabil ca variabilă de mediu. Astfel îți listezi codurile QR și modifici destinația unui cod QR:

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

Valoarea pentru X-Confirm, adică starea, o oferă cererea de citire la /api/v1/qr/<id>. Se modifică doar ceea ce trimiți. Cine vrea să fie sigur că nimeni nu a modificat între timp același cod QR trimite starea citită ca _rev. Dacă s-a schimbat ceva, nu se suprascrie nimic, iar răspunsul conține starea actuală. Erorile revin mereu în același format, cu stare, cod QR și un mesaj ușor de înțeles.

Limite și bune practici

Pentru fiecare cheie se pot face cel mult 120 de cereri pe minut. La aceasta se adaugă o limită pe oră, care depinde de tarif: 60 în tariful gratuit, 300 în Start, 1.000 în Pro și 5.000 în Agentur. Limitele opresc greșelile, de exemplu un script într-o buclă fără sfârșit, și nu deranjează utilizarea cinstită.

• Încearcă mai întâi cu o cheie de citire, abia apoi scrie.
• Testează fluxurile noi pe un singur cod QR și scanează-l cu telefonul.
• Evită ștergerea acolo unde este de ajuns o destinație nouă. Codurile QR șterse și linkurile lor scurte nu mai revin.
• Creează câte o cheie separată pentru fiecare program și păstrează-o într-un manager de parole sau într-o variabilă de mediu.

Concluzie: de ce Same-QR

Same-QR îți oferă API-ul nu ca pe un extra scump, ci în orice tarif, cu aceleași funcții ca în panou: coduri QR, statistică, meniuri, pagini pentru oaspeți, etichete și proiecte. La acestea se adaugă drepturi clare pentru fiecare cheie, mesaje de eroare sincere și o verificare nocturnă a tuturor destinațiilor, care te anunță prin e-mail dacă una nu mai este accesibilă.

Începe chiar acum: înregistrează-te gratuit pe sameqr.com, 20 de coduri QR dinamice sunt gratuite pentru totdeauna. API-ul, CLI și serverul MCP există în orice tarif, iar documentația se află la sameqr.com/entwickler.

Întrebări frecvente