Documentazione

Principi

• Scarica l'archivio una volta al giorno e usalo in locale. L'API non è pensata per consultazioni in tempo reale.
• Ogni account ha 10 letture al giorno (giorno UTC) e 100 barcode all'ora in invio. Sono due contatori separati e contano tutte le chiavi dell'account insieme.
• Un consumatore tipico usa due letture al giorno: una per sapere se c'è una versione nuova, una per scaricarla.
• Fonte dei prezzi: Agenzia delle Dogane e dei Monopoli (ADM). Servizio indipendente, non affiliato né approvato dall'ADM.

Guida rapida

1. Accedi e crea una chiave

   Richiedi il link di accesso da /login, poi dalla pagina del tuo account crea una chiave con un'etichetta (ad esempio il nome del tuo software). La chiave otb_… si vede una volta sola. Dettagli in Chiavi API.

2. Controlla la versione corrente

   Costa una lettura. Confronta version con quella che hai già salvato: se è uguale, hai finito per oggi.

   curl

   curl -H "Authorization: Bearer otb_la_tua_chiave" https://opentabacchi.org/v1/version

   risposta 200

   {
     "version": "20261014.2",
     "tariffDate": "2026-10-14",
     "generatedAt": "2026-10-14T09:00:00+00:00",
     "source": "Agenzia delle Dogane e dei Monopoli (ADM)",
     "schemaVersion": 1,
     "counts": { "products": 4343, "barcodes": 120 },
     "files": {
       "json":   { "url": "https://opentabacchi.org/v1/dataset.json.gz",   "sha256": "9f2c…", "size": 83912 },
       "sqlite": { "url": "https://opentabacchi.org/v1/dataset.sqlite.gz", "sha256": "4b71…", "size": 161280 },
       "blite":  { "url": "https://opentabacchi.org/v1/dataset.blite.gz",  "sha256": "c0de…", "size": 346112,
                  "bliteVersion": "5.2.3", "schemaVersion": 1 }
     }
   }

3. Scarica il file nel formato che preferisci

   Un'altra lettura. I tre file hanno lo stesso contenuto. Salva anche l'ETag della risposta: alla prossima chiamata, con If-None-Match, riceverai 304 se non è cambiato nulla.

   curl

   curl -H "Authorization: Bearer otb_la_tua_chiave" \
        -o opentabacchi.json.gz https://opentabacchi.org/v1/dataset.json.gz
   gunzip opentabacchi.json.gz

4. Verifica l'impronta e importa

   Confronta lo SHA-256 del file compresso con quello del manifest, poi carica i dati nel tuo database. Ogni prodotto ha questa forma (nel JSON; gli stessi campi esistono in SQLite e BLite):

   { "admCode": 12345, "name": "PRODOTTO DI ESEMPIO", "category": "Sigarette",
     "packaging": "Confezione da 20 pezzi", "packSize": 20, "packUnit": "pieces",
     "pricePerKg": 270.00, "priceCents": 540,
     "nextPriceCents": null, "nextPricePerKg": null, "nextEffectiveFrom": null,
     "status": "active" }

   Il significato di ogni campo e lo schema delle tabelle sono in Formati e schema.

5. Alla vendita, risolvi il codice a barre in locale

   Cerca il codice letto nella tabella dei codici a barre del tuo database, risali al codice AAMS e applica priceCents. Se il codice non è noto, puoi proporre l'abbinamento con POST /v1/barcodes: il tuo contributo, insieme a quello di altri due utenti, lo rende pubblico. Vedi Codici a barre.

Cosa succede se superi un limite

L'API risponde 429 con l'intestazione Retry-After e un corpo JSON con error: "rate_limited". Nessuna chiamata viene elaborata parzialmente. Le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset accompagnano ogni risposta, così il tuo software sa sempre quante letture restano. Dettagli in Limiti e uso corretto.