Configurazione: prezzi, corrispettivi e componenti regolate

Una bolletta nasce da tre sorgenti diverse, e distinguerle è la cosa che rende il sistema gestibile. Non sono tre tabelle: sono tre proprietari.

	chi la decide	dove vive
Prezzo dell'energia	tu, nell'offerta	offerte_prezzi, per fascia
Corrispettivi commerciali	tu, nell'offerta o nel contratto	corrispettivi
Componenti regolate	ARERA	file versionato, GET /v1/tariffe

Il prezzo dell'energia

Sta nell'offerta (CTE) e si esprime per fascia. Quante fasce ci siano lo decide la tariffazione scelta — monoraria, bioraria, trioraria.

curl -X POST "${AUTH[@]}" "$API/v1/cte/12/prezzi" \
  -d '{ "fascia_tariffaria_id": 1, "prezzo": 0.23998, "unita_misura_id": 3 }'

Riscrivere la stessa fascia aggiorna il prezzo: non si creano doppioni.

I corrispettivi commerciali

Sono le voci che decidi tu: il canone di commercializzazione, uno sconto promozionale, una quota fissa negoziata con un cliente grande.

Ciascuno appartiene a una delle due cose, mai a entrambe:

• tipo: "cte" → appartiene a un'offerta: vale per chiunque la sottoscriva
• tipo: "cgf" → appartiene a un contratto: vale per quel cliente soltanto

curl -X POST "${AUTH[@]}" "$API/v1/corrispettivi" \
  -d '{ "tipo": "cte", "cte_id": 12,
        "nome": "Corrispettivo di commercializzazione",
        "codice_fatturazione": "CCV", "unita_misura_id": 4,
        "corrispettivo_unitario": 20.0, "data_inizio": "2026-01-01" }'

Quando si applica: le regole

Un corrispettivo senza regole si applica sempre. Con una regola si qualifica su dimensioni indipendenti, che si combinano:

curl -X POST "${AUTH[@]}" "$API/v1/corrispettivi/88/regole" \
  -d '{ "opzioni_tariffarie": ["BTA4","BTA5"],
        "tipi_uso": ["EE_ALTRI_USI"],
        "potenza_min_kw": 10, "potenza_max_kw": 30 }'

Regola e condizioni si creano insieme, in una chiamata sola. Crearle in due passi lascerebbe viva, nel mezzo, una regola senza condizioni — cioè una che si applica a tutto.

Le componenti regolate

Oneri di sistema, trasporto, imposte: ASOS, ARIM, UC3, UC6, gli articoli TIDE, il Capacity Market. Non le decidi tu e non appartengono a nessuna offerta. Le fissa ARERA, valgono per chiunque venda energia in Italia, e cambiano ogni trimestre.

Per questo non stanno nel database del tuo tenant ma in un file versionato, condiviso e letto dall'API:

curl "${AUTH[@]}" "$API/v1/tariffe?al=2026-09-15&opzione=BTA4"

{ "data": {
    "versione": "storico-2026-10-20",
    "in_vigore_al": "2026-09-15",
    "perdite_di_rete": [
      { "opzione": "BTA4", "dal": "2023-01-01", "percentuale": 10.0 } ],
    "elementi": [
      { "nome": "ASOS Quota Potenza", "applica_perdite": false,
        "valori": [ { "opzione": "BTA4", "valore": 1.3001 } ] } ] } }

Le perdite di rete

applica_perdite è il campo che separa una bolletta giusta da una sbagliata del 10%.

Quando è vero, la quantità su cui si calcola la voce non è il consumo: è il consumo moltiplicato per (1 + perdite). Un punto in bassa tensione che ha consumato 2.513 kWh paga quelle voci su 2.764,30.

La percentuale dipende dall'opzione tariffaria: 10% in bassa tensione, 3,8% in media.

La versione va conservata

GET /v1/tariffe restituisce sempre un campo versione. Quel valore va salvato su ogni documento emesso.

Il motivo è pratico: fra un anno, davanti a una contestazione su un conguaglio, devi poter dimostrare quale tabella tariffaria era in vigore quando hai emesso quella fattura. Senza la versione, una bolletta non è riproducibile — e una bolletta non riproducibile non è difendibile.

GET /v1/tariffe/versioni elenca tutte le versioni pubblicate.

I dizionari

Fasce, unità di misura, opzioni tariffarie, tipi d'uso, zone geografiche: servono tutti insieme quando si costruisce un'offerta, e arrivano in una chiamata sola.

curl "${AUTH[@]}" "$API/v1/riferimenti"