Come funziona

1. La fonte: Agenzia delle Dogane e dei Monopoli

I prezzi di vendita al pubblico dei tabacchi lavorati sono fissati dall'Agenzia delle Dogane e dei Monopoli (ADM) e pubblicati come tariffa con una data di decorrenza. Ogni riga riporta categoria, codice AAMS, denominazione commerciale, prezzo al chilogrammo, prezzo della confezione e tipo di confezione. OpenTabacchi non modifica questi valori: li converte in un formato strutturato e li ripubblica. Il servizio è indipendente, non affiliato né approvato dall'ADM.

2. Importazione controllata

Più volte al giorno il servizio verifica se è stata pubblicata una tariffa con una nuova data di decorrenza. Quando la trova, importa il tariffario completo e lo confronta con i dati già in archivio, riga per riga, calcolando prodotti nuovi, prodotti variati e prodotti non più presenti.

Prima di applicare l'importazione si eseguono controlli automatici. Alcune condizioni sono bloccanti e fermano la pubblicazione in attesa di una revisione manuale:

• una tariffa con data più vecchia dell'ultima applicata, o una seconda tariffa con la stessa data ma contenuto diverso;
• un prezzo non valido (zero o negativo);
• una variazione del numero di prodotti superiore al 5 % rispetto all'archivio;
• prezzi che cambiano di oltre il 30 %;
• incoerenze tra il tariffario completo e l'elenco delle sole variazioni, quando l'ADM lo pubblica.

Altre condizioni sono solo avvisi (una categoria mai vista prima, confezioni di cui non si riconosce il formato) e non fermano nulla. Un'importazione senza anomalie bloccanti viene applicata automaticamente; una con anomalie resta in attesa e viene applicata o rifiutata da una persona. In ogni caso il risultato è registrato e verificabile.

Un prodotto che manca da due tariffari completi consecutivi passa allo stato delisted invece di sparire: il codice AAMS resta disponibile per le giacenze e i documenti già emessi.

3. Prezzi con decorrenza futura

Quando una tariffa ha decorrenza futura, il dataset espone sia il prezzo in vigore oggi (priceCents) sia quello che entrerà in vigore (nextPriceCents, con nextEffectiveFrom). Alla data di decorrenza, calcolata nell'ora italiana, il prezzo nuovo diventa quello corrente e viene pubblicata una release con il prezzo già in vigore. Il tuo software può scegliere se applicare la data da sé o aspettare la release.

4. Release versionate

Una release nasce solo quando cambia qualcosa nei dati pubblicati: una nuova tariffa, l'entrata in vigore di un prezzo, l'approvazione o la revoca di codici a barre. La versione ha la forma AAAAMMGG.n, dove la data è quella della tariffa in vigore e n è un progressivo. Ogni release produce tre file equivalenti, compressi con gzip, con un'impronta SHA-256 pubblicata nel manifest di /v1/version.

Le modifiche ai codici a barre vengono raccolte per alcuni minuti prima di pubblicare, così una serie di approvazioni ravvicinate produce una sola release.

5. Download da parte del software

Il consumatore tipico esegue due chiamate al giorno: GET /v1/version e, solo se la versione è cambiata, il download del file. Le risposte dei file portano un ETag; con If-None-Match si riceve 304 quando non c'è nulla di nuovo. Il modello è spiegato in Limiti e uso corretto e la sequenza completa nella guida rapida.

I codici a barre

I codici a barre non fanno parte della tariffa: li propongono gli utenti registrati e i produttori. Un abbinamento entra nel dataset quando tre contributori indipendenti lo confermano, oppure quando lo carica un produttore verificato per i prodotti del suo perimetro. Le regole, gli stati e la gestione dei conflitti sono descritti in Come funzionano i codici a barre.