Vai al contenuto

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 in out/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).
  • T030 fa 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 esempio 2026-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_cessazione e numero_polizza_cessazione vanno compilati insieme;
  • l'adesione deve esistere, essere attiva e appartenere alla polizza madre del partner;
  • la data_cessazione non 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 è null e InfoGeneriche riporta 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

  1. In Postman: Import → File → selezionare openapi.yaml.
  2. Impostare la variabile del server sull'ambiente di test (https://testoverx-api.elbassicurazioni.it/api/v1).
  3. Eseguire il login e usare access_token come 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.