Un'API per i QR code: cosa automatizzare e cosa no

La maggior parte dei QR code dovrebbe crearla una persona, una volta, e poi stamparli. Un'API si guadagna il posto dove questo è impossibile: un codice per ordine, per prenotazione, per cespite, per utente — creato in un momento imprevedibile e in quantità che nessuno vuole cliccare.

Quando l'API è la risposta giusta

• Un codice per record in un sistema che già gestite: biglietto, ordine di lavoro, targhetta, spedizione.
• Destinazioni calcolate, non scelte. Se l'URL si deduce dai vostri dati, riscriverlo non è una decisione ma una fonte di errori.
• Dati di scansione che devono stare nella vostra reportistica, accanto a ordini e fatturato.

Quando non lo è

• Una campagna di marketing. Mezza dozzina di codici scelti e disegnati da persone.
• Tutto ciò in cui conta il design. L'API crea e reindirizza; stile, cornici e modelli sono dell'editor.
• Un lotto singolo. Per quello c'è il caricamento CSV: un foglio di calcolo è un'integrazione più veloce di un'integrazione.

Autenticazione

La chiave si crea nel pannello e viene mostrata una sola volta. Si conserva solo un hash SHA-256 con i primi caratteri per distinguerle: una chiave persa non si recupera, si sostituisce.

Authorization: Bearer enq_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

L'API fa parte del piano Business. Limite: 60 richieste al minuto per account; oltre, 429 con rate_limited.

Creare un codice

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

{ "name": "Ordine 10432 – bolla", "url": "https://shop.example/orders/10432" }

• Mettete il vostro identificativo nel nome.
• Salvate l'id restituito accanto al vostro record.

Il resto

• GET /api/v1/qrcodes — i vostri codici, dal più recente, con paginazione a cursore.
• GET /api/v1/qrcodes/{id} — un codice.
• PATCH /api/v1/qrcodes/{id} — cambiare la destinazione. Su questo poggia l'intera idea del codice dinamico.
• DELETE /api/v1/qrcodes/{id} — eliminare; ciò che è stampato smette di funzionare.
• GET /api/v1/qrcodes/{id}/scans — fino a 1.000 scansioni, dalla più recente.

Cosa contiene una scansione

Ora, tipo di dispositivo, sistema e browser dichiarati, referrer se presente. Nessuna identità, nessun account e nessuna posizione: né città né paese. "Quante, quando, su che tipo di dispositivo": sì. "Chi" e "dove": no.

Errori reali

• 401 invalid_api_key
• 400 invalid_body — quasi sempre un URL che non lo è.
• 402 plan_limit_reached — Business non ha limiti, quindi la chiave è di un piano inferiore.
• 429 rate_limited

Due cose dal primo giorno

Rendete idempotente la creazione dalla vostra parte. Due chiamate creano due codici; i retry prima o poi chiamano due volte.

Non stampate ciò che non avete riletto. Una richiesta dopo la creazione evita l'unico errore irrecuperabile di tutto il sistema.

Risposte rapide

• Quale piano? Business.
• Autenticazione? Authorization: Bearer enq_….
• Chiave persa? Irrecuperabile: createne una nuova e revocate la vecchia.
• Limite? 60 richieste al minuto per account.
• Cambiare destinazione? Sì, PATCH.
• Posizione nelle scansioni? No.
• 500 codici una tantum? Caricamento CSV.