Formati e schema dei dati

I campi e il loro significato

Prodotti

Codici a barre

Nel dataset compaiono solo i codici a barre approvati; quelli da confermare, in conflitto o revocati non vengono pubblicati. Vedi Codici a barre.

Metadati

Prezzi e decorrenza

• priceCents è il prezzo di vendita al pubblico di una confezione, in centesimi di euro, valido oggi. Per il prezzo unitario di un pezzo dividi per packSize quando packUnit è pieces.
• Se una tariffa ha decorrenza futura, il prezzo nuovo è in nextPriceCents con la data in nextEffectiveFrom: applicalo da quel giorno (ora italiana). Il giorno della decorrenza viene comunque pubblicata una release con il prezzo già in vigore e i campi next* azzerati.
• packSize e packUnit derivano dal testo di packaging; se il formato non si riconosce restano nulli e va usato il testo.
• Un prodotto che esce dalla tariffa passa a status: "delisted" con l'ultimo prezzo noto, invece di sparire: così puoi continuare a gestire giacenze e resi. Non venderlo come se fosse in tariffa.

JSON

GET /v1/dataset.json.gz. Un unico oggetto con tre proprietà: meta, products (ordinati per codice AAMS) e barcodes (ordinati per codice). Nomi in camelCase, valori nulli presenti esplicitamente, numeri decimali come numeri JSON.

{
  "meta": {
    "version": "20261014.2", "tariffDate": "2026-10-14", "generatedAt": "2026-10-14T09:00:00+00:00",
    "source": "Agenzia delle Dogane e dei Monopoli (ADM)", "schemaVersion": 2
  },
  "products": [
    { "admCode": 12345, "name": "PRODOTTO DI ESEMPIO", "category": "Sigarette", "brand": "PRODOTTO",
      "packaging": "Confezione da 20 pezzi", "packSize": 20, "packUnit": "pieces",
      "pricePerKg": 270.00, "priceCents": 540,
      "nextPriceCents": 560, "nextPricePerKg": 280.00, "nextEffectiveFrom": "2026-11-01",
      "status": "active" },
    { "admCode": 12346, "name": "ALTRO PRODOTTO DI ESEMPIO", "category": "Trinciati per sigarette", "brand": "ALTRO",
      "packaging": "Busta da 30 grammi", "packSize": 30, "packUnit": "grams",
      "pricePerKg": 210.00, "priceCents": 630,
      "nextPriceCents": null, "nextPricePerKg": null, "nextEffectiveFrom": null,
      "status": "delisted" }
  ],
  "barcodes": [
    { "barcode": "4006381333931", "admCode": 12345, "kind": "pack", "unitsPerBarcode": 1 },
    { "barcode": "4006381333948", "admCode": 12345, "kind": "carton", "unitsPerBarcode": 10 }
  ]
}

SQLite

GET /v1/dataset.sqlite.gz. Un database SQLite 3 con tre tabelle; i nomi delle colonne sono in snake_case. PRAGMA user_version vale schemaVersion. Le date sono testo ISO (AAAA-MM-GG).

CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
CREATE TABLE products (
    adm_code INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    category TEXT NOT NULL,
    brand TEXT NOT NULL,
    packaging TEXT NOT NULL,
    pack_size REAL,
    pack_unit TEXT,
    price_per_kg REAL NOT NULL,
    price_cents INTEGER NOT NULL,
    next_price_cents INTEGER,
    next_price_per_kg REAL,
    next_effective_from TEXT,
    status TEXT NOT NULL);
CREATE INDEX ix_products_name ON products (name);
CREATE INDEX ix_products_brand ON products (brand);
CREATE TABLE barcodes (
    barcode TEXT PRIMARY KEY,
    adm_code INTEGER NOT NULL,
    kind TEXT NOT NULL,
    units_per_barcode INTEGER NOT NULL);
CREATE INDEX ix_barcodes_adm_code ON barcodes (adm_code);

La tabella meta contiene le chiavi schemaVersion, version, tariffDate, generatedAt e source. Esempio d'uso alla cassa:

SELECT p.adm_code, p.name, p.price_cents, b.kind, b.units_per_barcode
FROM barcodes b JOIN products p ON p.adm_code = b.adm_code
WHERE b.barcode = '4006381333931';

BLite

GET /v1/dataset.blite.gz. Un file per chi usa il database embedded BLite in .NET: si apre direttamente, senza importazione, con un DocumentDbContext che dichiara le stesse collezioni, gli stessi indici e la stessa dimensione di pagina (32 KB, PageFileConfig.Large).

I tipi dei campi sono quelli del JSON (decimal? per PackSize, string? per NextEffectiveFrom in formato AAAA-MM-GG, int per i centesimi).

var manifest = await GetVersionAsync();                       // GET /v1/version
var blite = manifest.Files.Blite;
if (blite.BliteVersion != MyBliteVersion || blite.SchemaVersion != MySchemaVersion)
    return await DownloadAsync(manifest.Files.Json.Url);         // ripiego senza vincoli
return await DownloadAsync(blite.Url);

Versioni dello schema

schemaVersion cambia solo se cambiano i campi o il loro significato; oggi vale 2. L'aggiunta di un campo facoltativo non è esclusa anche a schema invariato: un importatore robusto ignora i campi che non conosce. La versione della release (version) cambia invece a ogni variazione dei dati ed è quella da confrontare ogni giorno.