Vai al contenuto

Guida di integrazione — A001 Travel

Versione

2.0.0 — Riservato, esclusivamente per uso del partner.

1. Panoramica

Questa guida descrive come integrare il partner con REVO per il prodotto A001 — Travel, una copertura viaggio composta da garanzie selezionabili (elenco completo al §8). La polizza collettiva (polizza master) assegnata al partner abilita un sottoinsieme di queste garanzie: per esempio la sola Rischio Volo (commercialmente "Cancellazione mezzo di trasporto") oppure un pacchetto di più garanzie.

  • Emissione: una singola chiamata POST registra l'adesione di un viaggio. Non esiste una chiamata di quotazione verso REVO: il premio è calcolato dal motore tariffario del partner e inviato nel payload.
  • Elaborazione asincrona: la risposta alla chiamata di emissione conferma la ricezione; l'emissione e l'incasso si completano pochi secondi dopo e il risultato si legge con la chiamata di recupero adesione (§10).
  • Operazioni disponibili: emissione, recupero dettaglio, storno (annullamento), gestione allegati, recupero dati volo. Non è disponibile alcuna modifica (endorsement) dell'adesione.
  • Rinnovo automatico: non supportato. Inviare tacitoRinnovo: false.
  • Vincoli commerciali: sono definiti nell'accordo commerciale con REVO e applicati dal motore tariffario del partner. L'API di emissione non li verifica: invia solo adesioni già commercialmente valide. Per la garanzia Rischio Volo sono:
    • durata della copertura da 1 a 30 giorni;
    • nessuna retrodatazione (dataEffetto non precedente alla data odierna);
    • postdatazione fino a 30 giorni;
    • polizza stipulata entro 2 giorni dalla data di prenotazione oppure, se successiva, almeno 30 giorni di calendario prima della partenza.

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

Flusso operativo

sequenceDiagram
    participant Partner
    participant Overx as Overx API

    Partner->>Overx: POST /collettive/adesioni/ (Bearer token)
    Overx-->>Partner: 200 OK — numeroAdesione, id, stato EMESSA
    Overx->>Overx: Emissione e incasso (alcuni secondi)
    Partner->>Overx: GET /collettive/adesioni/by-num-polizza/by-num-adesione
    Overx-->>Partner: 200 OK — stato INCASSATA (oppure EMESSA / ERRORE_*)

2. Autenticazione

Ogni richiesta deve includere un Bearer Token nell'header HTTP Authorization. È lo stesso meccanismo applicativo già usato nell'ecosistema OverX: non è richiesto alcun passaggio di autenticazione specifico per questo prodotto.

Authorization: Bearer <token>

Ottenimento del token

Il token si ottiene chiamando l'endpoint di login con le credenziali fornite dal team Overx:

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",
  "refresh_token": "<jwt>",
  "id_token": "<jwt>",
  "expires_in": 2400,
  "refresh_expires_in": 28799,
  "scope": "openid email family_name",
  "session_state": "<uuid>",
  "not-before-policy": 0
}
Campo Descrizione
access_token JWT da usare nell'header Authorization: Bearer <access_token> di ogni altra chiamata
token_type Sempre Bearer
expires_in Validità di access_token in secondi (2400 = 40 minuti)
refresh_token, refresh_expires_in, id_token, scope, session_state, not-before-policy Campi dell'identity provider, non necessari per usare queste API

Alla scadenza del token si ripete il login con username e password.

Comportamento in caso di errore

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

Operazioni disponibili, in ordine di utilizzo tipico:

Metodo Percorso Descrizione Sezione
POST /sicurezza/login Ottiene il Bearer Token §2
POST /reverse-proxy/forward/api/v1/mobility/flights-schedule Recupera i dati di un volo da inserire nell'adesione §7
POST /collettive/adesioni/ Emette una nuova adesione §4
GET /collettive/adesioni/by-num-polizza/by-num-adesione Recupera lo stato e il dettaglio di un'adesione §10
POST /collettive/movimenti/{numeroPolizza}/create-by-adesione Storna (annulla) una o più adesioni §11
POST /collettive/allegato/upload Carica uno o più allegati §12
GET /collettive/allegato/list/{idAdesione} Elenca gli allegati di un'adesione §12
POST /collettive/allegato/download Scarica un allegato §12
DELETE /collettive/allegato/delete/{idAllegato} Elimina un allegato §12

Header obbligatori: Authorization: Bearer <token> e, per le richieste con corpo JSON, Content-Type: application/json.

4. Emissione adesione

POST /collettive/adesioni/ registra una nuova adesione collegata alla polizza master indicata in numeroPolizza.

4.1 Struttura della richiesta

AdesioneRequest
├── Dati generali (numeroPolizza, numeroAdesioneEsterno, dataEffetto, dataScadenza, tacitoRinnovo, source, tipoSoggetto)
├── personaFisica | personaGiuridica | dittaIndividuale   (una sola, coerente con tipoSoggetto — §5)
├── beneAssicurato                                         (viaggio assicurato — §6)
│   └── variabiliTecniche[]                                (dati viaggio, assicurati, voli)
└── garanzie[]                                             (una o più garanzie attive sulla polizza — §8)
    ├── variabiliTecniche[]
    └── premioGaranzia

4.2 Dati generali

Campo Tipo Obbligatorio Note
numeroPolizza string Sì Numero della polizza master, fornito dal team Overx. Se non esiste la risposta è 500
dataEffetto string (datetime ISO 8601) Sì Inizio copertura. Non può precedere la data di effetto della polizza master (400)
dataScadenza string (datetime ISO 8601) Sì Fine copertura. Non può precedere dataEffetto (400)
tipoSoggetto enum Sì PERSONA_FISICA | PERSONA_GIURIDICA | DITTA_INDIVIDUALE
numeroAdesioneEsterno string Consigliato Identificativo dell'adesione lato partner. Deve essere unico per polizza: un valore già usato dà 409. Può essere omesso o stringa vuota
tacitoRinnovo boolean No Sempre false per questo prodotto
source string No Canale di origine; se omesso REVO usa API
dataCreazione, stato — No Non inviare: li assegna REVO (qualsiasi valore inviato viene ignorato)
keyPolizza, codiceProdotto — No Non inviare: REVO li ricava da numeroPolizza

4.3 Campi calcolati da REVO (facoltativi)

REVO completa automaticamente questi campi a partire dalla polizza e dalla keyGaranzia; non è necessario inviarli:

Campo Valore assegnato da REVO
keyPolizza Chiave della polizza master indicata in numeroPolizza
codiceProdotto A001
beneAssicurato.identificativo Identificativo del bene assicurato "viaggio" del prodotto (a partire da tipoBene: viaggioAssicurato)
garanzie[].idGarOverx, nomeGaranzia, codAnagGar, ramoBilancio Valori della garanzia nel catalogo (§8.2), individuata da keyGaranzia
Tutti i campi id, idBeneAssicurato, idGaranzia, premioGaranzia.id Identificativi interni
Data di nascita del contraente Ricavata dal codice fiscale

4.4 Risposta (200 OK)

La risposta ripropone il payload inviato, completato con i campi calcolati da REVO e con:

Campo Descrizione
numeroAdesione Numero dell'adesione assegnato da REVO, nel formato <numeroPolizza>-<progressivo> (es. OXC0208-000022). Va usato per recupero e storno
id UUID interno dell'adesione; serve per la gestione degli allegati (§12)
stato EMESSA: ricezione confermata. Non è lo stato finale: vedere §4.5
{
  "id": "550dc694-cbb7-45e0-a610-3389aa213eee",
  "numeroPolizza": "OXC0208",
  "numeroAdesione": "OXC0208-000022",
  "numeroAdesioneEsterno": "ADH-2026-00123",
  "codiceProdotto": "A001",
  "stato": "EMESSA",
  "garanzie": [
    {
      "keyGaranzia": "rischioVolo",
      "idGarOverx": "f61d8ae5-c7b5-4036-80fa-23ccbeb0c08a",
      "nomeGaranzia": "RISCHIO VOLO e RISCHIO ZERO",
      "codAnagGar": "16032",
      "ramoBilancio": "0016"
    }
  ]
}

Controllare le garanzie nella risposta

Se per una garanzia idGarOverx, nomeGaranzia e codAnagGar risultano null, la keyGaranzia inviata non corrisponde a una garanzia attiva sulla polizza: l'adesione non viene registrata. Correggere la keyGaranzia (§8.2) e reinviare.

4.5 Stato dell'adesione dopo l'emissione

L'emissione e l'incasso si completano in genere entro 15 secondi. Durante questo intervallo il recupero dell'adesione (§10) può rispondere 404. Leggere lo stato finale con la chiamata di recupero:

stato Significato
EMESSA Adesione emessa. È lo stato finale se la polizza non prevede l'incasso alla firma
INCASSATA Adesione emessa e premio incassato: è lo stato finale atteso per le polizze con incasso alla firma
ANNULLO_CON_RIMBORSO, ANNULLO_SENZA_EFFETTO Adesione stornata (§11)
ERRORE_JMIL, ERRORE_EMISSIONE, ERRORE_EMISSIONE_BLOCKCHAIN L'emissione non si è completata: controllare i dati inviati (contraente §5, bene assicurato §6, garanzie §8)

La piattaforma prevede anche gli stati DRAFT, DA_APPROVARE e RIFIUTATA (approvazione manuale): per A001 non sono attualmente attivati.

Se dopo 60 secondi il recupero risponde ancora 404, l'adesione non è stata registrata: controllare i campi obbligatori e reinviare (lo stesso numeroAdesioneEsterno può essere riutilizzato).

4.6 Errori dell'emissione

Codice Causa Corpo
400 Dati non validi (vedere §13) { "timestamp", "status", "error": "Bad Request", "message", "path" }
401 Token non valido o scaduto —
403 Header Authorization assente —
409 numeroAdesioneEsterno già utilizzato sulla stessa polizza { "error": "ADESIONE_DUPLICATA", "message", "status": 409, ... }
500 Errore interno (anche numeroPolizza inesistente) { "timestamp", "status", "error", "message", "path" }

5. Contraente

Nel payload deve essere presente una e una sola tra personaFisica, personaGiuridica e dittaIndividuale, coerente con tipoSoggetto.

Indirizzo e codice fiscale: requisiti per il completamento dell'emissione

  • L'indirizzo del contraente deve contenere almeno il CAP (5 cifre) e preferibilmente comune e sigla di provincia. Formato raccomandato: VIA EDEN 2 - 23889 SANTA MARIA HOE (LC). Senza questi dati l'emissione si ferma in stato ERRORE_JMIL.
  • Il codice fiscale deve essere formalmente valido e coerente con nome e cognome: in caso contrario l'emissione si ferma in ERRORE_JMIL (es. "Codice Fiscale non valido: Cognome errato").

personaFisica

Campo Tipo Obbligatorio Note
codiceFiscale string Sì 16 caratteri, maiuscolo, coerente con nome e cognome
nome string Sì Massimo 50 caratteri
cognome string Sì Massimo 50 caratteri
indirizzo string Sì Vedere sopra
nazione string No ISO 3166-1 alpha-3 (es. ITA, ESP)
numeroTelefono string No Solo cifre, senza prefisso internazionale
email string No Formato user@domain.tld
pec string No Può essere stringa vuota

personaGiuridica

Campo Tipo Obbligatorio Note
partitaIva string Sì 11 cifre
ragioneSociale string Sì Denominazione legale
indirizzo string Sì Vedere sopra
nazione string No ISO 3166-1 alpha-3
formaSocietaria string No Es. SPA
codiceAteco string No Es. 80.10
numeroTelefono, email, pec string No —

dittaIndividuale

Campo Tipo Obbligatorio Note
codiceFiscale string Sì Coerente con nome e cognome
nome, cognome string Sì —
indirizzo string Sì Vedere sopra
partitaIva string No Se presente, 11 cifre (il prefisso IT viene ignorato), altrimenti 400
nazione, numeroTelefono, email, pec string No —

6. Bene assicurato

Il bene assicurato dell'adesione è sempre il viaggio: nel payload tipoBene vale sempre viaggioAssicurato.

Campo Tipo Obbligatorio Note
tipoBene string Sì Valore fisso: viaggioAssicurato
variabiliTecniche array Sì Almeno una variabile. Elenco in §6.1
identificativo string No Calcolato da REVO (§4.3)

tipoBene e variabili tecniche

Senza tipoBene valido o senza almeno una variabile tecnica del bene l'adesione non viene registrata.

6.1 Variabili tecniche del viaggio

Inviare sempre tutte le variabili seguenti (le numeriche a 0 e gli array a [] quando non applicabili):

keyVartec Tipo valueVartec Descrizione
prenotazione datetime ISO 8601 Data e ora di prenotazione del viaggio
destinazioneArea enum italia | europa | mondo | usaCanada
destinazionePaese string Paese o città di destinazione (per italia può contenere la città)
dataPartenza datetime ISO 8601 Data di partenza
dataRientro datetime ISO 8601 Data di rientro
dataGridDatiAssicurato array di oggetti Elenco degli assicurati (§6.2)
numeroAssicurati number Numero degli assicurati, pari alla lunghezza di dataGridDatiAssicurato
dataGridVoloAssicurato array di oggetti Voli assicurati (§7); [] se non ci sono voli
numeroVoloAssTot number Numero totale dei voli assicurati; 0 se non ci sono voli
indennizzoVolo number Importo dell'indennizzo volo in euro; 0 se non applicabile

Se è presente almeno un volo, devono essere presenti anche numeroAssicurati, dataGridDatiAssicurato e indennizzoVolo: in loro assenza l'emissione si ferma in ERRORE_EMISSIONE_BLOCKCHAIN.

6.2 Elemento di dataGridDatiAssicurato

Campo Tipo Obbligatorio Note
cognomeAssicurato string Sì —
nomeAssicurato string Sì —
fasciaEta enum Sì bassa (0-17) | media (18-74) | alta (75-89)
email string No —

7. Dati volo

Per le adesioni con voli assicurati, dataGridVoloAssicurato contiene un oggetto per ogni volo, con i campi indicati di seguito, ricavati dalla risposta dell'API di recupero dati volo (§7.1).

Campo Tipo Descrizione
numeroVolo string Numero volo operativo (es. WMT6313)
numeroVoloPdf string Numero volo da stampare sul contratto
aereoportoPartenza string Codice ICAO dell'aeroporto di partenza (es. LIMC)
fusorarioPartenza string Fuso orario IANA (es. Europe/Rome)
dataPartenza datetime ISO 8601 Partenza in ora locale
dataPartenzaUtc datetime ISO 8601 Partenza in UTC
aereoportoArrivo string Codice ICAO dell'aeroporto di arrivo (es. LEMD)
fusorarioArrivo string Fuso orario IANA dell'aeroporto di arrivo
dataArrivo datetime ISO 8601 Arrivo in ora locale
dataArrivoUtc datetime ISO 8601 Arrivo in UTC

Esempio di variabili del bene per un adesione con un volo:

{ "keyVartec": "dataGridVoloAssicurato", "valueVartec": [
  {
    "numeroVolo": "WMT6313", "numeroVoloPdf": "W46313",
    "aereoportoPartenza": "LIMC", "fusorarioPartenza": "Europe/Rome",
    "dataPartenza": "2026-10-30T10:05:00+02:00", "dataPartenzaUtc": "2026-10-30T08:05:00+00:00",
    "aereoportoArrivo": "LEMD", "fusorarioArrivo": "Europe/Rome",
    "dataArrivo": "2026-10-30T12:35:00+02:00", "dataArrivoUtc": "2026-10-30T10:35:00+00:00"
  }
] },
{ "keyVartec": "numeroVoloAssTot", "valueVartec": 1 },
{ "keyVartec": "indennizzoVolo", "valueVartec": 150 }

Non inoltrare la risposta dell'API così com'è

L'oggetto contenuto in dataGridVoloAssicurato deve avere esattamente i nomi di campo della tabella sopra. La risposta dell'API di recupero dati volo usa nomi diversi (§7.1): se viene inserita senza mappatura, l'emissione si ferma in ERRORE_EMISSIONE_BLOCKCHAIN.

7.1 API di recupero dati volo (flight schedule)

POST /reverse-proxy/forward/api/v1/mobility/flights-schedule restituisce la schedulazione di un volo a partire dal numero volo e dalla data di partenza.

Campo della richiesta Descrizione
dataPartenza Data locale di partenza (YYYY-MM-DD). Sempre obbligatoria
numeroVolo Numero volo riportato sul biglietto. Se presente, ha priorità e gli aeroporti non vanno inviati
aeroportoPartenza, aeroportoArrivo Codici aeroporto ICAO a 4 lettere (es. LIRF, KJFK; i codici IATA a 3 lettere non sono accettati). In alternativa a numeroVolo: almeno uno dei due; la ricerca per soli aeroporti restituisce tutti i voli della giornata tra i due scali. aeroportoArrivo è obbligatorio per i voli multi-tratta
{ "numeroVolo": "EJU5182", "dataPartenza": "2025-06-04" }

La risposta contiene l'array scheduled, con un elemento per ogni tratta trovata. Per i voli a più tratte lo stesso numeroVolo può coprire più tratte nella stessa giornata: indicare anche aeroportoPartenza e aeroportoArrivo per selezionare la tratta assicurata.

Esempio di risposta (campi utili; ogni elemento contiene anche campi aggiuntivi del fornitore, da non inviare):

{
  "scheduled": [
    {
      "numeroVolo": "ITY610",
      "numeroVoloPdf": "AZ610",
      "aeroportoPartenza": "LIRF",
      "aeroportoPartenzaIata": "FCO",
      "timezonePartenza": "Europe/Rome",
      "timestampPartenza": "2026-10-20T15:10:00+02:00",
      "timestampPartenzaUtc": "2026-10-20T13:10:00Z",
      "aeroportoArrivo": "KJFK",
      "aeroportoArrivoIata": "JFK",
      "timezoneArrivo": "America/New_York",
      "timestampArrivo": "2026-10-20T18:55:00-04:00",
      "timestampArrivoUtc": "2026-10-20T22:55:00Z"
    }
  ]
}

Mappatura verso dataGridVoloAssicurato — costruire l'oggetto volo a partire dall'elemento di scheduled:

Campo di dataGridVoloAssicurato Campo della risposta
numeroVolo numeroVolo
numeroVoloPdf numeroVoloPdf
aereoportoPartenza aeroportoPartenza
fusorarioPartenza timezonePartenza
dataPartenza timestampPartenza
dataPartenzaUtc timestampPartenzaUtc
aereoportoArrivo aeroportoArrivo
fusorarioArrivo timezoneArrivo
dataArrivo timestampArrivo
dataArrivoUtc timestampArrivoUtc

Attenzione all'ortografia: i campi di dataGridVoloAssicurato si scrivono aereoporto…, quelli della risposta aeroporto…. Nelle ricerche per soli aeroporti numeroVoloPdf può essere null: in tal caso usare il numero volo riportato sul biglietto.

Oggetto risultante per l'esempio sopra:

{
  "numeroVolo": "ITY610", "numeroVoloPdf": "AZ610",
  "aereoportoPartenza": "LIRF", "fusorarioPartenza": "Europe/Rome",
  "dataPartenza": "2026-10-20T15:10:00+02:00", "dataPartenzaUtc": "2026-10-20T13:10:00Z",
  "aereoportoArrivo": "KJFK", "fusorarioArrivo": "America/New_York",
  "dataArrivo": "2026-10-20T18:55:00-04:00", "dataArrivoUtc": "2026-10-20T22:55:00Z"
}
Codice Descrizione
200 Schedulazione restituita
400 dataPartenza mancante ({ "detail": { "message": "Data di partenza del volo mancante." } })
404 Compagnia aerea sconosciuta o non supportata ({ "detail": { "message": "Compagnia sconosciuta o non supportata: 'XX9' nel numero volo 'XX9999'" } })
500 Richiesta non elaborabile, per esempio data di partenza nel passato o codici aeroporto non ICAO. Corpo non strutturato

8. Garanzie

8.1 Come inserire le garanzie

  • Inviare in garanzie[] solo le garanzie attive sulla polizza assegnata al partner. Le garanzie del catalogo non attive sulla polizza non vengono riconosciute (§4.4).
  • Per un pacchetto parziale è sufficiente omettere le garanzie non di interesse: le altre vengono disabilitate da REVO.
  • keyGaranzia deve essere scritta esattamente come nel catalogo (§8.2), rispettando maiuscole e minuscole.
  • Per ogni adesione si possono inviare al massimo 15 garanzie.
  • Per ogni garanzia: keyGaranzia e premioGaranzia sono obbligatori; variabiliTecniche è un array (può essere vuoto) con i valori contrattuali della garanzia (§8.3). Gli altri campi (idGarOverx, nomeGaranzia, codAnagGar, ramoBilancio) sono calcolati da REVO.

8.2 Catalogo delle garanzie di A001

keyGaranzia Nome Descrizione idGarOverx tassePerc Variabili tecniche (keyVartec)
speseMediche SPESE MEDICHE IN VIAGGIO Spese mediche in viaggio 5f09a062-e355-48cb-8232-c6fc7dd88973 2.5 massimaleItalia, massimaleEuropa, massimaleMondo, limiteGiorni
ritardoVoloPar RITARDO VOLO (GARANZIA PARAMETRICA) Ritardo volo 15eb6e48-b179-4c72-9f93-547bc4d6e918 21.25 franchigia, massimalePersona
perditaBagaglio BAGAGLIO Furto o mancata riconsegna del bagaglio 13b9261e-7e4c-4c19-a704-b2cdba017247 12.5 massimale, massimalePersona
beniNecessari BAGAGLIO Acquisti di prima necessità e074732a-43c2-4f7a-b6fe-8790f6a6c768 12.5 massimalePersona, limiteNoleggio
rifacimDoc RIFACIMENTO DOCUMENTI Rifacimento documenti c262dd3e-30f8-471c-9598-3d5f0d52b41d 21.25 massimalePersona
assistenzaViag ASSISTENZA IN VIAGGIO Assistenza in viaggio 5c15e5f1-89ce-417b-b4cf-d13aa8399c9e 10 nessuna ([])
rct RESPONSABILITA' CIVILE VERSO TERZI Responsabilità civile verso terzi 6ccf86e2-7cd6-4a9f-8e0e-6a4f3db97dee 22.25 scoperto, minimoScoperto, massimalePersona
annullViaggio ANNULLAMENTO E INTERRUZIONE DEL VIAGGIO Annullamento del viaggio 89914481-337f-4142-a896-e8e6e3996462 21.25 scoperto, massimale, massimalePersona
interruzViaggio ANNULLAMENTO E INTERRUZIONE DEL VIAGGIO Interruzione del viaggio 7743b67e-55fd-4fdc-877d-aa90eb5313d7 21.25 massimale, massimalePersona
infMorteExtra INDENNIZZO PER MORTE EXTRA PROFESSIONALE Infortunio morte extra professionale f9f45322-b8eb-4e56-9b47-75feaca23f18 2.5 massimale
InfInvaPerm INDENNIZZO INVALIDITA' PERMANENTE Infortunio invalidità permanente extra professionale d460bfd5-b82f-4f57-b783-6d6a2822b195 2.5 massimale, franchigia
tutelaLegale TUTELA LEGALE Tutela legale 7cae198a-ffc3-4527-ae59-6cf9ae9020bc 21.25 massimale
assistenzaStr ASSISTENZA STRADALE Assistenza stradale 9c2a512b-93b1-4e6c-bb4a-16bd21cf155f 12.5 massimale
ritardoPart RITARDO PARTENZA Ritardo partenza 35faacb1-4bf5-40ed-9158-84afc9a5c4d7 21.25 massimale
rischioZero RISCHIO VOLO e RISCHIO ZERO Rischio zero 61305224-ae97-4004-9f2b-fb6b91ec5fe5 21.25 massimale
rischioVolo RISCHIO VOLO e RISCHIO ZERO Rischio volo f61d8ae5-c7b5-4036-80fa-23ccbeb0c08a 21.25 massimale, massimalePersona

Le chiavi keyGaranzia distinguono maiuscole e minuscole (es. InfInvaPerm). idGarOverx è indicato per riferimento: non va inviato.

8.3 Variabili tecniche delle garanzie

Ogni variabile è una coppia keyVartec / valueVartec con valueVartec numerico, usando i valori contrattuali concordati con REVO:

keyVartec Significato Garanzie
massimale Massimale complessivo (euro) perditaBagaglio, annullViaggio, interruzViaggio, infMorteExtra, InfInvaPerm, tutelaLegale, assistenzaStr, ritardoPart, rischioZero, rischioVolo
massimalePersona Massimale per persona (euro) ritardoVoloPar, perditaBagaglio, beniNecessari, rifacimDoc, rct, annullViaggio, interruzViaggio, rischioVolo
massimaleItalia, massimaleEuropa, massimaleMondo Massimale per area di destinazione (euro) speseMediche
limiteGiorni Numero massimo di giorni coperti speseMediche
franchigia Franchigia ritardoVoloPar, InfInvaPerm
scoperto Scoperto in percentuale rct, annullViaggio
minimoScoperto Minimo di scoperto (euro) rct
limiteNoleggio Limite per il noleggio (euro) beniNecessari

8.4 Premio della garanzia (premioGaranzia)

Campo Tipo Obbligatorio Descrizione
impAnnuo number Sì Premio netto
tassePerc number Sì Percentuale di imposta (valori di riferimento al §8.2)
lordoAnnuo number Sì Premio lordo = impAnnuo + impAnnuo × tassePerc / 100
valuta string Sì Codice ISO 4217 (EUR)
impAnnuoEur, lordoAnnuoEur number No Importi in euro, uguali a impAnnuo e lordoAnnuo se la valuta è EUR
  • Il premio è per adesione e per garanzia, così come calcolato dal motore tariffario del partner: REVO non lo moltiplica per il numero di assicurati.
  • lordoAnnuo deve essere coerente con impAnnuo e tassePerc (tolleranza 0.01, con la quota di imposta arrotondata a due decimali), altrimenti 400.
  • Senza tassePerc e lordoAnnuo l'incasso non si completa e l'adesione resta in stato EMESSA.

8.5 Rischio Volo — livelli BASE e TOP

Per la garanzia rischioVolo il partner invia i valori numerici del livello acquistato dal cliente (non esiste un campo di selezione del livello):

Attributo BASE TOP
massimale 40000 (Italia / Europa / Mondo) 40000 (Italia / Europa / Mondo)
massimalePersona Italia 500 / Europa 500 / Mondo 1000 2500 (tutte le aree)
lordoAnnuo 13.00 18.00
tassePerc 21.25 21.25
impAnnuo (derivato) 10.72 14.84

Rischio Volo è la garanzia base del prodotto "Cancellazione mezzo di trasporto". Codici della garanzia: codAnagGar 16032, ramoBilancio 0016.

9. Esempi di payload

9.1 Adesione con la sola garanzia Rischio Volo (livello BASE)

{
  "numeroPolizza": "OXC0XXX",
  "numeroAdesioneEsterno": "ADH-2026-00123",
  "dataEffetto": "2026-10-10T00:00:00.000Z",
  "dataScadenza": "2026-10-16T00:00:00.000Z",
  "tacitoRinnovo": false,
  "tipoSoggetto": "PERSONA_FISICA",
  "personaFisica": {
    "codiceFiscale": "RSSMRA85M01H501Q",
    "nome": "Mario",
    "cognome": "Rossi",
    "nazione": "ITA",
    "indirizzo": "VIA ROMA 10 - 00100 ROMA (RM)",
    "numeroTelefono": "3331234567",
    "email": "mario.rossi@example.com",
    "pec": ""
  },
  "beneAssicurato": {
    "tipoBene": "viaggioAssicurato",
    "variabiliTecniche": [
      { "keyVartec": "prenotazione", "valueVartec": "2026-10-05T10:00:00+02:00" },
      { "keyVartec": "destinazioneArea", "valueVartec": "italia" },
      { "keyVartec": "destinazionePaese", "valueVartec": "Italia" },
      { "keyVartec": "dataPartenza", "valueVartec": "2026-10-10T12:00:00+02:00" },
      { "keyVartec": "dataRientro", "valueVartec": "2026-10-16T12:00:00+02:00" },
      { "keyVartec": "dataGridDatiAssicurato", "valueVartec": [
        { "cognomeAssicurato": "Rossi", "nomeAssicurato": "Mario", "fasciaEta": "media", "email": "mario.rossi@example.com" }
      ] },
      { "keyVartec": "numeroAssicurati", "valueVartec": 1 },
      { "keyVartec": "dataGridVoloAssicurato", "valueVartec": [] },
      { "keyVartec": "numeroVoloAssTot", "valueVartec": 0 },
      { "keyVartec": "indennizzoVolo", "valueVartec": 0 }
    ]
  },
  "garanzie": [
    {
      "keyGaranzia": "rischioVolo",
      "variabiliTecniche": [
        { "keyVartec": "massimale", "valueVartec": 40000 },
        { "keyVartec": "massimalePersona", "valueVartec": 500 }
      ],
      "premioGaranzia": {
        "impAnnuo": 10.72,
        "tassePerc": 21.25,
        "lordoAnnuo": 13.00,
        "valuta": "EUR",
        "impAnnuoEur": 10.72,
        "lordoAnnuoEur": 13.00
      }
    }
  ]
}

9.2 Adesione con un pacchetto di più garanzie

Esempio con le nove garanzie del pacchetto "viaggio" (polizza che le abilita tutte). Per un pacchetto parziale si omettono le garanzie non di interesse.

{
  "numeroPolizza": "OXC0XXX",
  "numeroAdesioneEsterno": "ADH-2026-00124",
  "dataEffetto": "2026-10-23T00:00:00.000Z",
  "dataScadenza": "2026-10-26T00:00:00.000Z",
  "tacitoRinnovo": false,
  "tipoSoggetto": "PERSONA_FISICA",
  "personaFisica": {
    "codiceFiscale": "ZPPCHR91A52H224D",
    "nome": "Chiara",
    "cognome": "Zappia",
    "nazione": "ITA",
    "indirizzo": "Via Monte Rosa, 91, 20149 Milano MI, Italia",
    "numeroTelefono": null,
    "email": "chiara.zappia@example.com",
    "pec": ""
  },
  "beneAssicurato": {
    "tipoBene": "viaggioAssicurato",
    "variabiliTecniche": [
      { "keyVartec": "prenotazione", "valueVartec": "2026-10-15T00:00:00+01:00" },
      { "keyVartec": "destinazioneArea", "valueVartec": "italia" },
      { "keyVartec": "dataPartenza", "valueVartec": "2026-10-20T00:00:00+01:00" },
      { "keyVartec": "destinazionePaese", "valueVartec": "Palermo" },
      { "keyVartec": "dataRientro", "valueVartec": "2026-10-24T23:59:59+01:00" },
      { "keyVartec": "dataGridDatiAssicurato", "valueVartec": [
        { "cognomeAssicurato": "Zappia", "nomeAssicurato": "Chiara", "fasciaEta": "media", "email": "chiara.zappia@example.com" }
      ] },
      { "keyVartec": "numeroAssicurati", "valueVartec": 1 },
      { "keyVartec": "dataGridVoloAssicurato", "valueVartec": [] },
      { "keyVartec": "numeroVoloAssTot", "valueVartec": 0 },
      { "keyVartec": "indennizzoVolo", "valueVartec": 0 }
    ]
  },
  "garanzie": [
    { "keyGaranzia": "assistenzaViag", "variabiliTecniche": [],
      "premioGaranzia": { "impAnnuo": 4.6, "tassePerc": 10.0, "lordoAnnuo": 5.06, "valuta": "EUR", "impAnnuoEur": 4.6, "lordoAnnuoEur": 5.06 } },
    { "keyGaranzia": "speseMediche",
      "variabiliTecniche": [
        { "keyVartec": "massimaleItalia", "valueVartec": 3000 },
        { "keyVartec": "massimaleEuropa", "valueVartec": 1000000 },
        { "keyVartec": "massimaleMondo", "valueVartec": 4000000 },
        { "keyVartec": "limiteGiorni", "valueVartec": 100 } ],
      "premioGaranzia": { "impAnnuo": 7.4, "tassePerc": 2.5, "lordoAnnuo": 7.59, "valuta": "EUR", "impAnnuoEur": 7.4, "lordoAnnuoEur": 7.59 } },
    { "keyGaranzia": "ritardoVoloPar",
      "variabiliTecniche": [
        { "keyVartec": "franchigia", "valueVartec": 0 },
        { "keyVartec": "massimalePersona", "valueVartec": 300 } ],
      "premioGaranzia": { "impAnnuo": 4.03, "tassePerc": 21.25, "lordoAnnuo": 4.89, "valuta": "EUR", "impAnnuoEur": 4.03, "lordoAnnuoEur": 4.89 } },
    { "keyGaranzia": "perditaBagaglio",
      "variabiliTecniche": [
        { "keyVartec": "massimale", "valueVartec": 5000 },
        { "keyVartec": "massimalePersona", "valueVartec": 2000 } ],
      "premioGaranzia": { "impAnnuo": 1.305, "tassePerc": 12.5, "lordoAnnuo": 1.47, "valuta": "EUR", "impAnnuoEur": 1.305, "lordoAnnuoEur": 1.47 } },
    { "keyGaranzia": "beniNecessari",
      "variabiliTecniche": [
        { "keyVartec": "massimalePersona", "valueVartec": 200 },
        { "keyVartec": "limiteNoleggio", "valueVartec": 100 } ],
      "premioGaranzia": { "impAnnuo": 1.305, "tassePerc": 12.5, "lordoAnnuo": 1.47, "valuta": "EUR", "impAnnuoEur": 1.305, "lordoAnnuoEur": 1.47 } },
    { "keyGaranzia": "rct",
      "variabiliTecniche": [
        { "keyVartec": "scoperto", "valueVartec": 20 },
        { "keyVartec": "minimoScoperto", "valueVartec": 200 },
        { "keyVartec": "massimalePersona", "valueVartec": 50000 } ],
      "premioGaranzia": { "impAnnuo": 0.73, "tassePerc": 22.25, "lordoAnnuo": 0.9, "valuta": "EUR", "impAnnuoEur": 0.73, "lordoAnnuoEur": 0.9 } },
    { "keyGaranzia": "rifacimDoc",
      "variabiliTecniche": [ { "keyVartec": "massimalePersona", "valueVartec": 50 } ],
      "premioGaranzia": { "impAnnuo": 0.83, "tassePerc": 21.25, "lordoAnnuo": 1.01, "valuta": "EUR", "impAnnuoEur": 0.83, "lordoAnnuoEur": 1.01 } },
    { "keyGaranzia": "annullViaggio",
      "variabiliTecniche": [
        { "keyVartec": "scoperto", "valueVartec": 20 },
        { "keyVartec": "massimale", "valueVartec": 12000 },
        { "keyVartec": "massimalePersona", "valueVartec": 3000 } ],
      "premioGaranzia": { "impAnnuo": 28.28, "tassePerc": 21.25, "lordoAnnuo": 34.29, "valuta": "EUR", "impAnnuoEur": 28.28, "lordoAnnuoEur": 34.29 } },
    { "keyGaranzia": "interruzViaggio",
      "variabiliTecniche": [
        { "keyVartec": "massimale", "valueVartec": 12000 },
        { "keyVartec": "massimalePersona", "valueVartec": 3000 } ],
      "premioGaranzia": { "impAnnuo": 12.12, "tassePerc": 21.25, "lordoAnnuo": 14.7, "valuta": "EUR", "impAnnuoEur": 12.12, "lordoAnnuoEur": 14.7 } }
  ]
}

10. Recupero adesione

GET /collettive/adesioni/by-num-polizza/by-num-adesione restituisce il dettaglio e lo stato corrente di un'adesione.

Parametro di query Descrizione
numPolizza Numero della polizza master
numAdesione Numero dell'adesione (numeroAdesione restituito dall'emissione)

Esempio: GET https://testoverx-api.elbassicurazioni.it/api/v1/collettive/adesioni/by-num-polizza/by-num-adesione?numPolizza=OXC0208&numAdesione=OXC0208-000022

La risposta contiene gli stessi dati dell'emissione (contraente, bene assicurato, garanzie con premi, allegati) arricchiti da:

Campo Descrizione
id UUID interno dell'adesione
numeroAdesione Numero assegnato da REVO
stato Stato corrente (§4.5)
dataFineAdesione Data di fine adesione (coincide con dataScadenza; in caso di storno è la data dell'operazione)
idMovimento Identificativo del movimento di emissione, valorizzato a emissione avvenuta
allegati Allegati dell'adesione
Codice Descrizione
200 Adesione recuperata
401 / 403 Token non valido o scaduto / header Authorization assente
404 Adesione non trovata, oppure non ancora registrata (attendere qualche secondo dopo l'emissione). Corpo: { "timestamp", "status": 404, "error": "Not Found", "message", "path" }

11. Storno adesione

POST /collettive/movimenti/{numeroPolizza}/create-by-adesione annulla una o più adesioni della stessa polizza. È un movimento applicativo: l'adesione resta tracciata, con stato ed effetti economici aggiornati.

Esempio: POST https://testoverx-api.elbassicurazioni.it/api/v1/collettive/movimenti/OXC0208/create-by-adesione

11.1 Richiesta

{
  "numeroAdesione": ["OXC0208-000022", "OXC0208-000023"],
  "tipoMovimento": "ANNULLO_CON_RIMBORSO"
}
Campo Tipo Obbligatorio Note
numeroAdesione array di string Sì Numeri delle adesioni da stornare (anche più di una). Non può essere vuoto
tipoMovimento enum Sì ANNULLO_SENZA_EFFETTO | ANNULLO_CON_RIMBORSO
frazionamento enum No MENSILE, BIMESTRALE, TRIMESTRALE, QUADRIMESTRALE, SEMESTRALE, ANNUALE (per il pagamento unico: ANNUALE)

11.2 Tipi di movimento

Valore Quando usarlo Effetto
ANNULLO_CON_RIMBORSO Adesione già incassata (stato INCASSATA) L'adesione passa a ANNULLO_CON_RIMBORSO e viene generato il rimborso del premio
ANNULLO_SENZA_EFFETTO Adesione emessa ma non incassata L'adesione passa a ANNULLO_SENZA_EFFETTO, senza effetti economici. Su un'adesione già incassata l'operazione non viene eseguita e lo stato non cambia

Per le polizze con incasso alla firma le adesioni sono incassate subito: usare ANNULLO_CON_RIMBORSO.

Importo del rimborso: il premio netto incassato per ciascuna garanzia, moltiplicato per (365 − giorni trascorsi dalla dataEffetto) / 365.

In entrambi i casi eventuali registrazioni collegate all'adesione vengono disattivate automaticamente da REVO: il partner non deve effettuare altre chiamate.

11.3 Risposta

La risposta è 202 Accepted senza corpo: la richiesta è stata accettata ed è elaborata in modo asincrono. L'esito si legge con il recupero adesione (§10), dove stato diventa ANNULLO_CON_RIMBORSO o ANNULLO_SENZA_EFFETTO e dataFineAdesione riporta la data dell'operazione.

Codice Descrizione
202 Richiesta accettata
400 Richiesta non valida: numeroAdesione vuoto o assente, tipoMovimento assente o non ammesso
401 / 403 Token non valido o scaduto / header Authorization assente

Esito dello storno

Il codice 202 conferma la ricezione della richiesta, anche quando un numero di adesione non esiste o l'adesione si trova in uno stato che non consente il movimento richiesto: verificare sempre lo stato finale con il recupero adesione.

12. Gestione allegati

Le API consentono di caricare, elencare, scaricare ed eliminare documenti associati a un'adesione. Se la produzione e la conservazione dei documenti contrattuali sono in carico al partner, questa sezione può essere ignorata.

12.1 Upload

POST /collettive/allegato/upload (multipart/form-data)

Parte Tipo Obbligatorio Note
file file Sì Uno o più file (dimensione massima 50 MB)
idAdesione UUID Sì Il campo id dell'adesione (§4.4), non il numeroAdesione
numeroPolizza string Sì Numero della polizza master
tipoAllegato string No Tipologia del documento

La risposta è 200 OK con un messaggio di testo e non contiene l'identificativo dell'allegato: l'upload è asincrono. Per ottenere identificativo e chiave usare l'elenco (§12.2).

Codice Descrizione
200 Upload accettato
401 / 403 Token non valido o scaduto / header Authorization assente
500 Errore: nessun allegato è stato caricato; riprovare. Si ottiene anche con un idAdesione inesistente

12.2 Elenco

GET /collettive/allegato/list/{idAdesione}

[
  {
    "id": "cbb8f30b-ec75-49cf-9773-d08403453b19",
    "numeroPolizza": "OXC0208",
    "idAdesione": "2e34e4a3-d2b3-49c8-b986-9bcbb4cad707",
    "tipoAllegato": "TEST",
    "urlRemoto": "collettive/OXC0208/2e34e4a3-d2b3-49c8-b986-9bcbb4cad707/cbb8f30b-ec75-49cf-9773-d08403453b19",
    "originalFilename": "allegato-prova",
    "fileSize": 67,
    "fileExt": ".txt",
    "dataCreazione": "10/5/26, 2:26 PM"
  }
]
Codice Descrizione
200 Elenco restituito
204 Nessun allegato per l'adesione

12.3 Download

POST /collettive/allegato/download con corpo { "key": "<urlRemoto>" }, dove urlRemoto è il valore restituito dall'elenco.

La risposta è il contenuto binario del file, con Content-Disposition: attachment; filename="<nome>.<ext>" e Content-Type coerente con l'estensione.

Codice Descrizione
200 File scaricato
400 key assente o vuota
500 key non valida o allegato non scaricabile

12.4 Eliminazione

DELETE /collettive/allegato/delete/{idAllegato} — idAllegato è il campo id dell'elenco. L'operazione è irreversibile.

Codice Descrizione
200 Allegato eliminato
404 Allegato non trovato

13. Errori e regole di validazione

I 400 restituiscono il corpo { "timestamp", "status": 400, "error": "Bad Request", "message", "path" }. Messaggi che il partner può incontrare:

Messaggio (message) Causa Correzione
Codice fiscale non valido Formato del codice fiscale errato Inviare un codice fiscale di 16 caratteri
Impossibile creare l'adesione: la data di decorrenza (…) è antecedente alla data di decorrenza della polizza master (…) dataEffetto precedente alla decorrenza della polizza master Usare una dataEffetto valida per la polizza
Impossibile creare l'adesione: la data di scadenza (…) è antecedente alla data di decorrenza (…) dataScadenza precedente a dataEffetto Correggere le date
Nessuna garanzia trovata per adesione … garanzie assente o vuoto Inviare almeno una garanzia
Nessuna anagrafica trovata per adesione … Nessuna tra personaFisica, personaGiuridica, dittaIndividuale Inviare l'anagrafica del contraente
Per la garanzia '…' il premio annuo (impAnnuo) non può essere nullo. impAnnuo assente Valorizzare impAnnuo
Per la garanzia '…' i valori premio non sono coerenti: impAnnuo=…, tassePerc=…, lordoAnnuo=…. lordoAnnuo non coerente con impAnnuo e tassePerc Ricalcolare il lordo (§8.4)
La partita IVA '…' non è valida (deve essere composta da 11 cifre). Partita IVA di ditta individuale non valida Inviare 11 cifre
Bene Assicurato è obbligatorio beneAssicurato assente Inviare il bene assicurato

Le seguenti condizioni non producono un errore in fase di emissione, ma impediscono il completamento (§4.4, §4.5, §5, §6, §8): indirizzo del contraente senza CAP, codice fiscale non coerente con nome e cognome, tipoBene diverso da viaggioAssicurato o assente, bene senza variabili tecniche, dataScadenza o valuta assenti, keyGaranzia non attiva sulla polizza, più di 15 garanzie. In questi casi controllare lo stato con il recupero adesione.

14. Note tecniche

Formato data

Utilizzare lo standard ISO 8601:

YYYY-MM-DDTHH:MM:SS+HH:MM (con offset)
YYYY-MM-DDTHH:MM:SSZ (UTC)

Esempi: "2026-10-24T00:00:00.000Z", "2026-10-24T12:00:00+02:00".

Separatore decimale

Utilizzare il punto (.): "impAnnuo": 10.72 ✓ / "impAnnuo": "10,72" ✗.

Enum e distinzione tra maiuscole e minuscole

Contesto Convenzione Esempi
destinazioneArea minuscolo, camelCase italia, europa, mondo, usaCanada
fasciaEta minuscolo bassa, media, alta
tipoSoggetto, tipoMovimento UPPER_CASE con underscore PERSONA_FISICA, ANNULLO_CON_RIMBORSO
keyVartec (bene) lowerCamelCase dataPartenza, numeroAssicurati
keyVartec (garanzia) lowerCamelCase massimale, massimalePersona
keyGaranzia come da catalogo (§8.2) rischioVolo, InfInvaPerm

Fusi orari IANA

Per fusorarioPartenza e fusorarioArrivo dei voli si usano gli identificativi IANA, ad esempio Europe/Rome, Europe/Madrid, Europe/London, Europe/Athens, Europe/Paris. Elenco completo: List of tz database time zones.

Identificativi (UUID)

Non è necessario generare UUID: tutti gli identificativi interni (id, idBeneAssicurato, idGaranzia, premioGaranzia.id, keyPolizza, identificativo) sono assegnati da REVO. Gli UUID che compaiono nelle risposte (id dell'adesione, id degli allegati) vanno riutilizzati nelle chiamate successive.

15. Importazione della specifica in Postman

  1. Aprire Postman → Import.
  2. Selezionare il file openapi.yaml.
  3. Postman genera la collection con le variabili e gli esempi precompilati.
  4. Impostare la variabile baseUrl sull'ambiente di destinazione.
  5. Aggiungere il Bearer Token nella scheda Authorization della collection.

16. Cronologia della pagina

Versione Data Note
1.0.0 2026-08-06 Versione iniziale: emissione della garanzia Rischio Volo
2.0.0 2026-10-05 Revisione completa verificata sull'ambiente di test: percorsi corretti degli endpoint, tipoBene viaggioAssicurato, campi calcolati da REVO resi facoltativi, requisiti di contraente e bene assicurato, stati dell'adesione e flusso asincrono, catalogo completo delle 16 garanzie con indicazioni di integrazione, dati volo, storno asincrono (202), gestione allegati (con elenco), codici di errore

Per lo storico delle modifiche a questo sito (non alla singola guida), vedi il Changelog.