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
POSTregistra 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
numeroAdesionee 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
contraentee 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,numeroVoloquello usato per il monitoraggio: possono differire per conversione IATA/ICAO o voli in codeshare. Nella ricerca per soli aeroportinumeroVoloPdfènull: il certificato riporta alloranumeroVolo.- 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
aeroportoArrivoper 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
timestampPartenzaetimestampArrivo(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
maildell'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¶
- 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 nelle altre richieste.
10. Cronologia della pagina¶
| Versione | Data | Modifiche |
|---|---|---|
| 1.0.0 | 2026-10-06 | Prima pubblicazione |