Krijo kod QR me REST-API: udhëzues me shembuj curl

Hapi 1: Krijo çelësin

Te paneli, te Llogaria, në seksionin „Qasje për CLI, skripte dhe agjentë“, krijon një çelës. Për provat e para mjafton „vetëm leximi“. Zgjidh një afat të shkurtër, për shembull 30 ditë. Çelësi fillon me sqr_live_ dhe shfaqet vetëm një herë. Vëre në një ndryshore mjedisi, që të mos mbarojë në historikun e shell-it, për shembull përmes menaxherit tënd të fjalëkalimeve.

Hapi 2: Kërkesa e parë

API-ja gjendet te https://sameqr.com/api/v1. Çelësi vihet në header-in Authorization, kurrë në adresë:

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

Kërkesa e parë tregon llogarinë tënde, tarifën dhe kufijtë, e dyta kodet e tua QR me identifikues, emër, destinacion, etiketa, numrin e skanimeve dhe gjendjen _rev.

Hapi 3: Krijo një kod QR

Për krijimin të duhet një çelës i dytë me „leximi + shkrimi“. Me çelës leximi API-ja u përgjigjet kërkesave që ndryshojnë me 403 dhe kodin NUR_LESEN. Një kod i ri QR ka nevojë të paktën për një emër dhe një destinacion:

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

Skano kodin e ri QR me telefon para se të vazhdosh. Për krijimin, adresa jote e postës elektronike duhet të jetë konfirmuar, dhe kodi QR llogaritet në kuotën e tarifës sate.

Hapi 4: Ndrysho destinacionin

Ndryshimet e destinacionit mbrohen veçanërisht. Të duhet një çelës „i plotë“ dhe dërgon gjendjen aktuale të kodit QR si header X-Confirm. Gjendjen e jep kërkesa e leximit:

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

Ndryshohen vetëm fushat që dërgon. Nëse gjendja nuk përputhet, sepse dikush e ka ndryshuar kodin QR ndërkohë, nuk mbishkruhet asgjë. Përmes API-së lejohen më së shumti 10 ndryshime destinacioni në orë dhe 30 në ditë, te paneli ky kufi nuk ekziston. Në tarifën falas numri i ndryshimeve të destinacionit për çdo kod QR është i kufizuar.

Hapi 5: Kupto gabimet dhe kufijtë

Gabimet kthehen gjithmonë në të njëjtën formë: një objekt error me status, code dhe message. Lexoji në programin tënd, në vend që të vazhdosh pa i parë.

• 401: Çelësi mungon, është i gabuar, ka skaduar ose është revokuar.
• 403: Çelësit i mungon niveli i nevojshëm, ose tarifa jote nuk e lejon veprimin.
• 400 me BESTAETIGUNG_FEHLT: Për ndryshimin e destinacionit, për ta çuar jashtë linje ose për fshirje mungon X-Confirm me gjendjen aktuale.
• 409: Dikush e ka ndryshuar kodin QR ndërkohë.
• 429: Shumë kërkesa. Për çdo çelës lejohen 120 në minutë, në orë 60 në tarifën falas, 300 në Start, 1.000 në Pro dhe 5.000 në Agentur.

Të gjitha kërkesat i përshkruan /api/v1/openapi.json, udhëzuesi gjendet te sameqr.com/entwickler.

Përfundim: Pse Same-QR

REST-API-ja e Same-QR është e rregullt, e dokumentuar mirë dhe përfshihet në çdo tarifë. Ajo bën gjithçka që bën paneli, i mbron kodet e printuara QR nga ndryshimet e pavullnetshme të destinacionit me konfirmim dhe kufij, lejon çelësa në tre nivele dhe përgjigjet me gabime që kuptohen.

Fillo menjëherë: regjistrohu falas në sameqr.com, 20 kode QR dinamikë janë falas përgjithmonë. API, CLI dhe serveri MCP ofrohen në çdo tarifë, dokumentacioni gjendet te sameqr.com/entwickler.

Pyetje të shpeshta