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%.

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.