Guida di integrazione — REVO Cancellazione Mezzo di Trasporto, garanzia "Rischio Volo"

Versione

1.1.1 — Riservato, esclusivamente per uso del partner.

1. Panoramica

Questa guida descrive come integrare il partner con REVO per la garanzia "Rischio Volo", una copertura viaggio parametrica, tramite una singola chiamata API di adesione.

• Prodotto standard: il premio è interamente calcolato da un motore tariffario validato dal team Pricing REVO e fornito all'intermediario. Non è prevista alcuna chiamata API di quotazione verso REVO: in fase di sottoscrizione è richiesta esclusivamente la chiamata di adesione (emissione).
• Rinnovo automatico: non supportato (tacitoRinnovo è sempre false).
• Durata della copertura: minimo 1 giorno, massimo 30 giorni.
• Retrodatazione: non consentita — dataEffetto non può essere precedente alla data odierna.
• Postdatazione: fino a 30 giorni in anticipo per le adesioni trasmesse dall'intermediario.
• Modifica polizza: ad oggi non è un'operazione disponibile — non esiste un endpoint di modifica/endorsement per questo prodotto.

La specifica completa in formato leggibile dalle macchine è disponibile nel file openapi.yaml (OpenAPI 3.0), importabile direttamente in Postman, Insomnia o Swagger UI per esplorare gli schemi ed eseguire chiamate di test.

Flusso operativo

sequenceDiagram
    participant Partner
    participant Overx as Overx API

    Partner->>Overx: POST /adesioni (Bearer token, AdesioneRequest)
    Overx->>Overx: Valida il payload
    Overx->>Overx: Registra l'adesione
    Overx-->>Partner: 201 Created

Garanzia inclusa: rischioVolo

Attributo	Valore
Garanzia	Rischio volo
keyGaranzia	rischioVolo
Tipologia	Garanzia base — obbligatoria per la vendita del prodotto
codAnagGar	16032
ramoBilancio	0016
Aliquota fiscale (tassePerc)	21.25%**
Massimale — livello BASE	€40.000 (Italia / Europa / Mondo)
Massimale — livello TOP	€40.000 (Italia / Europa / Mondo)
Massimale per persona — BASE	Italia €500 / Europa €500 / Mondo €1.000
Massimale per persona — TOP	€2.500 (tutte le aree)
Premio lordo — BASE	€13.00
Premio lordo — TOP	€18.00
Finestra di sottoscrizione	La polizza deve essere stipulata entro 2 giorni dalla data di prenotazione oppure, se successiva, almeno 30 giorni di calendario prima della partenza

** Valore provvisorio: è prevista una ripartizione su più aliquote fiscali; l'8.15% non deve essere considerato definitivo.

Discrepanza nel documento sorgente

Il footnote del documento originale cita un valore provvisorio "8.15%" mai altrimenti usato: ogni valore effettivo mostrato nella guida e nella specifica OpenAPI è 21.25%. Verificare con il team Pricing REVO quale sia il valore corretto prima di considerare questa nota vincolante.

Nel payload JSON non esiste un campo esplicito per il livello "BASE/TOP": il motore tariffario del partner determina il livello e il payload di adesione riporta semplicemente i valori numerici risultanti relativi a massimale e premio (vedere §8).

2. Autenticazione

Ogni richiesta deve includere un Bearer Token nell'header HTTP Authorization. Si tratta dello stesso meccanismo di autenticazione a livello applicativo già utilizzato nell'ecosistema OverX: non è richiesto alcun passaggio di autenticazione specifico per I4Move.

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>"
}

Le credenziali di accesso vengono comunicate separatamente dal referente tecnico Overx.

Comportamento in caso di errore

Scenario	Stato HTTP	Azione consigliata
Token mancante	401	Aggiungere l'header Authorization
Token scaduto	401	Richiedere un nuovo token
Token valido, autorizzazioni insufficienti	403	Verificare le autorizzazioni con il team Overx

3. Endpoint

Ambiente	Base URL
Test	https://testoverx-api.elbassicurazioni.it/api/v1
UAT / Produzione	Fornito separatamente dal team Overx

Riepilogo di tutte le operazioni disponibili per questo prodotto, in ordine di utilizzo tipico:

Metodo	Percorso	Descrizione	Sezione
POST	/sicurezza/login	Ottiene il Bearer Token	§2
POST	/adesioni	Invia una nuova adesione collettiva	§4
GET	/collettive/adesioni/by-num-polizza/by-num-adesione	Recupera il dettaglio di un'adesione esistente	§12
POST	/movimenti/create-by-adesione	Storna (annulla) un'adesione esistente	§13
POST	/collettive/allegato/upload	Carica un allegato	§14
POST	/collettive/allegato/download	Scarica un allegato	§14
DELETE	/collettive/allegato/delete/{idAllegato}	Elimina un allegato	§14

La modifica (endorsement) di una polizza/adesione non è un'operazione disponibile per questo prodotto (§1).

Header obbligatori

Authorization: Bearer <token>
Content-Type: application/json

4. Struttura del payload — Adesione

Il corpo della richiesta per POST /adesioni è un oggetto JSON (AdesioneRequest) con la seguente struttura di alto livello:

AdesioneRequest
├── Metadati generali (keyPolizza, numeroPolizza, dataEffetto, dataScadenza, tacitoRinnovo, ...)
├── personaFisica | personaGiuridica | dittaIndividuale (mutuamente esclusivi — vedere §6)
├── beneAssicurato
│   └── variabiliTecniche[] (dati viaggio, assicurati, volo/i)
└── garanzie[] (sempre esattamente 1 voce: rischioVolo)
    ├── variabiliTecniche[] (MASSIMALE, MASSIMALE_PERSONA)
    └── premioGaranzia (premio netto, imposte, premio lordo)

5. Riferimento campi — Dati generali

Campo JSON	Tipo	Obbligatorio	Vincoli / Dominio
keyPolizza	string (uuid)	Sì	Identificativo univoco interno della polizza (UUID v4)
numeroAdesioneEsterno	string	No	Identificativo dell'adesione lato partner; può essere una stringa vuota
numeroPolizza	string	Sì	Numero di polizza, fornito separatamente dal team Overx
dataCreazione	string (datetime)	Sì	Timestamp di creazione — ISO 8601
dataEffetto	string (datetime)	Sì	Deve essere >= oggi (nessuna retrodatazione); deve essere <= oggi + 30 giorni (limite di postdatazione del partner) — ISO 8601
dataScadenza	string (datetime)	Sì	Deve essere > dataEffetto; (dataScadenza − dataEffetto) deve essere compreso tra 1 e 30 giorni — ISO 8601
tacitoRinnovo	boolean	Sì	Valore fisso: false — non supporta il rinnovo automatico
source	string	Sì	Canale di origine della richiesta (es. FE)
stato	string	Sì	Stato al momento dell'invio (es. EMESSA)
codiceProdotto	string	Sì	Codice del prodotto assicurativo. Valore fisso: A001
tipoSoggetto	enum	Sì	PERSONA_FISICA | PERSONA_GIURIDICA | DITTA_INDIVIDUALE

6. Riferimento campi — Contraente

Il payload prevede mutua esclusività tra le tipologie di soggetto: nel body deve essere presente una e una sola tra personaFisica, personaGiuridica e dittaIndividuale, coerente con il valore di tipoSoggetto (§5).

personaFisica

Campo JSON	Tipo	Obbligatorio	Vincoli
codiceFiscale	string	Sì	16 caratteri, validazione del formato del codice fiscale italiano
nome	string	Sì	Massimo 50 caratteri
cognome	string	Sì	Massimo 50 caratteri
nazione	string	Sì	ISO 3166-1 alpha-3 (es. ESP)
indirizzo	string	No	Indirizzo completo di residenza
numeroTelefono	number	No	Solo cifre, senza prefisso internazionale
email	string (email)	No	Formato user@domain.tld
pec	string	No	Indirizzo PEC (può essere una stringa vuota)

personaGiuridica

Campo JSON	Tipo	Vincoli
partitaIva	string	Partita IVA
formaSocietaria	string	Es. SPA
ragioneSociale	string	Denominazione legale dell'azienda
codiceAteco	string	Codice ATECO dell'attività (es. 80.10)
nazione	string	ISO 3166-1 alpha-3
indirizzo	string	Indirizzo completo
numeroTelefono	number	Solo cifre, senza prefisso internazionale
email	string (email)	—
pec	string	—

dittaIndividuale

Campo JSON	Tipo	Vincoli
codiceFiscale	string	16 caratteri, formato codice fiscale italiano
partitaIva	string	Partita IVA
nome	string	—
cognome	string	—
nazione	string	ISO 3166-1 alpha-3
indirizzo	string	Indirizzo completo
numeroTelefono	number	Solo cifre, senza prefisso internazionale
email	string (email)	—
pec	string	—

Obbligatorietà campi non confermata

A differenza di personaFisica, per personaGiuridica e dittaIndividuale la fonte non specifica esplicitamente quali campi siano obbligatori. Per analogia con personaFisica è presumibile che gli identificativi (ragioneSociale/partitaIva/codiceFiscale, nazione) siano obbligatori e indirizzo/numeroTelefono/email/pec opzionali — ma va confermato con il team prodotto prima di considerarlo vincolante.

7. Riferimento campi — Bene assicurato (Viaggio)

7.1 Oggetto beneAssicurato

Campo JSON	Tipo	Obbligatorio	Vincoli
tipoBene	string	Sì	Valore fisso: gruppo di assicurati
identificativo	string (uuid)	Sì	Identificativo univoco del bene assicurato (UUID v4)
variabiliTecniche	array	Sì	Elenco di coppie keyVartec / valueVartec — vedere §7.2

7.2 Variabili tecniche del viaggio (variabiliTecniche)

keyVartec	Tipo valueVartec	Obbligatorio	Descrizione
prenotazione	date-time string	Sì	Data e ora di prenotazione del viaggio
destinazioneArea	enum string	Sì	italia | europa | mondo
dataPartenza	date-time string	Sì	Data di partenza (inizio della copertura)
dataRientro	date-time string	Sì	Data di rientro (fine della copertura)
destinazionePaese	string	Sì	Nome del principale Paese di destinazione
dataGridDatiAssicurato	array (DatoAssicurato)	Sì	Elenco degli assicurati — vedere §7.3
numeroAssicurati	integer	Sì	Numero totale degli assicurati

7.3 Schema DatoAssicurato

Utilizzato come elemento dell'array valueVartec per la chiave dataGridDatiAssicurato:

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

8. Riferimento campi — Garanzia e premio (rischioVolo)

8.1 Oggetto Garanzia

Campo	Tipo	Obbligatorio	Vincoli
id	string (uuid)	No	Identificativo della garanzia nell'adesione. Il valore inviato viene sempre sovrascritto dal backend (UUID.randomUUID()) — può essere omesso o valorizzato con un placeholder, non ha effetto
idGarOverx	string (uuid)	Sì (richiesto per policy REVO)	Identificativo della garanzia nel catalogo Overx: solo il partner sa quale garanzia intende attivare, quindi va sempre inviato esplicitamente — non affidarsi al comportamento di fallback dell'API (vedere nota tecnica sotto)
nomeGaranzia	string	Sì	Nome completo — RISCHIO VOLO
keyGaranzia	enum	Sì	Valore fisso: rischioVolo
codAnagGar	string	Sì	Codice anagrafico della garanzia — 16032
ramoBilancio	string	Sì	0016
variabiliTecniche	array	No	Massimali — vedere §8.2
premioGaranzia	object	Sì	Premio netto, imposte e premio lordo — vedere §8.3

8.2 Variabili tecniche della garanzia (keyVartec)

keyVartec	Tipo	Livello BASE	Livello TOP
MASSIMALE	number	40000 (stesso valore per Italia / Europa / Mondo)	40000 (stesso valore per tutte le aree)
MASSIMALE_PERSONA	number	500 per Italia/Europa, 1000 per Mondo — il valore corrispondente alla destinazioneArea dell'adesione	2500 (tutte le aree)

Non esiste un campo esplicito di selezione del livello: il partner invia i valori numerici corrispondenti al livello (BASE o TOP) acquistato dal cliente finale.

8.3 Oggetto premioGaranzia

Campo	Tipo	Obbligatorio	Descrizione
id	string (uuid)	Sì	Identificativo univoco del premio (UUID v4)
impAnnuo	number	Sì	Premio annuo netto
tassePerc	number	Sì	Percentuale di imposta applicata — 21.25%** per rischioVolo
lordoAnnuo	number	Sì	Premio annuo lordo (netto + imposte)
valuta	string	Sì	Codice valuta ISO 4217 (EUR)
impAnnuoEur	number	No	Premio netto in EUR
lordoAnnuoEur	number	No	Premio lordo in EUR

Livello	lordoAnnuo	tassePerc	impAnnuo (derivato)
BASE	€13.00	21.25%**	€10.72
TOP	€18.00	21.25%**	€14.84

9. Esempio completo di payload

L'esempio seguente rappresenta un'adesione di livello BASE per 1 assicurato.

{
  "keyPolizza": "749115fa-a5c9-4c98-9461-f10b7a6ae559",
  "numeroAdesioneEsterno": "ADH-2026-00123",
  "numeroPolizza": "OXC0XXX",
  "dataCreazione": "2026-04-10T12:22:27.871Z",
  "dataEffetto": "2026-04-24T00:00:00.000Z",
  "dataScadenza": "2026-04-30T00:00:00.000Z",
  "tacitoRinnovo": false,
  "source": "FE",
  "stato": "EMESSA",
  "codiceProdotto": "A001",
  "tipoSoggetto": "PERSONA_FISICA",
  "personaFisica": {
    "codiceFiscale": "BNCMRC85M10L781A",
    "nome": "Marco",
    "cognome": "Bianchi",
    "nazione": "ESP",
    "indirizzo": "Calle Mayor 15, 28013 Madrid",
    "numeroTelefono": 612345678,
    "email": "marco.bianchi@email.it",
    "pec": ""
  },
  "beneAssicurato": {
    "tipoBene": "gruppo di assicurati",
    "identificativo": "9f5bad19-3f0c-4252-a9b7-90a7a449196a",
    "variabiliTecniche": [
      { "id": "4f3e9dde-f001-4b9c-9757-e7c2a9bbf7e2", "idBeneAssicurato": "9f5bad19-3f0c-4252-a9b7-90a7a449196a", "keyVartec": "prenotazione", "valueVartec": "2026-04-10T12:00:00+02:00" },
      { "id": "8fa94a3d-2162-4158-a2a1-d3a981b15b89", "idBeneAssicurato": "9f5bad19-3f0c-4252-a9b7-90a7a449196a", "keyVartec": "destinazioneArea", "valueVartec": "italia" },
      { "id": "492a5a91-8012-4e87-b0e5-693aae393b31", "idBeneAssicurato": "9f5bad19-3f0c-4252-a9b7-90a7a449196a", "keyVartec": "dataPartenza", "valueVartec": "2026-04-24T12:00:00+02:00" },
      { "id": "757d6edb-4cc6-432c-a883-490943f91dc5", "idBeneAssicurato": "9f5bad19-3f0c-4252-a9b7-90a7a449196a", "keyVartec": "destinazionePaese", "valueVartec": "Italia" },
      { "id": "e7d59bc6-0308-4afb-8138-046632a9a684", "idBeneAssicurato": "9f5bad19-3f0c-4252-a9b7-90a7a449196a", "keyVartec": "dataRientro", "valueVartec": "2026-04-30T12:00:00+02:00" },
      {
        "id": "c0358e63-04d6-41b1-a1ac-612e46acd5ab",
        "idBeneAssicurato": "9f5bad19-3f0c-4252-a9b7-90a7a449196a",
        "keyVartec": "dataGridDatiAssicurato",
        "valueVartec": [
          { "cognomeAssicurato": "Bianchi", "nomeAssicurato": "Marco", "fasciaEta": "media", "email": "marco.bianchi@email.it" }
        ]
      },
      { "id": "b9514356-6cba-4fd8-97b4-1a834d113def", "idBeneAssicurato": "9f5bad19-3f0c-4252-a9b7-90a7a449196a", "keyVartec": "numeroAssicurati", "valueVartec": 1 }
    ]
  },
  "garanzie": [
    {
      "id": "2efe35f3-9b1b-49b3-a0a3-c595f4654199",
      "idGarOverx": "5f09a062-e355-48cb-8232-c6fc7dd88973",
      "nomeGaranzia": "RISCHIO VOLO",
      "keyGaranzia": "rischioVolo",
      "codAnagGar": "16032",
      "ramoBilancio": "0016",
      "variabiliTecniche": [
        { "idGaranzia": "2efe35f3-9b1b-49b3-a0a3-c595f4654199", "keyVartec": "MASSIMALE", "valueVartec": 40000 },
        { "idGaranzia": "2efe35f3-9b1b-49b3-a0a3-c595f4654199", "keyVartec": "MASSIMALE_PERSONA", "valueVartec": 500 }
      ],
      "premioGaranzia": {
        "id": "54a048d2-0dff-4281-99c9-2c8c4afb08e8",
        "impAnnuo": 10.72,
        "tassePerc": 21.25,
        "lordoAnnuo": 13.00,
        "valuta": "EUR",
        "impAnnuoEur": 10.72,
        "lordoAnnuoEur": 13.00
      }
    }
  ]
}

10. Errori comuni e regole di validazione

Regole semantiche obbligatorie

Regola	Campo	Errore restituito
dataEffetto deve essere >= oggi	dataEffetto	422
dataEffetto deve essere <= oggi + 30 giorni (limite di postdatazione del partner)	dataEffetto	422
dataScadenza deve essere > dataEffetto	dataScadenza	422
(dataScadenza − dataEffetto) deve essere compreso tra 1 e 30 giorni	dataScadenza	422
La polizza deve essere stipulata entro 2 giorni da prenotazione oppure almeno 30 giorni di calendario prima di dataPartenza	beneAssicurato.variabiliTecniche (prenotazione / dataPartenza)	422
garanzie deve contenere esattamente una voce, rischioVolo	garanzie	400
codiceFiscale deve rispettare il formato del codice fiscale italiano	personaFisica.codiceFiscale	400

Errori di formato comuni

Errore	Causa	Correzione
400 su destinazioneArea	Uso errato di maiuscole/minuscole (es. Italia)	Usare il minuscolo: italia
400 su fasciaEta	Valore non presente nell'enum	Usare solo: bassa, media, alta
400 su keyGaranzia	Chiave non riconosciuta	Per I4Move è valido solo rischioVolo
400 su MASSIMALE / MASSIMALE_PERSONA	Uso errato di maiuscole/minuscole (es. massimale)	Usare UPPER_CASE
400 sulle date	Formato non ISO 8601	Usare YYYY-MM-DDTHH:MM:SSZ
400 sugli importi	Virgola come separatore decimale	Usare il punto: 12.50
401	Header Authorization mancante o non valido	Controllare Bearer <token>
401	Token scaduto	Richiedere un nuovo token

11. Note tecniche

Formato data

Utilizzare sempre lo standard ISO 8601:

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

Esempi corretti: "2026-04-24T00:00:00.000Z", "2026-04-24T12:00:00+02:00"

Separatore decimale

Utilizzare sempre il punto (.) per i valori numerici: "impAnnuo": 10.72 ✓ / "impAnnuo": "10,72" ✗

Enum e distinzione tra maiuscole e minuscole

I valori enum distinguono tra maiuscole e minuscole. Convenzioni utilizzate nel payload:

Contesto	Convenzione	Esempi
destinazioneArea	lowercase	italia, europa, mondo
fasciaEta	lowercase	bassa, media, alta
tipoSoggetto	UPPER_CASE (underscore)	PERSONA_FISICA
keyVartec (garanzia)	UPPER_CASE (underscore)	MASSIMALE, MASSIMALE_PERSONA
keyVartec (bene)	lowerCamelCase	dataPartenza, destinazioneArea
keyGaranzia	lowerCamelCase	rischioVolo

Fusi orari IANA

Per gli identificativi di fuso orario, utilizzare gli identificativi IANA, ad esempio:

Città / Aeroporto	IANA
Italia (LIN, MXP, FCO, LIS...)	Europe/Rome
Spagna (BCN, MAD...)	Europe/Madrid
Regno Unito (LHR, LGW...)	Europe/London
Grecia (ATH...)	Europe/Athens
Francia (CDG, ORY...)	Europe/Paris

Elenco completo: List of tz database time zones (IANA).

UUID

Formato UUID v4 richiesto per tutti i campi id/identificativo:

xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

Non tutti questi campi hanno lo stesso comportamento lato server — verificato sul codice reale del backend (om-collettive):

Campo	Comportamento
keyPolizza, beneAssicurato.identificativo	Generati dal partner, il valore inviato è quello utilizzato
garanzie[].idGarOverx	Da inviare sempre, per policy REVO: identifica quale garanzia il partner intende attivare, informazione che solo il partner possiede. Nota tecnica: se il campo venisse omesso l'API lo valorizzerebbe comunque in automatico pescando l'id dal catalogo (match su key/nome) — ma questo fallback non va usato in produzione, va sempre inviato il valore esplicito
garanzie[].id	Sempre sovrascritto dal backend con un nuovo UUID, indipendentemente dal valore inviato — può essere omesso
garanzie[].variabiliTecniche[].id e .idGaranzia	Sempre sovrascritti/ricostruiti dal backend; il partner può omettere questi campi o inviare un placeholder
beneAssicurato.variabiliTecniche[].id e .idBeneAssicurato	Sempre sovrascritti/ricostruiti dal backend, stesso motivo — possono essere omessi
premioGaranzia.id	Non verificato nel codice — trattarlo per ora come generato dal partner, in attesa di conferma

In pratica: per i campi marcati "sempre sovrascritti" è sufficiente inviare un UUID v4 qualsiasi (anche un placeholder fisso), oppure ometterli — il backend non ne tiene conto. idGarOverx è l'unica eccezione: va sempre valorizzato esplicitamente dal partner.

12. Recupero adesione (GET)

Consente di ottenere il dettaglio completo di un'adesione a partire da numero di polizza e numero di adesione. Richiede autenticazione valida OverX.

12.1 Endpoint

Metodo	Microservizio	Path
GET	om-collettive	/api/v1/collettive/adesioni/by-num-polizza/by-num-adesione

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

12.2 Parametri di query

Parametro	Descrizione
numPolizza	Numero della polizza Master
numAdesione	Numero dell'adesione

12.3 Risposta

La risposta è un oggetto AdesioneDTO che ripropone gli stessi campi della richiesta di adesione (dati generali, personaFisica/personaGiuridica/dittaIndividuale, beneAssicurato, garanzie), arricchiti dagli identificativi assegnati da REVO (id, numeroAdesione).

Campi interni omessi

La risposta reale del backend include anche blocchi interni (dati di polizza, intermediario, configurazione di prodotto/tariffazione) non documentati qui perché non necessari all'integrazione del partner.

{
  "id": "fa1b16bf-0d96-49ae-84d6-4964bbf9772b",
  "tipoSoggetto": "PERSONA_FISICA",
  "numeroPolizza": "OXC0XXX",
  "numeroAdesione": "OX00232638-000003",
  "numeroAdesioneEsterno": "ADH-2026-00123",
  "codiceProdotto": "A001",
  "dataCreazione": "2026-04-10T12:22:27.871Z",
  "dataEffetto": "2026-04-24T00:00:00.000Z",
  "dataScadenza": "2026-04-30T00:00:00.000Z",
  "keyPolizza": "749115fa-a5c9-4c98-9461-f10b7a6ae559",
  "personaFisica": { "...": "come da richiesta di adesione, §6" },
  "personaGiuridica": null,
  "dittaIndividuale": null,
  "beneAssicurato": { "...": "come da richiesta di adesione, §7" },
  "garanzie": [ { "...": "come da richiesta di adesione, §8" } ]
}

12.4 Codici risposta

Codice	Descrizione
200	Adesione recuperata con successo
404	Adesione non trovata
401	Utente non autorizzato o token non valido
500	Errore interno durante il recupero dell'adesione

13. Storno adesione

L'operazione di storno consente di annullare un'adesione precedentemente creata, registrando un movimento amministrativo coerente con le regole di polizza.

Lo storno è gestito come movimento applicativo, non come cancellazione fisica: l'adesione resta tracciata a sistema, ma stato ed effetti economici vengono aggiornati. Richiede autenticazione valida OverX.

13.1 Endpoint

Metodo	Microservizio	Path
POST	om-collettive	/api/v1/movimenti/create-by-adesione

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

13.2 Payload di richiesta

{
  "numeroAdesione": "OX00232638-000003",
  "frazionamento": "TRIMESTRALE",
  "tipoMovimento": "ANNULLO_SENZA_EFFETTO",
  "dataMovimento": "2026-04-24T00:00:00.000Z"
}

13.3 Descrizione campi

Campo	Note
numeroAdesione	Identificativo univoco dell'adesione da stornare
frazionamento	Periodicità di pagamento associata all'adesione
tipoMovimento	Tipologia di movimento amministrativo applicato — vedere §13.5
dataMovimento	Data del movimento in formato ISO (yyyy-MM-dd o ISO completo)

13.4 Codici risposta

Codice	Descrizione
200	Movimento di storno registrato correttamente
404	Adesione non trovata
400	Richiesta non valida o dati mancanti
401	Utente non autorizzato o token non valido
500	Errore interno durante lo storno

13.5 Valori ammessi per tipoMovimento

• ANNULLO_SENZA_EFFETTO — annullamento tecnico senza effetti economici.
• ANNULLO_CON_RIMBORSO — annullo/storno a titolo incassato.

In entrambi i casi, eventuali registrazioni su blockchain associate all'adesione vengono automaticamente disattivate dai sistemi REVO nell'ambito della stessa operazione applicativa.

Blockchain gestita da REVO

Il partner non deve effettuare alcuna chiamata aggiuntiva per la gestione della blockchain: la logica di aggiornamento e disattivazione è interamente a carico dei sistemi REVO.

13.6 Comportamento applicativo

1. L'adesione viene recuperata tramite numeroAdesione.
2. Viene validata la possibilità di effettuare lo storno in base allo stato corrente.
3. Viene registrato il movimento secondo il tipoMovimento indicato.
4. Lo stato dell'adesione viene aggiornato coerentemente con l'operazione richiesta.
5. Nei casi previsti (es. ANNULLO_CON_RIMBORSO), viene gestita automaticamente la disattivazione delle eventuali registrazioni su blockchain.

Non viene effettuata alcuna eliminazione fisica dei dati.

14. Gestione allegati per adesione

Le API di gestione allegati consentono di caricare, scaricare ed eliminare documenti associati a un'adesione emessa. Gli allegati sono archiviati su S3 e tracciati a livello applicativo tramite database. Richiedono autenticazione valida OverX.

Quando serve

Se la produzione e conservazione delle stampe contrattuali è in carico al partner, questa sezione può essere ignorata.

14.1 Upload allegato

Metodo	Path
POST	/api/v1/collettive/allegato/upload

Riceve il file da caricare e i metadati associati all'adesione, salva il file su S3 e persiste nel database le informazioni dell'allegato (identificativo, nome originale, estensione, path S3, riferimento all'adesione). Restituisce le informazioni dell'allegato caricato, inclusa la chiave di storage necessaria per le operazioni successive.

14.2 Download allegato

Metodo	Path
POST	/api/v1/collettive/allegato/download

Riceve in input la chiave dell'allegato (path S3), recupera i metadati dal database, scarica il file da S3 e restituisce il contenuto binario con nome file originale ed estensione corretta (header Content-Disposition: attachment, Content-Type coerente con l'estensione).

Codice	Descrizione
200	File scaricato con successo
400	ID allegato non valido
404	Allegato non trovato
500	Errore interno durante il download

14.3 Delete allegato

Metodo	Path
DELETE	/api/v1/collettive/allegato/delete/{idAllegato}

Elimina il file fisico da S3 e rimuove il relativo record dal database. L'operazione è irreversibile.

Codice	Descrizione
200	Allegato eliminato con successo
404	Allegato non trovato
500	Errore interno durante l'eliminazione

15. Importazione della specifica in Postman

1. Aprire Postman → Import
2. Selezionare il file openapi.yaml
3. Postman genera automaticamente 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	Autore	Note
1.0.0	2026-08-06	Matteo Costantini	Versione iniziale. Riprende la Guida di integrazione A001 per ambito (singolo endpoint di adesione) e convenzioni tecniche (keyPolizza, id/idBeneAssicurato nelle variabili tecniche, keyVartec in UPPER_CASE per i massimali a livello di garanzia), adattata ai dati del prodotto I4Move presenti nella scheda prodotto (garanzia rischioVolo).
1.1.0	2026-09-21	Matteo Costantini	Aggiunti personaGiuridica/dittaIndividuale (§6), Recupero adesione GET, Storno adesione, Gestione allegati — integrati dalla pagina Confluence "Integrazione API Collettive OverX in I4T" e da conferma diretta del product owner. Chiarito che la modifica polizza non è un'operazione disponibile per questo prodotto (§1).
1.1.1	2026-09-21	Matteo Costantini	Riordinate le sezioni per una lettura più lineare (errori/note tecniche subito dopo il flusso di adesione, operazioni accessorie a seguire); aggiunto l'endpoint di login allo Swagger; aggiunto un riepilogo di tutti gli endpoint (§3); chiarito — verificato sul codice reale di om-collettive — quali campi id/idGarOverx sono generati dal partner e quali vengono sempre sovrascritti o auto-popolati dal backend (§8.1, §11).

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