Limiti e uso corretto

I due contatori

I contatori sono dell'account: tutte le sue chiavi API attingono allo stesso budget. Il limite orario degli invii può essere alzato dal gestore per le integrazioni che servono molti punti vendita; quello delle letture no.

Le intestazioni

Ogni risposta riporta lo stato del contatore che ha usato:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1792454400

X-RateLimit-Reset è il momento dell'azzeramento in secondi Unix. Nella risposta di POST /v1/barcodes le intestazioni descrivono il contatore degli invii; in tutte le altre quello delle letture.

Cosa succede al superamento

La chiamata non viene eseguita, nemmeno in parte, e l'API risponde 429 Too Many Requests con l'intestazione Retry-After (secondi) e un corpo JSON:

{ "error": "rate_limited",
  "message": "Limite giornaliero di letture raggiunto: conserva i dati in cache.",
  "retryAfterSeconds": 41230 }

Per gli invii, un batch che supera i barcode rimasti nell'ora viene rifiutato per intero: se restano 30 invii e ne mandi 50, nessuno dei 50 viene registrato. Il corpo riporta anche limit e remaining. Riduci il batch o aspetta Retry-After.

Strategia di cache consigliata

1. Una volta al giorno: GET /v1/version

   Confronta version con l'ultima che hai importato. Se coincide, non fare altro: hai usato una lettura.

2. Solo se cambia: scarica un file

   Un solo formato, quello che usi. Invia If-None-Match con l'ETag dell'ultimo download: anche in caso di 304 la lettura si consuma, quindi è il manifest il vero controllo di cambiamento, non l'ETag.

3. Verifica, importa, conserva

   Controlla lo SHA-256, importa nel tuo database e salva versione ed ETag. Le casse e i client leggono dal tuo database, mai dall'API.

4. Ridistribuisci tu ai tuoi client

   Se il tuo software serve molte installazioni, scarica una volta sul tuo server e distribuisci il file ai client con i tuoi mezzi. Non dare la chiave API alle singole casse.

Così restano 8 letture di margine per i tentativi falliti, un controllo straordinario o GET /v1/me.

Quando conviene controllare

Le tariffe nuove vengono rilevate più volte al giorno; la release con i prezzi che entrano in vigore viene pubblicata il giorno della decorrenza. Un controllo al mattino presto (ora italiana) prende sia la tariffa pubblicata il giorno prima sia l'entrata in vigore del giorno stesso. Un controllo ogni dodici ore resta ampiamente dentro il limite.

Uso corretto

• Un account per organizzazione, non uno per installazione: aprire più account per moltiplicare le letture o le segnalazioni è vietato dai termini d'uso e comporta il blocco.
• Nessuna chiamata per ogni vendita, scansione o apertura di schermata: tutte le letture devono partire da un processo pianificato.
• In caso di 429 o di errore del server, riprova dopo Retry-After o il giorno dopo: non ripetere la chiamata in un ciclo.
• Segnala solo codici a barre letti davvero su una confezione: le segnalazioni inattendibili portano al blocco dell'account.
• Non usare i dati per pubblicità, promozione o marketing di prodotti del tabacco.

Nessuna garanzia di disponibilità

I dati sono forniti così come sono, senza garanzia di completezza, aggiornamento o disponibilità, come stabilito nei termini d'uso. Un software ben fatto continua a funzionare con l'ultima copia scaricata anche se l'API non risponde per qualche giorno.