Dal consumo alla fattura

Una riga di fattura nasce dall'incontro di tre cose che vivono in posti diversi. Il motore le mette insieme; questa pagina dice in che ordine chiamarlo.

sorgente	cosa porta	dove sta
misure	consumo per fascia, già validato	il modulo Misure
offerta (CTE)	prezzo dell'energia per fascia	il tuo catalogo
tariffe regolate	oneri, trasporto, imposte, perdite	tabella condivisa, versionata

I passi

1 · Le misure sono pronte?

curl "${AUTH[@]}" "$API/v1/metering/stato?mese=2026-09"

Guarda salute e l'elenco problemi. Un mese con archivi letti solo in parte produce consumi in difetto senza che i numeri lo dicano.

2 · Quante bollette si possono emettere

curl "${AUTH[@]}" "$API/v1/metering/chiusura?mese=2026-09"

Dice quanti POD-mese sono in stato fatturabile e quanti no, con il motivo.

3 · Calcola, in anteprima

curl -X POST "${AUTH[@]}" "$API/v1/fatturazione/calcola" \
  -d '{ "mese": "2026-09", "pod": ["IT001E000000NN"] }'

{ "data": {
    "mese": "2026-09", "modalita": "anteprima",
    "versione_tariffe": "storico-2026-10-20b",
    "elaborati": 1, "scartati": [], "totale_imponibile": 347.90,
    "totali_per_categoria": {
      "energia": 84.51, "oneri_sistema": 148.92,
      "trasporto": 77.26, "imposte": 31.41 },
    "pod": [ {
      "pod": "IT001E000000NN", "opzione_tariffaria": "BTA5",
      "potenza_impegnata": 15.0, "perdite": 10.0, "kwh": 2513.011,
      "righe": [
        { "descrizione": "Energia F1", "categoria": "energia",
          "quantita": 1543.01, "prezzo_unitario": 0.033630, "importo": 51.89 },
        { "descrizione": "ASOS Quota Potenza", "categoria": "oneri_sistema",
          "quantita": 15.0, "prezzo_unitario": 1.300100, "importo": 19.50 },
        { "descrizione": "Art. 24.3 TIDE-Uplift", "categoria": "oneri_sistema",
          "quantita": 2764.31, "prezzo_unitario": 0.003326, "importo": 9.19 } ] } ] } }

È un'anteprima: non scrive niente. scrivi: true viene rifiutato finché il confronto con le fatture reali non è concluso. Creare documenti per distrazione è il modo peggiore di scoprire un errore di calcolo.

4 · Le righe diventano una fattura

curl -X POST "${AUTH[@]}" "$API/v1/fatture" -d '{ … }'      # bozza, con le righe
curl -X POST "${AUTH[@]}" "$API/v1/fatture/42/emetti"        # assegna il numero

Dall'emissione le righe sono immutabili: il modello non consente di modificarle fuori dalla bozza.

5 · Il documento per il cliente

curl "${AUTH[@]}" "$API/v1/metering/pod/IT001E000000NN/bolletta?mese=2026-09" -o bolletta.pdf

Come si forma la quantità

Questa è la parte che sbaglia chi la deduce dal nome della voce. Ogni componente dichiara la propria base di calcolo:

base	quantità
energia	i kWh consumati — moltiplicati per (1 + perdite) se la componente le applica
potenza	i kW impegnati dal punto
fissa	la quantità fissa della componente, di norma 1 al mese
reattiva	i kvarh del periodo

Le perdite non sono un dettaglio. Un punto in bassa tensione che ha consumato 2.513 kWh paga le voci di rete su 2.764,30 — il 10% in più. Le voci che le applicano si riconoscono dal campo applica_perdite in GET /v1/tariffe. In media tensione la percentuale è 3,8%.

Le tre regole che cambiano l'importo

Non sono dettagli di implementazione: decidono quanto paga il cliente. Sono state ricavate dal confronto con fatture reali, non dedotte dalla norma.

I kWh si fatturano arrotondati, fascia per fascia

Ogni fascia si arrotonda all'intero per conto suo, e il totale è la somma degli arrotondati — non l'arrotondamento della somma. Le perdite di rete si applicano dopo.

misurato   F1 433,42   F2 274,96   F3 349,44
fatturato  F1 433      F2 275      F3 349      totale 1.057
con perdite  1.057 × 1,10 = 1.162,70

Sommare prima e arrotondare dopo darebbe 1.058, e un kWh di differenza si moltiplica per il fattore di perdita e per ogni componente a base energia. Il valore misurato resta disponibile nel campo kwh_misurato, accanto a quello fatturato.

L'accisa dipende dall'uso

opzione tariffaria	aliquota
TDR, TDNR — uso domestico	0,0227 €/kWh
BTA1-BTA6, MTA1-MTA3, altre	0,0125 €/kWh

La distinzione è determinata dall'opzione tariffaria del punto, non da un campo separato.

Le quote fisse e di potenza si ragguagliano ai giorni

Un punto attivato a metà mese non deve il canone intero. Il periodo di competenza è la sovrapposizione fra il mese e il tratto in cui il punto è intestato, e le quote fisse e di potenza si riducono in proporzione:

punto attivo dal 21 settembre  →  10 giorni su 30  →  quota 0,3333
Trasporto Quota Potenza   2,889333 × 0,3333 = 0,963111 €/kW

L'energia non si ragguaglia: i kWh misurati sono già quelli del periodo, ridurli li conterebbe due volte.

Cosa viene scartato, e perché lo dice

Un punto che non si può calcolare non sparisce in silenzio: finisce in scartati con il motivo.

motivo	cosa fare
manca l'opzione tariffaria	caricare i dati tecnici del punto
nessuna offerta sul punto	collegare una CTE al punto
nessun consumo per il mese	il mese non è stato acquisito, o il POD non era attivo
l'offerta non ha prezzi	offerta indicizzata: il prezzo dipende dall'indice del mese, non dal listino

L'ultimo è il caso che merita attenzione: su un'offerta indicizzata il listino porta solo lo spread, e il prezzo dell'energia si compone con l'indice del periodo.

Quanto scala

Misurato: 2,7 ms per punto, più circa mezzo secondo fisso per caricare la tabella delle tariffe e interrogare le due banche dati.

punti	durata
25	505 ms
100	670 ms
200	966 ms
288	1,2 s

L'anteprima è tappata a 500 punti per chiamata, e il limite non è il tempo — è la dimensione della risposta. Ogni punto produce una ventina di righe di dettaglio: a 500 punti sono circa 1,5 MB, e il tetto di una risposta HTTP è 6 MB.

Per la chiusura di un parco grande, quindi, il calcolo è un lotto — non perché l'aritmetica sia lenta, ma perché il risultato va scritto, non restituito: duecentomila punti sono qualche milione di righe, che nessuna risposta HTTP può contenere. Stesso motore, un'altra scorza, come già avviene per le misure.

La versione delle tariffe

Ogni risposta porta versione_tariffe. Quel valore va conservato sul documento emesso. Fra un anno, davanti a una contestazione su un conguaglio, è l'unica cosa che permette di dimostrare quale tabella era in vigore. Senza, una fattura non è riproducibile.