Vai al contenuto

Guida di integrazione — R04x Volo Protetto

Versione

1.0.0 — Riservato, esclusivamente per uso del partner.

1. Panoramica

Questa guida descrive come integrare il partner con REVO per i prodotti R04x, coperture parametriche sul volo emesse come adesioni a una polizza collettiva (polizza madre):

Codice Prodotto Garanzie (keyGaranzia)
R044 REVO Volo Protetto ritardoVoloPar e/o cancellazioneVoloPar
R042 REVO Flight Delay ritardoVoloPar
R043 REVO Flight Cancellation cancellazioneVoloPar

Le API sono identiche per i tre prodotti: cambiano solo il codice prodotto e le garanzie inviate. La polizza madre assegnata al partner è legata a un solo prodotto.

Nella struttura collettiva i soggetti sono:

  • il contraente della polizza collettiva (per esempio l'intermediario);
  • l'aderente (la persona che aderisce: agenzia di viaggio, azienda che assicura i dipendenti, persona fisica, genitore che assicura la famiglia);
  • gli assicurati: le persone che viaggeranno.

Flusso operativo

sequenceDiagram
    participant P as Partner
    participant R as REVO / OverX
    P->>R: POST /sicurezza/login
    R-->>P: access_token
    P->>R: POST …/mobility/flights-schedule (numeroVolo, dataPartenza)
    R-->>P: scheduled[] (tratte trovate)
    Note over P: l'utente sceglie la tratta da assicurare
    P->>R: POST …/blockchain/flightdelay/insurance (tratta scelta, premio, aderente)
    R-->>P: 201 numeroAdesione
    R--)P: e-mail all'aderente con certificato e condizioni
    opt annullamento
        P->>R: POST …/collettive/annullamento/adesioni
        R-->>P: 200 policy_number
    end
  • Ricerca volo: serve a ottenere il record della tratta da assicurare, che va inoltrato così com'è nell'emissione (§4).
  • Emissione: una singola chiamata POST registra l'adesione (§5). Non esiste una chiamata di quotazione verso REVO: il premio è calcolato dal motore tariffario del partner e inviato nel payload.
  • Elaborazione asincrona: la risposta conferma subito il numero di adesione; il certificato e le condizioni di polizza arrivano via e-mail all'aderente pochi secondi dopo, se l'invio è abilitato sulla polizza madre (configurazione a cura di REVO). Non esiste un servizio per scaricare il certificato.
  • Annullamento: disponibile fino al giorno di partenza del primo volo (§6).
  • Non disponibili: modifica (appendice) dell'adesione e recupero dell'adesione emessa. Conservare numeroAdesione e la richiesta inviata.

Cosa serve per iniziare, da richiedere a REVO:

  • username e password per il login;
  • il numero della polizza madre (polizzaMadre) e il codice prodotto;
  • l'accordo sul valore di contraente e sui dati dell'intermediario.

La specifica OpenAPI è disponibile nel file openapi.yaml e nella pagina Specifica OpenAPI; è importabile in Postman, Insomnia o Swagger UI.

2. Autenticazione

Tutte le chiamate, tranne il login, richiedono un Bearer Token nell'header Authorization:

Authorization: Bearer <token>

Il token si ottiene 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>" }

access_token è il JWT da inviare in Authorization: Bearer <access_token>. Il token ha durata limitata: quando una chiamata risponde 401 si ripete il login.

Scenario Stato HTTP Note
Header Authorization assente 403 Risposta senza corpo
Token non valido o scaduto 401 Risposta senza corpo: ripetere il login

3. 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 §2
POST /reverse-proxy/forward/api/v1/mobility/flights-schedule Cerca il volo da assicurare §4
POST /reverse-proxy/blockchain/flightdelay/insurance Emissione dell'adesione §5
POST /reverse-proxy/blockchain/collettive/annullamento/adesioni Annullamento dell'adesione §6

4. Ricerca del volo

POST /reverse-proxy/forward/api/v{vers}/mobility/flights-schedule (con vers = 1) restituisce le tratte programmate per un volo e una data.

Due combinazioni valide di input:

Combinazione Campi
Per numero volo numeroVolo + dataPartenza. aeroportoPartenza e aeroportoArrivo sono filtri facoltativi
Per aeroporti dataPartenza + entrambi aeroportoPartenza e aeroportoArrivo (senza numeroVolo)
Campo Descrizione
numeroVolo Numero volo riportato sul biglietto, in maiuscolo (es. AZ610, EZY5182): da 1 a 3 lettere seguite da 1–4 cifre. Il prefisso EJU è normalizzato in U2
dataPartenza Data locale di partenza, YYYY-MM-DD. Sempre obbligatoria
aeroportoPartenza, aeroportoArrivo Codice aeroporto che deve esistere nell'anagrafica aeroporti. Insieme a numeroVolo: IATA (3 lettere) o ICAO (4 lettere). Nella ricerca per soli aeroporti: solo ICAO (es. LIRF, KJFK); con codici IATA la chiamata risponde 500
{ "numeroVolo": "EZY5182", "dataPartenza": "2026-12-04" }

Ricerca per soli aeroporti (codici ICAO):

{ "dataPartenza": "2026-12-04", "aeroportoPartenza": "LSGG", "aeroportoArrivo": "EDDB" }

La risposta contiene l'array scheduled, con un elemento per ogni tratta trovata (codeshare esclusi). Esempio con i campi utili (ogni elemento contiene anche altri campi, tra cui vendor, da non modificare):

{
  "scheduled": [
    {
      "numeroVolo": "EZY5182",
      "numeroVoloPdf": "EJU5182",
      "numero_volo_pdf": "EJU5182",
      "timestampPartenza": "2026-12-04T07:40:00+01:00",
      "timestampArrivo": "2026-12-04T09:25:00+01:00",
      "aeroportoPartenza": "LSGG",
      "aeroportoArrivo": "EDDB",
      "aeroportoPartenzaNome": "Geneva Cointrin Int'l",
      "aeroportoPartenzaIata": "GVA",
      "aeroportoArrivoNome": "Berlin-Brandenburg",
      "aeroportoArrivoIata": "BER",
      "vendor": { "…": "…" }
    }
  ]
}

Come usare la risposta:

  • Il record scelto va inoltrato così com'è in datiTecnici.voliAssicurati (§5.4): non va letto né modificato.
  • numeroVoloPdf è il numero riportato sul certificato, numeroVolo quello usato per il monitoraggio: possono differire per conversione IATA/ICAO o voli in codeshare. Nella ricerca per soli aeroporti numeroVoloPdf è null: il certificato riporta allora numeroVolo.
  • Un numero volo può coprire più tratte nello stesso giorno senza cambiare numero (esempio: EK210). In questo caso l'API restituisce più record: mostrarli tutti e far scegliere all'utente quello con l'aeroporto di arrivo corretto, oppure inviare aeroportoArrivo per filtrare.
  • Se scheduled è vuoto, numero volo e/o data sono errati oppure il volo non è in programmazione: non può essere assicurato.
  • Per la visualizzazione usare timestampPartenza e timestampArrivo (orario locale con offset).
Stato Quando
200 Ricerca eseguita (anche con scheduled vuoto)
400 Dati mancanti: Data di partenza del volo mancante.; senza numeroVolo, Aeroporto di partenza mancante. / Aeroporto di arrivo mancante.. Corpo: {"detail": {"message": "…"}}
404 Codice aeroporto inesistente, oppure compagnia sconosciuta o non supportata. Stesso formato del 400
422 Campo malformato (per esempio numeroVolo in minuscolo o dataPartenza non in formato YYYY-MM-DD). Corpo: {"errors": "…"}
500 Errore interno, per esempio ricerca per soli aeroporti con codici IATA: usare i codici ICAO

5. Emissione dell'adesione

POST /reverse-proxy/blockchain/flightdelay/insurance — la stessa API per R042, R043 e R044.

5.1 Struttura della richiesta

Campo Obbligatorio Descrizione
polizzaMadre Sì Numero della polizza madre fornito da REVO (es. OX44444444). Deve essere valida alla data della chiamata
prodotto Sì R042, R043 o R044; deve essere il prodotto della polizza madre
contraente Consigliato Ragione sociale del contraente della polizza collettiva, come concordata con REVO
intermediario Sì Intermediario della polizza madre (§5.2)
aderentePF / aderentePG Sì, uno solo Aderente (§5.3)
datiTecnici Sì Dati del viaggio, come stringa JSON (§5.4)
premio Sì Premio e garanzie (§5.5)
adesione No Lasciare vuoto: il numero di adesione è generato da REVO

5.2 Intermediario

Campo Obbligatorio Note
denominazioneSociale Sì
partitaIVA Sì Deve coincidere con quella registrata da REVO sulla polizza madre, altrimenti errore E003
codiceFiscale, pec, telefono, fax No
mail, indirizzo No Se inviati (l'indirizzo solo se completo di tutti i campi), sostituiscono quelli registrati nei documenti generati per l'adesione

5.3 Aderente

Inviare aderentePF oppure aderentePG, mai entrambi (né nessuno).

Campo aderentePF (persona fisica) aderentePG (persona giuridica)
nome, cognome Obbligatori —
denominazioneSociale — Obbligatorio
codiceFiscale, partitaIVA codiceFiscale facoltativo Almeno uno dei due obbligatorio
mail Obbligatoria Obbligatoria
dataDiNascita, telefono, indirizzo Facoltativi telefono e indirizzo facoltativi
  • La mail dell'aderente è il destinatario del certificato e delle condizioni di polizza.
  • Una ditta individuale si invia come aderentePG.

5.4 datiTecnici

datiTecnici è un oggetto JSON serializzato in una stringa (non un oggetto annidato):

{
  "numeroAssicurati": 2,
  "voliAssicurati": [ { "…": "record scelto dalla ricerca volo, invariato" } ],
  "assicurati": [
    { "nome": "MARIO", "cognome": "ROSSI", "mail": "mario.rossi@example.com" },
    { "nome": "ANNA",  "cognome": "VERDI", "mail": "anna.verdi@example.com" }
  ],
  "codiceEmissionePartner": "PRT-157642678"
}
Campo Obbligatorio Descrizione
numeroAssicurati Sì Numero totale di persone assicurate
voliAssicurati Sì Voli scelti dall'utente (per esempio andata e ritorno), al massimo 6. Ogni elemento è il record della ricerca volo, invariato. Non vanno inviate tutte le tratte restituite dalla ricerca, ma solo quelle da assicurare
assicurati Consigliato Persone assicurate: nome e cognome obbligatori. Se tutte le e-mail sono valorizzate, REVO può inviare le comunicazioni di sinistro a ciascun assicurato; se manca anche una sola e-mail, le comunicazioni vanno all'e-mail dell'aderente. Evitare configurazioni miste
codiceEmissionePartner No Riferimento libero del partner (per esempio il codice prenotazione). Viene conservato con la richiesta; non è interpretato né restituito dalle API

Campi del record volo che REVO legge (tutti gli altri sono conservati e ignorati):

Campo Note
numeroVolo Obbligatorio. Identificativo usato per il monitoraggio
numero_volo_pdf Numero riportato sul certificato; se assente si usa numeroVolo
timestampPartenza Obbligatorio. Partenza locale con offset (ISO 8601)
timestampArrivo Obbligatorio. Arrivo locale con offset (ISO 8601)
aeroportoArrivo Obbligatorio. Insieme a numero volo e data identifica il volo monitorato
aeroportoArrivoNome, aeroportoArrivoIata Facoltativi, usati nelle comunicazioni

Indennizzo

L'importo dell'indennizzo non si invia: è definito da REVO sulla polizza madre. Un eventuale campo indennizzo in datiTecnici viene ignorato.

Per costruire la stringa basta serializzare l'oggetto, per esempio JSON.stringify(datiTecnici) (JavaScript) o json.dumps(dati_tecnici) (Python).

5.5 Premio e garanzie

Campo Descrizione
premio.idQuotazione Lasciare vuoto
premio.garanzie[] Garanzie acquistate; almeno una, coerente con il prodotto
premio.lordo Premio lordo totale (somma delle garanzie), maggiore di 0
premio.netto Premio netto totale = lordo − imposte
premio.imposte Imposte totali

Ogni elemento di garanzie:

Campo Obbligatorio Descrizione
keyGaranzia Sì ritardoVoloPar o cancellazioneVoloPar (distinzione tra maiuscole e minuscole)
lordo Sì Premio lordo della garanzia
netto, imposte Consigliati Premio netto e imposte della garanzia: sono registrati sulla polizza, quindi inviarli sempre
id, descrizione No id vuoto; descrizione è testo libero

Garanzie accettate per prodotto:

Prodotto Garanzie ammesse
R042 ritardoVoloPar
R043 cancellazioneVoloPar
R044 ritardoVoloPar e/o cancellazioneVoloPar

Una keyGaranzia non coerente con il prodotto fa rifiutare la richiesta. Gli importi sono quelli calcolati dal motore tariffario del partner: REVO li registra come ricevuti e non li ricalcola. Negli esempi di questa guida le imposte sono il 21,25% del netto (imposte = lordo / 1,2125 × 0,2125, arrotondate per eccesso al centesimo).

5.6 Risposta (201 Created)

{
  "numeroAdesione": "OX44444444-000000012",
  "emissione": 1796000000
}
Campo Descrizione
numeroAdesione Numero dell'adesione, nel formato <polizzaMadre>-<9 cifre>. Va conservato: serve per l'annullamento e va riportato nell'estratto conto mensile inviato all'intermediario, per riconciliare i premi
emissione Istante di emissione, Unix epoch in secondi

Ogni garanzia e ogni volo dell'adesione generano una copertura monitorata: un'adesione R044 con ritardo e cancellazione su due voli ne genera quattro.

Dopo la risposta REVO completa l'emissione in modo asincrono e, se l'invio è abilitato sulla polizza madre, invia all'aderente un'e-mail con certificato e condizioni di polizza.

5.7 Errori dell'emissione

In caso di errore la risposta ha stato 400 e corpo:

{ "message": "`polizzaMadre` is not valid", "code": "E003" }
code Significato Esempi di message
E001 Troppi voli maximum insured flights exceeded (oltre 6 voli)
E002 Richiesta non valida errore di validazione della subscriptionRequest: …; AderentePF o AderentePG non valorizzati; presenti sia AderentePF che AderentePG; indirizzo mail richiesto; invalid match betweenprodottoandkeyGaranzia; prodotto is not valid `; per R043,numeroVolo mancante per il volo #1/aeroportoArrivo mancante per il volo #1/nessun volo assicurato`
E003 Polizza madre, intermediario o prodotto non validi `polizzaMadre` is not valid; `intermediario.partitaIVA` is not valid; `prodotto / condizione` non valido
(assente) Dati illeggibili datiTecnici non è un JSON valido; timestampPartenza / timestampArrivo in un formato non riconosciuto

Non è emessa alcuna adesione se la richiesta viene rifiutata.

6. Annullamento

POST /reverse-proxy/blockchain/collettive/annullamento/adesioni

{
  "numeroPolizzaMadre": "OX44444444",
  "numeroAdesione": "OX44444444-000000012"
}
Campo Obbligatorio Descrizione
numeroPolizzaMadre Sì Polizza madre dell'adesione. numeroAdesione deve iniziare con questo valore
numeroAdesione Sì Numero restituito dall'emissione

Regole:

  • La chiamata deve essere fatta con le credenziali dell'intermediario intestatario della polizza madre; altre utenze sono rifiutate (E003).
  • Per R042, R043 e R044 l'annullamento è possibile fino al giorno di partenza del primo volo dell'adesione, compreso; dopo è rifiutato (E003). Per annullare oltre questo limite occorre aprire un ticket all'AM REVO tramite il portale dedicato.
  • La data di annullamento è il giorno della chiamata.
  • L'adesione viene disattivata e contrassegnata per il rimborso del premio.
  • Annullare un'adesione già annullata è rifiutato (E004).

Risposta (200):

{ "policy_number": "OX44444444-000000012" }

Errori (corpo {"errorMessage": "…", "errorCode": "…"}):

Stato errorCode Quando
404 E002 Richiesta non valida, numeroAdesione mancante, polizza madre o adesione non trovata
401 E003 L'adesione non appartiene alla polizza madre indicata; intermediario non autorizzato; annullamento dopo il giorno di partenza
400 E004 L'adesione non è attiva (già annullata)
400 E005, E006 Errore tecnico o adesione modificata da un'altra operazione contemporanea: riprovare

Un 401 senza corpo indica invece un token non valido o scaduto (§2).

7. Esempi di payload

7.1 R044 — Volo Protetto, aderente persona fisica

datiTecnici è la stringa JSON descritta al §5.4; qui è riportata decodificata, con il record volo abbreviato, solo per leggibilità.

{
  "polizzaMadre": "OX44444444",
  "adesione": "",
  "prodotto": "R044",
  "contraente": "Contraente Esempio S.r.l.",
  "datiTecnici": "<stringa JSON: vedi §5.4>",
  "aderentePF": {
    "nome": "MARIO",
    "cognome": "ROSSI",
    "codiceFiscale": "RSSMRA80A01F205X",
    "mail": "mario.rossi@example.com",
    "telefono": "+393331234567",
    "indirizzo": {
      "indirizzo": "Via Roma 1",
      "comune": "Milano",
      "cap": "20121",
      "provincia": "MI",
      "nazione": "Italia"
    }
  },
  "intermediario": {
    "denominazioneSociale": "Intermediario Esempio S.r.l.",
    "codiceFiscale": "01234567890",
    "partitaIVA": "01234567890",
    "mail": "intermediario@example.com"
  },
  "premio": {
    "idQuotazione": "",
    "garanzie": [
      { "id": "", "keyGaranzia": "ritardoVoloPar", "descrizione": "Ritardo Volo",
        "lordo": 12.13, "netto": 10.00, "imposte": 2.13 },
      { "id": "", "keyGaranzia": "cancellazioneVoloPar", "descrizione": "Cancellazione Volo",
        "lordo": 24.25, "netto": 20.00, "imposte": 4.25 }
    ],
    "lordo": 36.38,
    "netto": 30.00,
    "imposte": 6.38
  }
}

7.2 R043 — Flight Cancellation, aderente persona fisica

Cambiano prodotto, la polizza madre e la sola garanzia cancellazioneVoloPar:

{
  "polizzaMadre": "OX43333333",
  "adesione": "",
  "prodotto": "R043",
  "contraente": "Contraente Esempio S.r.l.",
  "datiTecnici": "<stringa JSON: vedi §5.4>",
  "aderentePF": { "nome": "MARIO", "cognome": "ROSSI", "mail": "mario.rossi@example.com" },
  "intermediario": {
    "denominazioneSociale": "Intermediario Esempio S.r.l.",
    "partitaIVA": "01234567890"
  },
  "premio": {
    "idQuotazione": "",
    "garanzie": [
      { "id": "", "keyGaranzia": "cancellazioneVoloPar", "descrizione": "Cancellazione Volo",
        "lordo": 11.75, "netto": 9.69, "imposte": 2.06 }
    ],
    "lordo": 11.75,
    "netto": 9.69,
    "imposte": 2.06
  }
}

Per R042 la struttura è identica, con prodotto: "R042" e la sola garanzia ritardoVoloPar. Altri esempi (aderente persona giuridica, ditta individuale) sono nella Specifica OpenAPI, nell'operazione di emissione.

8. Note tecniche

Formato data e ora

I timestamp dei voli sono ISO 8601 con offset (2026-12-04T07:40:00+01:00) e vanno inoltrati come restituiti dalla ricerca volo. dataPartenza della ricerca è YYYY-MM-DD.

Separatore decimale

Gli importi sono numeri JSON con il punto come separatore decimale (12.13), non stringhe.

Maiuscole e minuscole

keyGaranzia e i codici prodotto sono sensibili alle maiuscole.

Stringa datiTecnici

Il campo è una stringa: virgolette e caratteri speciali al suo interno vanno protetti dalla serializzazione JSON del client, non scritti a mano.

9. 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 nelle altre richieste.

10. Cronologia della pagina

Versione Data Modifiche
1.0.0 2026-10-06 Prima pubblicazione