Guida di integrazione — Fotovoltaico¶
Versione
1.1.0 — Riservato, esclusivamente per uso del partner.
1. Panoramica¶
Fotovoltaico è una copertura parametrica collettiva legata all'irraggiamento solare: se l'irraggiamento cumulato osservato in un periodo annuale di monitoraggio è inferiore alla 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 di convenzione (codice_sconto), il codice della polizza collettiva (polizza madre) e l'elenco delle taglie ammesse sono forniti da REVO in base alle convenzioni definite in fase di creazione della collettiva. Le adesioni hanno numero del tipo E0000123-000001242.
La durata della copertura dipende dalla convenzione (annuale o pluriennale). Per le adesioni pluriennali il monitoraggio e il confronto con la soglia avvengono alla fine di ogni anno di copertura.
sequenceDiagram
participant Partner
participant REVO as Area di scambio REVO
Partner->>REVO: in/I_T030_FOTOVOLTAICO_YYYYMMDD.csv
REVO->>REVO: Elaborazione giornaliera
REVO-->>Partner: out/O_T030_FOTOVOLTAICO_YYYYMMDD.csv (esito di ogni riga)
REVO-->>Partner: out/pdf/<numero_adesione>.pdf (certificati)
REVO-->>Partner: out/liquidazioni/L_T030_FOTOVOLTAICO_YYYYMMDD.csv (mensile)
2. File e cartelle¶
| Cartella | File | Chi lo scrive | Note |
|---|---|---|---|
in/ |
I_T030_FOTOVOLTAICO_YYYYMMDD.csv |
Partner | Adesioni e storni. |
out/ |
O_T030_FOTOVOLTAICO_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_FOTOVOLTAICO_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, in serata; l'orario esatto è comunicato da REVO. 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: 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. Un altro formato (per esempio2026-10-01) fa scartare la riga.
3.2 Colonne¶
| # | Colonna | Obbligatoria | Descrizione |
|---|---|---|---|
| 1 | codice_ordine |
sì | Codice univoco dell'ordine/impianto. Non sono ammesse due adesioni attive con lo stesso codice_ordine sulla stessa polizza madre. |
| 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. |
| 7 | cellulare |
no | Numero di cellulare. |
| 8 | codice_sconto |
no | Codice di convenzione comunicato da REVO. Se vuoto si applica la convenzione di default del partner; se valorizzato deve corrispondere a una convenzione valida. |
| 9 | indirizzo_ubicazione |
no | Indirizzo dell'impianto. |
| 10 | codice_istat_comune |
sì | Codice ISTAT del comune dell'impianto, a 6 cifre (con gli zeri iniziali). Determina il punto monitorato e la soglia. |
| 11 | data_fine_collaudo |
no | Data di fine collaudo, quando l'impianto è pronto. Non determina l'inizio della copertura. |
| 12 | data_allaccio |
sì | Data di allaccio dell'impianto, DD/MM/YYYY. La copertura inizia il primo giorno del mese successivo. |
| 13 | taglia |
sì | Taglia dell'impianto, tra quelle concordate con REVO. |
| 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:
- 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, quando prevista dalla convenzione, deve avere la cifra di controllo corretta (altrimenti «partita IVA non valida»).
3.4 Regole sulla data di allaccio¶
La data_allaccio 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.».
La copertura inizia il primo giorno del mese successivo alla data_allaccio (con allaccio al 01/10/2026 la copertura inizia il 01/11/2026).
3.5 Esempi¶
codice_ordine;pf_pg;nome;cognome_ragione_sociale;codice_fiscale_p_iva;email;cellulare;codice_sconto;indirizzo_ubicazione;codice_istat_comune;data_fine_collaudo;data_allaccio;taglia;data_cessazione;numero_polizza_cessazione
145151351;PF;Mario;Rossi;RSSMRA80A01H501U;mario.rossi@example.com;3330000000;<codice_convenzione>;Via Roma 1;001002;30/09/2026;01/10/2026;<taglia>;;
453523623;PG;;Cubi Srl;02178720237;info@example.com;3335555555;<codice_convenzione>;Via dell'Agricoltura 7;001002;;01/10/2026;<taglia>;;
758456456;PF;Mario;Rossi;RSSMRA80A01H501U;mario.rossi@example.com;3334444444;<codice_convenzione>;Via Prati 1;001002;;01/10/2026;<taglia>;07/10/2026;E0000123-000001242
La terza riga è uno storno (§6). <codice_convenzione> e <taglia> vanno sostituiti con valori forniti 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. |
trigger |
Soglia dell'adesione: l'indennizzo spetta se l'indice cumulato del periodo annuale è inferiore a questo valore (§7). |
somma_assicurata |
Somma assicurata. |
indennizzo_annuale |
Indennizzo riconosciuto per ogni periodo annuale. |
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 (le colonne 4 e 5 compaiono come cognome e codice_fiscale/p_iva):
codice_ordine;pf_pg;nome;cognome;codice_fiscale/p_iva;email;cellulare;codice_sconto;indirizzo_ubicazione;codice_istat_comune;data_fine_collaudo;data_allaccio;taglia;data_cessazione;numero_polizza_cessazione;numero_adesione;stato_polizza;data_inizio_copertura;data_fine_copertura;latitudine_monitorata;longitudine_monitorata;trigger;somma_assicurata;indennizzo_annuale;premio_lordo;note_scarto
Esempi di righe di esito (valori indicativi):
145151351;PF;Mario;Rossi;RSSMRA80A01H501U;mario.rossi@example.com;3330000000;<codice_convenzione>;Via Roma 1;001002;30/09/2026;01/10/2026;<taglia>;;;E0000123-000001242;ATTIVA;2026-11-01T00:00:00.000Z;2027-10-31T23:59:00.000Z;44.917;7.484;1383472.54;199.00;199.00;15.27;
965462363;PF;Mario;Rossi;RSSMRA80A01H501U;mario.rossi@example.com;3332222222;<codice_convenzione>;Via Prati 1;001002;;01/05/2026;<taglia>;;;;SCARTO;;;;;;;;;Data Attivazione non può essere anteriore a 2 mesi precedenti, rispetto al primo giorno del mese.
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 riporta il motivo. Messaggi principali:
| Motivo | Messaggio |
|---|---|
| Campo obbligatorio vuoto | Campo <nome_colonna> non valorizzato (es. Campo taglia non valorizzato) |
| Nome vuoto per PF | Campo nome non valorizzato |
pf_pg non valido |
Campo pf_pg deve essere PF o PG |
| Email vuota | Indirizzo mail richiesto |
| Data in formato errato | invalid date "<valore>", expected DD/MM/YYYY |
| 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 |
| Taglia non concordata | Taglia impianto non supportata |
| Convenzione non valida | polizza madre non trovata |
| Codice ordine già attivo | utenza con una adesione attiva |
| Comune non configurato | Codice Comune non presente nelle configurazioni oppure Impossibile recuperare temporaneamente la configurazione del servizio. Riprovare più tardi o contattare l'assistenza. — verificare codice_istat_comune prima di riprovare. |
| Cessazione incompleta | Presenza di data_cessazione senza numero_polizza_cessazione o viceversa |
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.
TBD — esito dello storno
TBD (OBC-4758): la riga di output di uno storno (stato_polizza, importo rimborsato in premio_lordo) e il calcolo del rimborso per i periodi annuali non goduti saranno documentati dopo la verifica dal vivo, che oggi non è possibile finché non è corretto OBC-4758.
Scarti possibili in fase di storno: l'adesione non è attiva, adesione non trovata, data annullamento successiva alla data cessazione, formato dataCessazione non valido, preceduti da errore storno.
7. File degli indennizzi¶
Una volta al mese REVO scrive in out/liquidazioni/ il file L_T030_FOTOVOLTAICO_YYYYMMDD.csv, con un record per ogni periodo annuale di copertura terminato nel mese precedente, anche se l'indennizzo è zero.
| Colonna | Descrizione |
|---|---|
numero_polizza |
Numero dell'adesione (colonna numero_adesione del file di output). |
data_scadenza |
Fine del periodo annuale, DD/MM/YYYY. |
indennizzo |
Indennizzo in euro. |
L'indennizzo è maggiore di zero se l'irraggiamento cumulato nel periodo annuale è inferiore alla soglia (colonna trigger del file di output). L'indennizzo di ogni periodo annuale viene riconosciuto una sola volta. L'andamento dell'indice è consultabile con l'API (§9).
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 (irraggiamento giornaliero (GHI) osservato nel punto monitorato) 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": "N0449170E0074840",
"TitoloPopup": "Irraggiamento",
"InfoGeneriche": "Irraggiamento giornaliero da 01/06/2026 a 31/05/2027",
"headers": {
"data": "Data",
"oraInizio": "Ora Inizio",
"oraFine": "Ora Fine",
"indice": "Irraggiamento (GHI)"
},
"dettaglio": [
{ "data": "01/06/2026", "oraInizio": "00:00", "oraFine": "23:59", "indice": 8234, "highlight": 0 },
{ "data": "02/06/2026", "oraInizio": "00:00", "oraFine": "23:59", "indice": 8256, "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: Irraggiamento |
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 (Irraggiamento (GHI)) |
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;
- gli indici del mese precedente vengono caricati una volta al mese: i giorni del mese in corso non sono ancora disponibili;
- 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.
I valori sono giornalieri: l'indennizzo si confronta con la somma dei valori del periodo annuale di copertura, da calcolare lato partner (`7).
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 i due punti).
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. |