API za QR kode: kaj avtomatizirati in česa ne

Večino QR kod naj bi človek ustvaril enkrat in jih natisnil. API si zasluži mesto tam, kjer to ni mogoče: koda na naročilo, na rezervacijo, na sredstvo, na uporabnika — ustvarjena v trenutku, ki ga nihče ne napove, in v količini, ki je nihče noče klikati.

Kdaj je API pravi odgovor

• Ena koda na zapis v sistemu, ki ga že vodite: vstopnica, delovni nalog, oznaka sredstva, pošiljka.
• Cilji, ki se izračunajo, ne izberejo. Če je naslov izpeljiv iz vaših podatkov, prepisovanje ni odločitev, ampak vir napak.
• Podatki o skeniranjih, ki sodijo v vaše poročanje, ob naročila in prihodke.

Kdaj ni

• Marketinška kampanja. Pol ducata kod, ki jih izberejo in oblikujejo ljudje.
• Vse, kjer šteje oblika. API ustvarja in preusmerja; slog, okvirji in predloge so stvar urejevalnika.
• Enkratna serija. Za to je nalaganje CSV: preglednica je hitrejša integracija od integracije.

Preverjanje pristnosti

Ključ nastane v nadzorni plošči in se pokaže enkrat. Shrani se le zgoščena vrednost SHA-256 in prvih nekaj znakov za razlikovanje: izgubljenega ključa ni mogoče obnoviti, le zamenjati.

Authorization: Bearer enq_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

API je del paketa Business. Omejitev: 60 zahtev na minuto na račun; nad tem 429 in rate_limited.

Ustvarjanje kode

POST /api/v1/qrcodes
Authorization: Bearer enq_…
Content-Type: application/json

{ "name": "Naročilo 10432 – dobavnica", "url": "https://shop.example/orders/10432" }

• V ime vpišite svoj identifikator.
• Vrnjeni id shranite ob svoj zapis.

Preostalo

• GET /api/v1/qrcodes — vaše kode, najnovejše najprej, s kazalčnim ostranjevanjem.
• GET /api/v1/qrcodes/{id} — ena koda.
• PATCH /api/v1/qrcodes/{id} — sprememba cilja. Na tem stoji celotna zamisel dinamične kode.
• DELETE /api/v1/qrcodes/{id} — izbris; natisnjeno preneha delovati.
• GET /api/v1/qrcodes/{id}/scans — do 1.000 skeniranj, najnovejša najprej.

Kaj vsebuje zapis o skeniranju

Čas, vrsto naprave, sistem in brskalnik, kot ju sporoči zahteva, ter napotitelja, če obstaja. Brez identitete, brez računa in brez lokacije — ne mesta ne države. "Koliko, kdaj, na kakšni napravi": da. "Kdo" in "kje": ne.

Napake, ki se res pojavijo

• 401 invalid_api_key
• 400 invalid_body — najpogosteje naslov, ki to ni.
• 402 plan_limit_reached — Business omejitve nima, torej ključ pripada manjšemu paketu.
• 429 rate_limited

Dvoje že prvi dan

Ustvarjanje naredite idempotentno na svoji strani. Dva klica ustvarita dve kodi; ponovni poskusi prej ali slej pokličejo dvakrat.

Ne tiskajte tistega, česar niste prebrali nazaj. Ena zahteva po ustvarjanju prepreči edino napako v tem sistemu, ki je pozneje ni mogoče popraviti.

Kratki odgovori

• Kateri paket? Business.
• Preverjanje pristnosti? Authorization: Bearer enq_….
• Izgubljen ključ? Ni ga mogoče obnoviti: ustvarite novega in starega prekličite.
• Omejitev? 60 zahtev na minuto na račun.
• Sprememba cilja? Da, PATCH.
• Lokacija v podatkih? Ne.
• 500 kod enkratno? Nalaganje CSV.