openapi: 3.0.3

info:
  title: Partner Integration API — A001 Travel
  version: "2.0.0"
  description: |
    OpenAPI specification for the product **A001 — Travel** (guarantee **Rischio Volo** /
    *Cancellazione mezzo di trasporto* and the other Travel guarantees). It covers enrolment
    issuing, enrolment retrieval, cancellation (storno), attachment management and flight
    schedule lookup. Policy modification (endorsement) is **not available**.

    ## Authentication
    All requests require a **Bearer Token** in the `Authorization` header, obtained via
    `POST /sicurezza/login` with the credentials provided by the Overx team. A missing header
    returns `403`; an invalid or expired token returns `401`.

    ## Asynchronous processing
    Issuing is asynchronous: `POST /collettive/adesioni/` returns `200` with `numeroAdesione`
    and `stato: EMESSA` as soon as the request is received. Issuing and collection complete
    within a few seconds; read the final `stato` with `GET
    /collettive/adesioni/by-num-polizza/by-num-adesione` (it may answer `404` for the first
    seconds). Cancellation and attachment upload are asynchronous as well.

    ## General technical notes
    - Decimal separator: **dot** (`.`), e.g. `12.50`
    - Date format: **ISO 8601** (`YYYY-MM-DDTHH:MM:SSZ` or with offset)
    - Enums and keys (`keyVartec`, `keyGaranzia`) are **case-sensitive**
  contact:
    name: Overx Integration Team
  license:
    name: Internal use — Confidential

servers:
  - url: "https://testoverx-api.elbassicurazioni.it/api/v1"
    description: Test environment
  - url: "{baseUrl}"
    description: Production environment — URL provided separately by the Overx team.
    variables:
      baseUrl:
        default: https://testoverx-api.elbassicurazioni.it/api/v1
        description: API base URL

security:
  - bearerAuth: []

tags:
  - name: Authentication
  - name: Enrolments
  - name: Attachments
  - name: Flights

paths:
  /sicurezza/login:
    post:
      operationId: login
      summary: Obtain a Bearer Token
      description: |
        Authenticates the OverX application user (credentials provided separately by the Overx
        team) and returns the Bearer Token to use in the `Authorization` header of every other
        call. The token is valid for `expires_in` seconds (2400 = 40 minutes); repeat the login
        when it expires.
      tags: [Authentication]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                  example: "<username>"
                password:
                  type: string
                  format: password
                  example: "<password>"
      responses:
        "200":
          description: Login successful.
          content:
            application/json:
              schema:
                type: object
                required: [access_token, token_type, expires_in]
                properties:
                  access_token:
                    type: string
                    description: Bearer JWT to use in the Authorization header of every other call.
                  token_type:
                    type: string
                    example: "Bearer"
                  expires_in:
                    type: integer
                    description: Validity of access_token in seconds.
                    example: 2400
                  refresh_token:
                    type: string
                  refresh_expires_in:
                    type: integer
                    example: 28799
                  id_token:
                    type: string
                  scope:
                    type: string
                    example: "openid email family_name"
                  session_state:
                    type: string
                  not-before-policy:
                    type: integer

  /collettive/adesioni/:
    post:
      operationId: creaAdesione
      summary: Issue a new enrolment
      description: |
        Registers a new enrolment linked to the master policy given in `numeroPolizza`.

        The response confirms receipt (`stato: EMESSA`, `numeroAdesione`, `id`). Issuing and
        collection complete asynchronously; read the final `stato` with the retrieval operation.

        **Fields calculated by REVO (optional)**: `keyPolizza`, `codiceProdotto`,
        `beneAssicurato.identificativo`, `garanzie[].idGarOverx`, `nomeGaranzia`, `codAnagGar`,
        `ramoBilancio` and all internal ids are completed automatically — do not send them.
        `dataCreazione` and `stato` are assigned by REVO and ignored if sent.

        **Requirements for the enrolment to be registered and completed**: `tipoBene` =
        `viaggioAssicurato` and at least one technical variable of the insured asset; a valid
        `keyGaranzia` among the guarantees active on the policy (when it is not recognised,
        `idGarOverx`, `nomeGaranzia` and `codAnagGar` come back `null` and the enrolment is not
        registered); `dataScadenza`; `premioGaranzia` with `impAnnuo`, `tassePerc`, `lordoAnnuo`
        and `valuta`; contractor address with a postal code; tax code consistent with first and
        last name.
      tags: [Enrolments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AdesioneRequest"
            examples:
              RischioVolo:
                summary: Single guarantee Rischio Volo (BASE level)
                value:
                  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
      responses:
        "200":
          description: |
            Request received. `stato` is `EMESSA` at this point and is **not** the final state:
            read it with the retrieval operation after a few seconds.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdesioneResponse"
        "400":
          description: |
            Invalid data. Messages include: `Codice fiscale non valido`, effective/expiry date
            before the master policy effective date or inconsistent, `Nessuna garanzia trovata…`,
            `Nessuna anagrafica trovata…`, missing `impAnnuo`, inconsistent premium values
            (`lordoAnnuo` vs `impAnnuo` and `tassePerc`), invalid VAT number, missing
            `beneAssicurato`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Invalid or expired token (empty body)
        "403":
          description: Missing `Authorization` header (empty body)
        "409":
          description: An enrolment with the same `numeroAdesioneEsterno` already exists on the policy.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DuplicateErrorResponse"
        "500":
          description: Internal error (also returned when `numeroPolizza` does not exist).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /collettive/adesioni/by-num-polizza/by-num-adesione:
    get:
      operationId: recuperaAdesione
      summary: Retrieve an enrolment and its current state
      description: |
        Returns the detail and the **current state** (`stato`) of an enrolment. For the first
        seconds after issuing the enrolment may not be registered yet and the answer is `404`.
      tags: [Enrolments]
      parameters:
        - name: numPolizza
          in: query
          required: true
          schema:
            type: string
          description: Master policy number.
          example: "OXC0208"
        - name: numAdesione
          in: query
          required: true
          schema:
            type: string
          description: Enrolment number (`numeroAdesione` returned by the issuing operation).
          example: "OXC0208-000022"
      responses:
        "200":
          description: Enrolment retrieved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdesioneDetail"
        "401":
          description: Invalid or expired token (empty body)
        "403":
          description: Missing `Authorization` header (empty body)
        "404":
          description: Enrolment not found, or not yet registered.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /collettive/movimenti/{numeroPolizza}/create-by-adesione:
    post:
      operationId: stornoAdesione
      summary: Cancel (storno) one or more enrolments
      description: |
        Registers a cancellation movement for one or more enrolments of the same policy. It is an
        applicative movement, not a physical deletion: the enrolment stays tracked with its state
        and economic effects updated. Related records are deactivated automatically by REVO.

        The request is processed **asynchronously**: `202` confirms receipt, also when an
        enrolment number does not exist or its state does not allow the requested movement.
        Read the final `stato` with the retrieval operation.

        - `ANNULLO_CON_RIMBORSO`: for already collected enrolments (`INCASSATA`); state becomes
          `ANNULLO_CON_RIMBORSO` and the premium is refunded. Refund amount: collected net
          premium × (365 − days elapsed since `dataEffetto`) / 365.
        - `ANNULLO_SENZA_EFFETTO`: for issued but **not collected** enrolments; state becomes
          `ANNULLO_SENZA_EFFETTO`, with no economic effects. On a collected enrolment it is not
          performed and the state does not change.
      tags: [Enrolments]
      parameters:
        - name: numeroPolizza
          in: path
          required: true
          schema:
            type: string
          description: Master policy number the enrolments belong to.
          example: "OXC0208"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StornoRequest"
      responses:
        "202":
          description: Request accepted, processing is asynchronous (empty body).
        "400":
          description: Invalid request — empty or missing `numeroAdesione`, missing or unsupported `tipoMovimento`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Invalid or expired token (empty body)
        "403":
          description: Missing `Authorization` header (empty body)

  /collettive/allegato/upload:
    post:
      operationId: uploadAllegato
      summary: Upload attachments for an enrolment
      description: |
        Uploads one or more files and associates them with an enrolment. Processing is
        asynchronous: the response is a text message and **does not contain the attachment
        identifier** — read it with the list operation. Maximum file size 50 MB.
      tags: [Attachments]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, idAdesione, numeroPolizza]
              properties:
                file:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: One or more files.
                idAdesione:
                  type: string
                  format: uuid
                  description: The `id` of the enrolment (not the `numeroAdesione`).
                numeroPolizza:
                  type: string
                  description: Master policy number.
                tipoAllegato:
                  type: string
                  description: Document type (optional).
      responses:
        "200":
          description: Upload accepted.
          content:
            text/plain:
              schema:
                type: string
                example: "Messaggio kafka per l'upload degli allegati inviato con successo."
        "401":
          description: Invalid or expired token (empty body)
        "403":
          description: Missing `Authorization` header (empty body)
        "500":
          description: Upload failed, no attachment was stored — retry. Also returned for an unknown `idAdesione`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /collettive/allegato/list/{idAdesione}:
    get:
      operationId: listAllegati
      summary: List the attachments of an enrolment
      tags: [Attachments]
      parameters:
        - name: idAdesione
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The `id` of the enrolment.
      responses:
        "200":
          description: Attachment list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Allegato"
        "204":
          description: No attachment for the enrolment.
        "401":
          description: Invalid or expired token (empty body)
        "403":
          description: Missing `Authorization` header (empty body)

  /collettive/allegato/download:
    post:
      operationId: downloadAllegato
      summary: Download an attachment
      description: |
        Returns the binary content of the file, with `Content-Disposition: attachment;
        filename="<name>.<ext>"` and a `Content-Type` consistent with the extension.
      tags: [Attachments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [key]
              properties:
                key:
                  type: string
                  description: The `urlRemoto` value returned by the list operation.
                  example: "collettive/OXC0208/2e34e4a3-d2b3-49c8-b986-9bcbb4cad707/cbb8f30b-ec75-49cf-9773-d08403453b19"
      responses:
        "200":
          description: File content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Missing or empty `key`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Invalid or expired token (empty body)
        "403":
          description: Missing `Authorization` header (empty body)
        "500":
          description: Invalid `key` or attachment not downloadable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /collettive/allegato/delete/{idAllegato}:
    delete:
      operationId: deleteAllegato
      summary: Delete an attachment
      description: Deletes the file and its record. **Irreversible.**
      tags: [Attachments]
      parameters:
        - name: idAllegato
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The attachment `id` returned by the list operation.
      responses:
        "200":
          description: Attachment deleted (empty body).
        "401":
          description: Invalid or expired token (empty body)
        "403":
          description: Missing `Authorization` header (empty body)
        "404":
          description: Attachment not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /reverse-proxy/forward/api/v1/mobility/flights-schedule:
    post:
      operationId: flightsSchedule
      summary: Retrieve flight schedule data
      description: |
        Returns the schedule of a flight in the `scheduled` array (one element per leg). The
        element must be **mapped** to the `dataGridVoloAssicurato` object (see the integration
        guide): the response field names differ from the ones expected in the enrolment
        (`aeroportoPartenza` → `aereoportoPartenza`, `timezonePartenza` → `fusorarioPartenza`,
        `timestampPartenza` → `dataPartenza`, `timestampPartenzaUtc` → `dataPartenzaUtc`, and
        likewise for arrival). `dataPartenza` is always required. With `numeroVolo` the airports must not be sent;
        without `numeroVolo` at least one of `aeroportoPartenza` and `aeroportoArrivo` is
        required (`aeroportoArrivo` is required for multi-leg flights).
      tags: [Flights]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [dataPartenza]
              properties:
                numeroVolo:
                  type: string
                  example: "EJU5182"
                dataPartenza:
                  type: string
                  description: Local departure date (YYYY-MM-DD).
                  example: "2025-06-04"
                aeroportoPartenza:
                  type: string
                  description: ICAO code (4 letters, e.g. `LIRF`). IATA codes are not accepted.
                aeroportoArrivo:
                  type: string
                  description: ICAO code (4 letters, e.g. `KJFK`). IATA codes are not accepted.
      responses:
        "200":
          description: Flight schedule data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  scheduled:
                    type: array
                    items:
                      type: object
                      description: One element per leg (the supplier adds further fields, not to be sent).
                      properties:
                        numeroVolo:
                          type: string
                          example: "ITY610"
                        numeroVoloPdf:
                          type: string
                          nullable: true
                          description: Null in searches by airports only.
                          example: "AZ610"
                        aeroportoPartenza:
                          type: string
                          example: "LIRF"
                        aeroportoPartenzaIata:
                          type: string
                          example: "FCO"
                        timezonePartenza:
                          type: string
                          example: "Europe/Rome"
                        timestampPartenza:
                          type: string
                          format: date-time
                        timestampPartenzaUtc:
                          type: string
                          format: date-time
                        aeroportoArrivo:
                          type: string
                          example: "KJFK"
                        aeroportoArrivoIata:
                          type: string
                          example: "JFK"
                        timezoneArrivo:
                          type: string
                          example: "America/New_York"
                        timestampArrivo:
                          type: string
                          format: date-time
                        timestampArrivoUtc:
                          type: string
                          format: date-time
        "400":
          description: Missing `dataPartenza`.
        "404":
          description: Unknown or unsupported airline in `numeroVolo`.
        "500":
          description: Request not processable, e.g. a past departure date or non-ICAO airport codes (unstructured body).

components:

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Token obtained via `POST /sicurezza/login`. Include it in the HTTP header:
        ```
        Authorization: Bearer <token>
        ```

  schemas:

    AdesioneRequest:
      type: object
      description: |
        Payload for issuing an enrolment. Exactly one of `personaFisica`, `personaGiuridica` or
        `dittaIndividuale` must be present, matching `tipoSoggetto`.
      required:
        - numeroPolizza
        - dataEffetto
        - dataScadenza
        - tipoSoggetto
        - beneAssicurato
        - garanzie
      properties:
        numeroPolizza:
          type: string
          description: Master policy number, provided by the Overx team.
          example: "OXC0XXX"
        numeroAdesioneEsterno:
          type: string
          description: Partner-side enrolment id, unique per policy (duplicate → 409). May be omitted or empty.
          example: "ADH-2026-00123"
        dataEffetto:
          type: string
          format: date-time
          description: Coverage start. Not earlier than the master policy effective date.
        dataScadenza:
          type: string
          format: date-time
          description: Coverage end. Not earlier than `dataEffetto`.
        tacitoRinnovo:
          type: boolean
          description: Always `false` for this product.
          default: false
        source:
          type: string
          description: Origin channel. Defaults to `API`.
        tipoSoggetto:
          type: string
          enum: [PERSONA_FISICA, PERSONA_GIURIDICA, DITTA_INDIVIDUALE]
        personaFisica:
          $ref: "#/components/schemas/PersonaFisica"
        personaGiuridica:
          $ref: "#/components/schemas/PersonaGiuridica"
        dittaIndividuale:
          $ref: "#/components/schemas/DittaIndividuale"
        beneAssicurato:
          $ref: "#/components/schemas/BeneAssicurato"
        garanzie:
          type: array
          description: |
            Guarantees to activate, among those active on the policy (maximum 15 per
            enrolment). Omit the guarantees not wanted.
          minItems: 1
          maxItems: 15
          items:
            $ref: "#/components/schemas/Garanzia"

    PersonaFisica:
      type: object
      required: [codiceFiscale, nome, cognome, indirizzo]
      properties:
        codiceFiscale:
          type: string
          description: 16 characters, uppercase, consistent with first and last name.
          example: "RSSMRA85M01H501Q"
        nome:
          type: string
          maxLength: 50
        cognome:
          type: string
          maxLength: 50
        indirizzo:
          type: string
          description: |
            Must contain at least the postal code (5 digits); recommended format
            `VIA EDEN 2 - 23889 SANTA MARIA HOE (LC)`.
          example: "VIA ROMA 10 - 00100 ROMA (RM)"
        nazione:
          type: string
          description: ISO 3166-1 alpha-3.
          example: "ITA"
        numeroTelefono:
          type: string
          description: Digits only, without international prefix.
        email:
          type: string
        pec:
          type: string

    PersonaGiuridica:
      type: object
      required: [partitaIva, ragioneSociale, indirizzo]
      properties:
        partitaIva:
          type: string
          description: 11 digits.
          example: "12550970151"
        ragioneSociale:
          type: string
        indirizzo:
          type: string
          description: Same format as for `personaFisica`.
        nazione:
          type: string
        formaSocietaria:
          type: string
          example: "SPA"
        codiceAteco:
          type: string
          example: "80.10"
        numeroTelefono:
          type: string
        email:
          type: string
        pec:
          type: string

    DittaIndividuale:
      type: object
      required: [codiceFiscale, nome, cognome, indirizzo]
      properties:
        codiceFiscale:
          type: string
          description: Consistent with first and last name.
        nome:
          type: string
        cognome:
          type: string
        indirizzo:
          type: string
          description: Same format as for `personaFisica`.
        partitaIva:
          type: string
          description: Optional. If present, 11 digits (an `IT` prefix is ignored), otherwise 400.
        nazione:
          type: string
        numeroTelefono:
          type: string
        email:
          type: string
        pec:
          type: string

    BeneAssicurato:
      type: object
      required: [tipoBene, variabiliTecniche]
      properties:
        tipoBene:
          type: string
          enum: [viaggioAssicurato]
          description: Fixed value.
        variabiliTecniche:
          type: array
          minItems: 1
          description: |
            Trip variables. Send all of them (numeric ones as `0`, arrays as `[]` when not
            applicable): `prenotazione` (date-time), `destinazioneArea` (`italia` | `europa` |
            `mondo` | `usaCanada`), `destinazionePaese` (string), `dataPartenza`, `dataRientro`
            (date-time), `dataGridDatiAssicurato` (array of insured people), `numeroAssicurati`
            (number), `dataGridVoloAssicurato` (array of flights), `numeroVoloAssTot` (number),
            `indennizzoVolo` (number, euro). When at least one flight is present,
            `numeroAssicurati`, `dataGridDatiAssicurato` and `indennizzoVolo` are required too.
          items:
            $ref: "#/components/schemas/VariabileTecnica"

    VariabileTecnica:
      type: object
      required: [keyVartec, valueVartec]
      properties:
        keyVartec:
          type: string
          description: Variable key (case-sensitive).
          example: "destinazioneArea"
        valueVartec:
          description: |
            Variable value. String, number, or array of objects (`dataGridDatiAssicurato`,
            `dataGridVoloAssicurato`).
          anyOf:
            - type: string
            - type: number
            - type: array
              items:
                anyOf:
                  - $ref: "#/components/schemas/DatoAssicurato"
                  - $ref: "#/components/schemas/VoloAssicurato"

    DatoAssicurato:
      type: object
      description: Element of `dataGridDatiAssicurato`.
      required: [cognomeAssicurato, nomeAssicurato, fasciaEta]
      properties:
        cognomeAssicurato:
          type: string
        nomeAssicurato:
          type: string
        fasciaEta:
          type: string
          enum: [bassa, media, alta]
          description: "`bassa` 0-17, `media` 18-74, `alta` 75-89."
        email:
          type: string

    VoloAssicurato:
      type: object
      description: |
        Element of `dataGridVoloAssicurato`, built from an element of the flight schedule
        response with the field mapping described in the integration guide. Sending the response
        element unchanged causes the issuing to stop in `ERRORE_EMISSIONE_BLOCKCHAIN`.
      properties:
        numeroVolo:
          type: string
          example: "WMT6313"
        numeroVoloPdf:
          type: string
          example: "W46313"
        aereoportoPartenza:
          type: string
          description: Departure airport ICAO code.
          example: "LIMC"
        fusorarioPartenza:
          type: string
          example: "Europe/Rome"
        dataPartenza:
          type: string
          format: date-time
        dataPartenzaUtc:
          type: string
          format: date-time
        aereoportoArrivo:
          type: string
          description: Arrival airport ICAO code.
          example: "LEMD"
        fusorarioArrivo:
          type: string
          example: "Europe/Rome"
        dataArrivo:
          type: string
          format: date-time
        dataArrivoUtc:
          type: string
          format: date-time

    Garanzia:
      type: object
      required: [keyGaranzia, premioGaranzia]
      properties:
        keyGaranzia:
          type: string
          description: |
            Guarantee key, case-sensitive. When it does not match a guarantee active on the
            policy, `idGarOverx`, `nomeGaranzia` and `codAnagGar` come back `null` and the
            enrolment is not registered.
          enum:
            - speseMediche
            - ritardoVoloPar
            - perditaBagaglio
            - beniNecessari
            - rifacimDoc
            - assistenzaViag
            - rct
            - annullViaggio
            - interruzViaggio
            - infMorteExtra
            - InfInvaPerm
            - tutelaLegale
            - assistenzaStr
            - ritardoPart
            - rischioZero
            - rischioVolo
        idGarOverx:
          type: string
          format: uuid
          readOnly: true
          description: Calculated by REVO from `keyGaranzia` — do not send.
        nomeGaranzia:
          type: string
          readOnly: true
          description: Calculated by REVO — do not send.
        codAnagGar:
          type: string
          readOnly: true
          description: Calculated by REVO — do not send.
        ramoBilancio:
          type: string
          readOnly: true
          description: Calculated by REVO — do not send.
        variabiliTecniche:
          type: array
          description: |
            Contractual values of the guarantee (numeric `valueVartec`): `massimale`,
            `massimalePersona`, `massimaleItalia`, `massimaleEuropa`, `massimaleMondo`,
            `limiteGiorni`, `franchigia`, `scoperto`, `minimoScoperto`, `limiteNoleggio`. The
            keys applicable to each guarantee are listed in the integration guide.
          items:
            type: object
            required: [keyVartec, valueVartec]
            properties:
              keyVartec:
                type: string
                example: "massimale"
              valueVartec:
                type: number
                example: 40000
        premioGaranzia:
          $ref: "#/components/schemas/PremioGaranzia"

    PremioGaranzia:
      type: object
      description: |
        Premium of the guarantee, per enrolment (not multiplied by the number of insured
        people). `lordoAnnuo` must equal `impAnnuo` + `impAnnuo` × `tassePerc` / 100 (tolerance
        0.01, tax rounded to two decimals), otherwise 400. Without `tassePerc` and `lordoAnnuo`
        collection does not complete.
      required: [impAnnuo, tassePerc, lordoAnnuo, valuta]
      properties:
        impAnnuo:
          type: number
          description: Net premium.
          example: 10.72
        tassePerc:
          type: number
          description: Tax percentage (reference values in the integration guide).
          example: 21.25
        lordoAnnuo:
          type: number
          description: Gross premium.
          example: 13.00
        valuta:
          type: string
          description: ISO 4217 currency code.
          example: "EUR"
        impAnnuoEur:
          type: number
          description: Net premium in EUR (equal to `impAnnuo` when the currency is EUR).
        lordoAnnuoEur:
          type: number
          description: Gross premium in EUR (equal to `lordoAnnuo` when the currency is EUR).

    AdesioneResponse:
      type: object
      description: |
        Echo of the request completed with the fields calculated by REVO. Only the fields
        relevant to the integration are listed.
      properties:
        id:
          type: string
          format: uuid
          description: Internal enrolment id, used for attachments.
        numeroPolizza:
          type: string
        numeroAdesione:
          type: string
          description: Enrolment number assigned by REVO, `<numeroPolizza>-<progressivo>`.
          example: "OXC0208-000022"
        numeroAdesioneEsterno:
          type: string
        codiceProdotto:
          type: string
          example: "A001"
        stato:
          type: string
          description: "`EMESSA` — receipt confirmed; **not** the final state."
          example: "EMESSA"
        garanzie:
          type: array
          description: |
            Guarantees with `idGarOverx`, `nomeGaranzia`, `codAnagGar` and `ramoBilancio`
            completed by REVO. When these are `null` the `keyGaranzia` is not active on the
            policy and the enrolment is not registered.
          items:
            $ref: "#/components/schemas/Garanzia"

    AdesioneDetail:
      type: object
      description: |
        Enrolment detail: same data as the issuing response, with typed technical variables, plus
        the fields below.
      properties:
        id:
          type: string
          format: uuid
        numeroAdesione:
          type: string
        stato:
          type: string
          description: |
            Current state: `EMESSA` (issued, final if the policy has no collection at signing),
            `INCASSATA` (issued and collected), `ANNULLO_CON_RIMBORSO`, `ANNULLO_SENZA_EFFETTO`,
            `ERRORE_JMIL`, `ERRORE_EMISSIONE`, `ERRORE_EMISSIONE_BLOCKCHAIN`.
          example: "INCASSATA"
        dataFineAdesione:
          type: string
          format: date-time
          description: Equal to `dataScadenza`; after a storno, the date of the operation.
        idMovimento:
          type: integer
          nullable: true
          description: Issuing movement identifier, set once issuing has been performed.
        allegati:
          type: array
          items:
            $ref: "#/components/schemas/Allegato"

    StornoRequest:
      type: object
      required: [numeroAdesione, tipoMovimento]
      properties:
        numeroAdesione:
          type: array
          minItems: 1
          description: Numbers of the enrolments to cancel.
          items:
            type: string
          example: ["OXC0208-000022", "OXC0208-000023"]
        tipoMovimento:
          type: string
          enum: [ANNULLO_SENZA_EFFETTO, ANNULLO_CON_RIMBORSO]
        frazionamento:
          type: string
          description: Optional. For single payment use `ANNUALE`.
          enum: [MENSILE, BIMESTRALE, TRIMESTRALE, QUADRIMESTRALE, SEMESTRALE, ANNUALE]

    Allegato:
      type: object
      properties:
        id:
          type: string
          format: uuid
        numeroPolizza:
          type: string
        idAdesione:
          type: string
          format: uuid
        tipoAllegato:
          type: string
        urlRemoto:
          type: string
          description: Value to send as `key` to the download operation.
        originalFilename:
          type: string
        fileSize:
          type: number
        fileExt:
          type: string
          example: ".pdf"
        dataCreazione:
          type: string

    ErrorResponse:
      type: object
      properties:
        timestamp:
          type: string
        status:
          type: integer
        error:
          type: string
          example: "Bad Request"
        message:
          type: string
        path:
          type: string

    DuplicateErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: "ADESIONE_DUPLICATA"
        message:
          type: string
          example: "Il numero adesione esterno 'ADH-2026-00123' è già presente per la polizza 'OXC0208'"
        status:
          type: integer
          example: 409
