Vai al contenuto

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 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 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).
  • T030 fa 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 esempio 2026-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_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.

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 è null e InfoGeneriche riporta 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

  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.