Creează un cod QR prin API REST: ghid cu exemple curl

Pasul 1: Creează cheia

În dashboard, la Cont, secțiunea „Acces pentru CLI, scripturi și agenți”, creezi o cheie. Pentru primele încercări este suficient „doar citire”. Alege o durată scurtă de valabilitate, de exemplu 30 de zile. Cheia începe cu sqr_live_ și este afișată o singură dată. Păstrează-o ca variabilă de mediu, ca să nu ajungă în istoricul shell-ului, de exemplu prin managerul tău de parole.

Pasul 2: Prima cerere

API-ul se află la https://sameqr.com/api/v1. Cheia aparține antetului Authorization, niciodată adresei:

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

Prima cerere îți arată contul, tariful și limitele, a doua codurile tale QR cu identificator, nume, destinație, etichete, număr de scanări și starea _rev.

Pasul 3: Creează un cod QR

Pentru creare ai nevoie de o a doua cheie, cu „citire + scriere”. Cu o cheie de citire, API-ul răspunde la cererile care modifică cu 403 și codul NUR_LESEN. Un cod QR nou are nevoie cel puțin de un nume și o destinație:

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

Scanează noul cod QR cu telefonul înainte de a continua. Pentru creare, adresa ta de e-mail trebuie să fie confirmată, iar codul QR se numără în cota tarifului tău.

Pasul 4: Schimbă destinația

Schimbările de destinație sunt protejate în mod special. Ai nevoie de o cheie „complet” și trimiți starea curentă a codului QR în antetul X-Confirm. Starea o oferă cererea de citire:

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

Se modifică doar câmpurile trimise. Dacă starea diferă, pentru că între timp cineva a schimbat codul QR, nu se suprascrie nimic. Prin API sunt posibile cel mult 10 schimbări de destinație pe oră și 30 pe zi, în dashboard această limită nu există. În tariful gratuit, numărul schimbărilor de destinație pentru fiecare cod QR este limitat.

Pasul 5: Înțelege erorile și limitele

Erorile revin mereu în aceeași formă: un obiect error cu status, code și message. Interpretează-le în programul tău, în loc să continui pur și simplu.

• 401: cheia lipsește, este greșită, a expirat sau a fost revocată.
• 403: cheii îi lipsește treapta necesară sau tariful tău nu permite acțiunea.
• 400 cu BESTAETIGUNG_FEHLT: pentru schimbarea destinației, trecerea offline sau ștergere lipsește X-Confirm cu starea curentă.
• 409: cineva a schimbat între timp codul QR.
• 429: prea multe cereri. Pentru fiecare cheie sunt permise 120 pe minut, pe oră 60 în tariful gratuit, 300 în Start, 1.000 în Pro și 5.000 în Agentur.

Toate cererile sunt descrise în /api/v1/openapi.json, iar ghidul se află pe sameqr.com/entwickler.

Concluzie: de ce Same-QR

API-ul REST al Same-QR este ordonat, bine documentat și inclus în fiecare tarif. Poate tot ce poate dashboardul, protejează codurile QR tipărite de schimbări accidentale ale destinației prin confirmare și limite, permite chei în trei trepte și răspunde cu erori care se înțeleg.

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

Întrebări frecvente