Guida di integrazione — Bolletta Protetta¶
Versione
1.1.0 — Riservato, esclusivamente per uso del partner.
1. Panoramica¶
Bolletta Protetta è una copertura parametrica collettiva legata all'andamento delle temperature: se l'indice cumulato, calcolato sulle temperature osservate nel periodo di copertura, raggiunge o supera la soglia associata all'adesione, REVO riconosce un indennizzo.
L'integrazione avviene tramite scambio di file CSV sull'area di scambio (FTP) messa a disposizione da REVO, nelle cartelle in, out, out/pdf e out/liquidazioni:
- il partner deposita ogni giorno il file con le nuove adesioni e gli storni in
in/; - REVO lo elabora e scrive in
out/un file con l'esito di ogni riga, e inout/pdf/il certificato di ogni adesione emessa; - una volta al mese REVO scrive in
out/liquidazioni/il file degli indennizzi; - l'andamento giornaliero dell'indice di ogni adesione è consultabile tramite API (§9).
Le credenziali di accesso all'area di scambio, il codice della polizza collettiva (polizza madre) e l'elenco dei valori ammessi per tipo_utenza sono forniti da REVO in base alle convenzioni definite in fase di creazione della collettiva. Viene staccata una polizza madre diversa per ogni tipologia di fornitura (energia elettrica EE e gas GAS); le singole adesioni hanno numero del tipo E0000123-000001242.
sequenceDiagram
participant Partner
participant REVO as Area di scambio REVO
Partner->>REVO: in/I_T030_BOLLETTAPROTETTA_YYYYMMDD.csv
REVO->>REVO: Elaborazione giornaliera (19:00 UTC)
REVO-->>Partner: out/O_T030_BOLLETTAPROTETTA_YYYYMMDD.csv (esito di ogni riga)
REVO-->>Partner: out/pdf/<numero_adesione>.pdf (certificati)
REVO-->>Partner: out/liquidazioni/L_T030_BOLLETTAPROTETTA_YYYYMMDD.csv (il 5 di ogni mese)
2. File e cartelle¶
| Cartella | File | Chi lo scrive | Note |
|---|---|---|---|
in/ |
I_T030_BOLLETTAPROTETTA_YYYYMMDD.csv |
Partner | Adesioni e storni. |
out/ |
O_T030_BOLLETTAPROTETTA_YYYYMMDD.csv |
REVO | Esito di ogni riga del file di input. |
out/pdf/ |
<numero_adesione>.pdf |
REVO | Certificato di ogni adesione emessa. |
out/liquidazioni/ |
L_T030_BOLLETTAPROTETTA_YYYYMMDD.csv |
REVO | Indennizzi del mese precedente. |
YYYYMMDDè la data del giorno di invio (per il file di input) o di elaborazione (per gli altri).T030fa parte del nome del file e va riportato così com'è.- Il file di input viene elaborato una volta al giorno, alle 19:00 UTC (20:00 in inverno, 21:00 in estate, ora italiana). Viene letto solo il file con la data del giorno: un file con un'altra data non viene elaborato. Se nella giornata non c'è alcun file, non viene eseguita alcuna operazione.
- Dopo l'elaborazione il file di input viene spostato in
in/elaborati/. - Il file di output contiene le stesse righe del file di input (nello stesso ordine) con le colonne di esito aggiunte alla fine. Le righe completamente vuote vengono ignorate.
3. File di input¶
3.1 Formato¶
- Formato CSV con separatore punto e virgola (
;). - La prima riga è l'intestazione e viene ignorata (non viene controllata): le colonne sono lette per posizione, nell'ordine indicato sotto. Ogni riga deve avere 15 colonne.
- Le date vanno indicate come
DD/MM/YYYY, senza orario (una data con orario, per esempio2026-10-01 00:00:00, viene scartata).
3.2 Colonne¶
| # | Colonna | Obbligatoria | Descrizione |
|---|---|---|---|
| 1 | codice_utenza |
sì | Codice univoco dell'utenza (normalmente il POD per l'energia elettrica o il PDR per il gas). Non sono ammesse due adesioni attive con lo stesso codice_utenza sulla stessa polizza madre, cioè sulla stessa fornitura. Per correggere un errore (per esempio un indirizzo sbagliato) si può stornare l'adesione e crearne un'altra con lo stesso codice. |
| 2 | pf_pg |
sì | PF persona fisica, PG persona giuridica. |
| 3 | nome |
solo se PF o ditta individuale |
Nome completo, coerente con il codice fiscale (con più nomi, il codice fiscale cambia). Vuoto per le società. |
| 4 | cognome_ragione_sociale |
sì | Cognome (PF e ditta individuale) oppure ragione sociale (società). |
| 5 | codice_fiscale_p_iva |
sì | Codice fiscale (PF e ditta individuale) oppure partita IVA (società). |
| 6 | email |
sì | Indirizzo email dell'aderente, in formato valido. Se per la convenzione non è richiesta, REVO lo comunica. |
| 7 | cellulare |
no | Numero di cellulare. |
| 8 | comune_residenza |
no | Comune di residenza. Non è utilizzata per l'emissione. |
| 9 | tipo_fornitura |
sì | EE energia elettrica, GAS gas. |
| 10 | indirizzo_ubicazione |
no | Indirizzo della fornitura. |
| 11 | codice_istat_comune |
sì | Codice ISTAT del comune della fornitura, a 6 cifre (con gli zeri iniziali, per esempio 001001). Determina il punto monitorato e la soglia. |
| 12 | data_attivazione |
sì | Data di attivazione della fornitura, DD/MM/YYYY. Inizio della copertura. |
| 13 | tipo_utenza |
sì | Tipologia di utenza. La lista dei valori verrà fornita da REVO in base alle convenzioni definite in fase di creazione della collettiva. |
| 14 | data_cessazione |
solo per gli storni | Data di cessazione, DD/MM/YYYY. |
| 15 | numero_polizza_cessazione |
solo per gli storni | Numero dell'adesione da stornare, come restituito nella colonna numero_adesione del file di output. |
3.3 Aderente: persona fisica, società, ditta individuale¶
| Caso | pf_pg |
nome |
cognome_ragione_sociale |
codice_fiscale_p_iva |
|---|---|---|---|---|
| Persona fisica | PF |
nome | cognome | codice fiscale |
| Società | PG |
vuoto | ragione sociale | partita IVA |
| Ditta individuale | PG |
nome | cognome | codice fiscale della persona (la partita IVA non serve) |
Controlli sul codice fiscale e sulla partita IVA:
- Persona fisica: il codice fiscale deve essere formalmente valido (16 caratteri, carattere di controllo) e coerente con nome e cognome. In caso contrario la riga è scartata con il messaggio «Inserire un Codice Fiscale italiano valido. Inserire il nome per esteso e, se in possesso di secondo nome, specificarlo nell'apposito campo "Nome"».
- Società: la partita IVA deve avere la cifra di controllo corretta (altrimenti «partita IVA non valida»).
3.4 Regole sulla data di attivazione¶
La data_attivazione non può essere anteriore al primo giorno del mese di due mesi prima della data di invio (per un file inviato a ottobre, non prima del 1° agosto). In caso contrario la riga è scartata con il messaggio «Data Attivazione non può essere anteriore a 2 mesi precedenti, rispetto al primo giorno del mese.».
3.5 Esempi¶
codice_utenza;pf_pg;nome;cognome_ragione_sociale;codice_fiscale_p_iva;email;cellulare;comune_residenza;tipo_fornitura;indirizzo_ubicazione;codice_istat_comune;data_attivazione;tipo_utenza;data_cessazione;numero_polizza_cessazione
145151351;PF;Mario;Rossi;RSSMRA80A01H501U;mario.rossi@example.com;3330000000;Roma;EE;Via Roma 1;001001;01/10/2026;<tipo_utenza>;;
453523623;PG;;Cubi Srl;02178720237;info@example.com;3335555555;Verona;EE;Via dell'Agricoltura 7;001001;01/10/2026;<tipo_utenza>;;
758456456;PF;Mario;Rossi;RSSMRA80A01H501U;mario.rossi@example.com;3334444444;Vicenza;EE;Via Prati 1;001001;01/10/2026;<tipo_utenza>;07/10/2026;E0000123-000001242
La terza riga è uno storno (§6). <tipo_utenza> va sostituito con un valore fornito da REVO.
4. File di output¶
Il file di output ripete le 15 colonne della riga di input e aggiunge 11 colonne calcolate da REVO:
| Colonna | Descrizione |
|---|---|
numero_adesione |
Numero dell'adesione emessa. Vuoto per le righe scartate e per gli storni. |
stato_polizza |
ATTIVA adesione emessa, SCARTO riga non elaborata, STORNO adesione stornata. |
data_inizio_copertura |
Inizio della copertura, formato YYYY-MM-DDTHH:MM:SS.000Z (UTC). |
data_fine_copertura |
Fine della copertura, stesso formato. |
latitudine_monitorata |
Latitudine del punto monitorato. |
longitudine_monitorata |
Longitudine del punto monitorato. |
consumo_medio_annuo |
Consumo medio annuo preso a riferimento. |
trigger |
Soglia dell'adesione: l'indennizzo spetta se l'indice raggiunge o supera questo valore (§7). |
somma_assicurata |
Somma assicurata. |
premio_lordo |
Premio lordo dell'adesione. |
note_scarto |
Motivo dello scarto (§5); vuoto se la riga è stata elaborata. |
L'intestazione del file di output è la seguente: la colonna 8 compare come indirizzo_residenza e riporta il valore inviato nella colonna comune_residenza dell'input.
codice_utenza;pf_pg;nome;cognome;codice_fiscale/p_iva;email;cellulare;indirizzo_residenza;tipo_fornitura;indirizzo_ubicazione;codice_istat_comune;data_attivazione;tipo_utenza;data_cessazione;numero_polizza_cessazione;numero_adesione;stato_polizza;data_inizio_copertura;data_fine_copertura;latitudine_monitorata;longitudine_monitorata;consumo_medio_annuo;trigger;somma_assicurata;premio_lordo;note_scarto
Esempi di righe di esito (valori indicativi):
145151351;PF;Mario;Rossi;RSSMRA80A01H501U;mario.rossi@example.com;3330000000;Roma;EE;Via Roma 1;001001;01/10/2026;<tipo_utenza>;;;E0000123-000001242;ATTIVA;2026-10-01T00:00:00.000Z;2027-09-30T23:59:00.000Z;45.36;7.77;2500;2841.2;40;12;
965462363;PF;Mario;Rossi;RSSMRA80A01H501U;mario.rossi@example.com;3332222222;Milano;EE;Corso Lodi 1;001001;01/05/2026;<tipo_utenza>;;;;SCARTO;;;;;;;;;emission API call failed: emission error: Data Attivazione non può essere anteriore a 2 mesi precedenti, rispetto al primo giorno del mese.
758456456;PF;Mario;Rossi;RSSMRA80A01H501U;mario.rossi@example.com;3334444444;Vicenza;EE;Via Prati 1;001001;01/10/2026;<tipo_utenza>;07/10/2026;E0000123-000001242;;STORNO;;;;;;;;;
Correggere una riga scartata
Le righe scartate non generano alcuna adesione. Correggere la riga e rinviarla nel file del giorno successivo (o del primo giorno utile). Se il messaggio di scarto non è comprensibile o non corrisponde a quanto concordato, aprire un ticket secondo le modalità concordate con la Compagnia.
5. Scarti: messaggi¶
Il messaggio in note_scarto ha uno dei prefissi seguenti, seguito dal motivo:
| Prefisso | Quando |
|---|---|
validation errors: |
Controlli formali sulla riga, prima dell'emissione. |
emission API call failed: emission error: |
Controlli effettuati in fase di emissione. |
deletion API call failed: deletion error: |
Controlli effettuati in fase di storno. |
Messaggi principali:
| Motivo | Messaggio |
|---|---|
| Campo obbligatorio vuoto | Campo <nome_colonna> non valorizzato (es. Campo codice_utenza non valorizzato) |
| Nome vuoto per PF | Campo nome non valorizzato per PF |
pf_pg non valido |
Campo pf_pg deve essere PF o PG |
tipo_fornitura non valido |
Campo tipo_fornitura deve essere EE o GAS |
| Email non valida | Formato email non valido |
| Data con orario | la data contiene un componente orario non ammesso: '<valore>' - inviare solo la data senza orario (es. DD/MM/YYYY o YYYY-MM-DD) |
| Data oltre la finestra | Data Attivazione non può essere anteriore a 2 mesi precedenti, rispetto al primo giorno del mese. |
| Codice fiscale non valido | Inserire un Codice Fiscale italiano valido. … (§3.3) |
| Partita IVA non valida | partita IVA non valida |
| Utenza già attiva | utenza con una adesione attiva |
Comune o tipo_utenza non configurati |
Impossibile recuperare temporaneamente la configurazione del servizio. Riprovare più tardi o contattare l'assistenza. — verificare codice_istat_comune e tipo_utenza prima di riprovare. |
| Cessazione incompleta | data_cessazione e numero_polizza_cessazione devono essere entrambi valorizzati o vuoti |
6. Storni¶
Per stornare un'adesione si invia, nel file del giorno, una riga con data_cessazione e numero_polizza_cessazione valorizzati (le altre colonne ripetono i dati dell'adesione). Il numero da indicare è quello restituito nella colonna numero_adesione del file di output.
Regole:
data_cessazioneenumero_polizza_cessazionevanno compilati insieme;- l'adesione deve esistere, essere attiva e appartenere alla polizza madre del partner;
- la
data_cessazionenon può essere successiva alla fine della copertura; - gli storni sono effettuati al netto delle tasse: l'importo rimborsato è il premio netto dell'adesione (non è riportato nel file di output).
Nel file di output la riga di storno riporta stato_polizza = STORNO, con numero_adesione vuoto; il numero stornato resta nella colonna numero_polizza_cessazione.
Scarti possibili in fase di storno:
| Motivo | Messaggio |
|---|---|
| Adesione già stornata | deletion API call failed: deletion error: l'adesione non è attiva |
| Adesione inesistente | deletion API call failed: deletion error: adesione non trovata |
| Data oltre la fine copertura | deletion API call failed: deletion error: data annullamento successiva alla data cessazione |
| Data non valida | deletion API call failed: deletion error: formato dataCessazione non valido |
| Adesione di un'altra convenzione | cancellation: nessuna polizza madre trovata per <polizza madre> |
7. File degli indennizzi¶
Il 5 di ogni mese alle 07:00 UTC REVO scrive in out/liquidazioni/ il file L_T030_BOLLETTAPROTETTA_YYYYMMDD.csv, con un record per ogni adesione il cui periodo di copertura è terminato nel mese precedente, anche se l'indennizzo è zero. Se non ci sono record il file non viene scritto.
| Colonna | Descrizione |
|---|---|
numero_polizza |
Numero dell'adesione (colonna numero_adesione del file di output). |
data_scadenza |
Fine della copertura, DD/MM/YYYY. |
indennizzo |
Indennizzo in euro, con due decimali (es. 40.00). |
codice_utenza |
codice_utenza comunicato dal partner nel file di input. |
indice |
Indice cumulato osservato nel periodo di copertura. |
id_sinistro |
Identificativo del sinistro in REVO, utile per segnalare a REVO eventuali problemi su un sinistro specifico. Vuoto se non è stato aperto alcun sinistro. |
L'indice può essere confrontato con la soglia (colonna trigger del file di output): se indice ≥ soglia l'indennizzo è maggiore di zero.
8. Certificati¶
Per ogni adesione emessa REVO scrive in out/pdf/ il certificato di polizza, con nome <numero_adesione>.pdf.
9. API di monitoraggio dell'indice¶
L'API restituisce, per una singola adesione, l'andamento giornaliero dell'indice monitorato (temperatura media giornaliera, in °C) a partire dall'inizio della copertura.
9.1 Autenticazione¶
La chiamata richiede un Bearer Token nell'header Authorization, ottenuto con il login usando le credenziali fornite da REVO:
POST /api/v1/sicurezza/login
Host: testoverx-api.elbassicurazioni.it
Content-Type: application/json
{
"username": "<username>",
"password": "<password>"
}
Risposta (200):
{
"access_token": "<jwt>",
"token_type": "Bearer",
"expires_in": 2400,
"refresh_token": "<refresh_token>",
"refresh_expires_in": 28799
}
| Campo | Descrizione |
|---|---|
access_token |
JWT da inviare in Authorization: Bearer <access_token> |
token_type |
Sempre Bearer |
expires_in |
Validità del token in secondi (2400, cioè 40 minuti): alla scadenza o quando una chiamata risponde 401 si ripete il login |
refresh_token, refresh_expires_in |
Token di rinnovo e relativa validità in secondi |
La risposta può contenere altri campi non descritti qui, che vanno ignorati.
| Scenario del login | Stato HTTP | Corpo |
|---|---|---|
Credenziali errate, utente sconosciuto, username mancante o valori vuoti |
400 | {"status": 5400, "message": "Wrong login access", "error": "WrongRequest"} |
Corpo vuoto o senza il campo password |
403 | Nessun corpo |
9.2 Endpoint¶
| Ambiente | Base URL |
|---|---|
| Test | https://testoverx-api.elbassicurazioni.it/api/v1 |
| Produzione | Fornito separatamente dal team Overx |
| Metodo | Path | Descrizione | Sezione |
|---|---|---|---|
POST |
/sicurezza/login |
Ottiene il Bearer Token | `9.1 |
GET |
/reverse-proxy/blockchain/collettive/adesione/oracolo |
Andamento giornaliero dell'indice di un'adesione | `9.3 |
9.3 Richiesta¶
GET /api/v1/reverse-proxy/blockchain/collettive/adesione/oracolo?adesione=E0000123-000001242&codice_intermediario=<codice_intermediario>
Host: testoverx-api.elbassicurazioni.it
Authorization: Bearer <access_token>
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
adesione |
stringa | sì | Numero dell'adesione, come restituito nella colonna numero_adesione del file di output (formato <polizza madre>-<progressivo>). Le maiuscole sono significative e non sono ammessi spazi. Un'adesione già stornata viene comunque restituita |
codice_intermediario |
stringa | sì | Codice intermediario della polizza collettiva, fornito da REVO. Deve coincidere esattamente con quello della polizza dell'adesione, compresi gli zeri iniziali (0539 è diverso da 539) |
data |
stringa | no | Non utilizzato per questo prodotto: se presente viene ignorato (non viene validato) |
Esempio:
curl --location 'https://testoverx-api.elbassicurazioni.it/api/v1/reverse-proxy/blockchain/collettive/adesione/oracolo?adesione=E0000123-000001242&codice_intermediario=<codice_intermediario>' \
--header 'Authorization: Bearer <access_token>'
9.4 Risposta (200 OK)¶
{
"idEvento": "N0369300E0147300",
"TitoloPopup": "Temperatura Media",
"InfoGeneriche": "Media delle temperature da 01/10/2026 a 30/09/2027",
"headers": {
"data": "Data",
"oraInizio": "Ora Inizio",
"oraFine": "Ora Fine",
"indice": "Temperatura Media (°C)"
},
"dettaglio": [
{ "data": "01/10/2026", "oraInizio": "00.00", "oraFine": "23.59", "indice": 7.3125, "highlight": 0 },
{ "data": "02/10/2026", "oraInizio": "00.00", "oraFine": "23.59", "indice": 6.9, "highlight": 0 }
]
}
I valori numerici dell'esempio sono indicativi.
| Campo | Tipo | Descrizione |
|---|---|---|
idEvento |
stringa | Identificativo della fonte dell'indice per il punto monitorato: adesioni nello stesso punto hanno lo stesso valore |
TitoloPopup |
stringa | Titolo dell'indice: Temperatura Media |
InfoGeneriche |
stringa | Descrizione dell'indice e periodo di riferimento (dd/MM/yyyy) |
headers |
oggetto | Intestazioni delle colonne di dettaglio; headers.indice riporta nome e unità dell'indice (Temperatura Media (°C)) |
dettaglio |
array o null |
Valori giornalieri, in ordine di data. null se non c'è alcun valore disponibile |
dettaglio[].data |
stringa | Giorno, formato dd/MM/yyyy |
dettaglio[].oraInizio |
stringa | Inizio dell'osservazione: 00.00 |
dettaglio[].oraFine |
stringa | Fine dell'osservazione: 23.59 |
dettaglio[].indice |
numero | Valore dell'indice del giorno (separatore decimale: punto) |
dettaglio[].highlight |
intero | Campo usato dall'interfaccia per evidenziare le fasce orarie nei prodotti con indice orario; per questo prodotto l'indice è giornaliero e vale sempre 0 |
Regole sul contenuto di dettaglio:
- contiene un elemento per ogni giorno per cui l'indice è disponibile, dall'inizio della copertura fino all'ultimo giorno caricato: possono esserci giorni mancanti e il numero di elementi non è necessariamente quello dei giorni di copertura;
- se la copertura non è ancora iniziata,
dettaglioènulleInfoGenericheriporta comunque l'intero periodo; - per le adesioni pluriennali vengono restituiti solo i giorni del primo periodo annuale di copertura.
Le temperature riportate sono medie giornaliere in °C. L'indice cumulato usato per l'indennizzo (colonna indice del file degli indennizzi, `7) è calcolato da REVO a partire dalle temperature e dalle soglie di riferimento dell'adesione: non coincide con la semplice somma dei valori restituiti da questa API.
9.5 Errori¶
In caso di errore la risposta ha corpo {"message": "…"} (tranne dove indicato).
| Stato | Messaggio | Quando |
|---|---|---|
| 400 | 'codiceIntermediaro' non valido |
codice_intermediario assente o vuoto (il refuso fa parte del messaggio) |
| 400 | codice intermediario non valido |
codice_intermediario non coincide con quello della polizza dell'adesione |
| 401 | error = unauthorized, error_description, path |
Token malformato, non valido o scaduto: ripetere il login (l'header WWW-Authenticate riporta il dettaglio) |
| 403 | (nessun corpo) | Header Authorization assente |
| 404 | adesione non trovata |
adesione assente, vuota o inesistente (maiuscole e spazi inclusi) |
| 500 | errore nel recupero dati o errore nel recupero dei dati della adesione |
Errore interno: se persiste, aprire un ticket secondo le modalità concordate con la Compagnia |
9.6 Note tecniche¶
Formato data e ora¶
Le date sono nel formato dd/MM/yyyy. Gli orari usano 00.00 e 23.59 (separatore il punto).
Separatore decimale¶
indice è un numero JSON con il punto come separatore decimale, non una stringa.
Nomi dei campi¶
I nomi dei campi sono sensibili alle maiuscole: TitoloPopup e InfoGeneriche iniziano con la maiuscola, gli altri con la minuscola.
Validità del token¶
Il token dura 2400 secondi: in un processo che interroga molte adesioni conviene rinnovare il login alla scadenza, senza aspettare il 401.
9.7 Importazione della specifica in Postman¶
- In Postman: Import → File → selezionare
openapi.yaml. - Impostare la variabile del server sull'ambiente di test (
https://testoverx-api.elbassicurazioni.it/api/v1). - Eseguire il login e usare
access_tokencome Bearer Token nella richiesta di monitoraggio.
10. Cronologia della pagina¶
| Versione | Data | Modifiche |
|---|---|---|
| 1.1.0 | 2026-10-07 | Documentati richiesta, risposta ed errori dell'API di monitoraggio dell'indice. |
| 1.0.0 | 2026-10-07 | Prima pubblicazione. |