openapi: 3.0.3
info:
  title: Partner Integration API — R04x Volo Protetto
  version: 1.0.0
  description: |
    OpenAPI specification for the **R04x flight products**: **R044 — REVO Volo Protetto** (delay + cancellation),
    **R042 — REVO Flight Delay** and **R043 — REVO Flight Cancellation**, issued on a **collective policy**
    (master policy) through the OverX platform. The APIs are the same for the three products; they differ only in the
    `prodotto` code and in the guarantees sent.

    Parties of the collective policy:

    - the **contraente** of the collective policy (e.g. the intermediary);
    - the **aderente** / policyholder (a travel agency, a company insuring its employees, an individual, a parent insuring the family);
    - the **assicurati**: the people who will travel.

    ## What you need to start
    Provided by REVO: username and password for the login, the master policy number (`polizzaMadre`) and the product code.
    The premium of each guarantee is computed by the partner and sent in the request.

    ## Authentication
    All the calls except the login require a **Bearer token** in the `Authorization` header, obtained with
    `POST /sicurezza/login`. A missing header returns `403`; an invalid or expired token returns `401`.

    ## Flow
    1. `POST /sicurezza/login` → token.
    2. `POST …/mobility/flights-schedule` → find the flight and pick the leg to insure.
    3. `POST …/blockchain/flightdelay/insurance` → emission; keep `numeroAdesione`.
    4. (optional) `POST …/blockchain/collettive/annullamento/adesioni` → cancellation.

    Emission is asynchronous: the response confirms the adhesion number immediately, the certificate and the policy terms
    are e-mailed to the policyholder a few seconds later. There is no API to download the certificate.
  contact:
    name: Overx Integration Team
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://<production-url-provided-by-REVO>/api/v1
tags:
- name: Authentication
- name: Flights
  description: Flight search
- name: Adhesions
  description: Emission and cancellation
paths:
  /sicurezza/login:
    post:
      tags:
      - Authentication
      operationId: login
      summary: Login — get the Bearer token
      description: Authenticates with the credentials provided by REVO and returns the `access_token`
        to use as Bearer token. Obtain a new token when a call answers `401`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            example:
              username: <username>
              password: <password>
      responses:
        '200':
          description: Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
              example:
                access_token: <jwt_token>
  /reverse-proxy/forward/api/v{vers}/mobility/flights-schedule:
    post:
      tags:
      - Flights
      operationId: searchFlights
      summary: Search the flight to insure
      security:
      - bearerAuth: []
      description: |
        Returns the legs scheduled for the requested flight number and local departure date (or for the airport pair and date).

        - The search looks for the flight on the requested **local departure date**; codeshare duplicates are excluded.
        - A flight number can cover more than one leg on the same day without changing number (e.g. `EK210` Athens–Dubai and then onwards). In that case several records are returned: show them all and let the user pick the one with the correct destination, or send `aeroportoArrivo` to filter.
        - An empty `scheduled` array means that the number and/or the date are wrong or the flight is not in the schedule: it cannot be insured.
        - **Integration note**: do not interpret the returned JSON. Forward the selected record as-is in `datiTecnici.voliAssicurati`. Use `timestampPartenza` / `timestampArrivo` for local display. `numeroVoloPdf` is the number shown on the certificate, `numeroVolo` the one used for monitoring: they may differ.
      parameters:
      - name: vers
        in: path
        required: true
        description: Version of the API.
        schema:
          type: integer
          format: int32
          example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlightScheduleRequest'
            examples:
              ByFlightNumber:
                summary: By flight number
                value:
                  numeroVolo: EZY5182
                  dataPartenza: '2026-12-04'
              ByAirports:
                summary: By departure and arrival airport (ICAO codes)
                value:
                  dataPartenza: '2026-12-04'
                  aeroportoPartenza: LSGG
                  aeroportoArrivo: EDDB
      responses:
        '200':
          description: Flights found (possibly none).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightScheduleResponse'
              example:
                scheduled:
                - vendor:
                    ident: EZY5182
                    ident_icao: EZY5182
                    ident_iata: U25182
                    actual_ident: null
                    actual_ident_icao: null
                    actual_ident_iata: null
                    aircraft_type: A319
                    scheduled_in: '2026-12-04T08:25:00Z'
                    scheduled_out: '2026-12-04T06:40:00Z'
                    origin: LSGG
                    origin_icao: LSGG
                    origin_iata: GVA
                    origin_lid: null
                    destination: EDDB
                    destination_icao: EDDB
                    destination_iata: BER
                    destination_lid: null
                    fa_flight_id: EZY5182-1796000000-schedule-0000p
                    meal_service: 'Economy: No meal'
                    seats_cabin_business: 0
                    seats_cabin_coach: 156
                    seats_cabin_first: 0
                  numero_volo_pdf: EJU5182
                  numeroVoloPdf: EJU5182
                  numeroVolo: EZY5182
                  numero_volo_iata: U25182
                  timestampPartenza_utc: '2026-12-04T06:40:00Z'
                  timestampArrivo_utc: '2026-12-04T08:25:00Z'
                  timestampPartenzaUtc: '2026-12-04T06:40:00Z'
                  timestampArrivoUtc: '2026-12-04T08:25:00Z'
                  timestampPartenza: '2026-12-04T07:40:00+01:00'
                  timestampArrivo: '2026-12-04T09:25:00+01:00'
                  timezonePartenza: Europe/Zurich
                  timezoneArrivo: Europe/Berlin
                  timezone_partenza: Europe/Zurich
                  timezone_arrivo: Europe/Berlin
                  aeroportoPartenza: LSGG
                  aeroportoArrivo: EDDB
                  aeroportoPartenzaNome: Geneva Cointrin Int'l
                  aeroportoPartenzaIata: GVA
                  aeroportoArrivoNome: Berlin-Brandenburg
                  aeroportoArrivoIata: BER
        '400':
          description: Missing mandatory data, e.g. departure date, or airports when `numeroVolo` is absent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleError'
              example:
                detail:
                  message: Data di partenza del volo mancante.
        '401':
          description: Invalid or expired token.
        '404':
          description: Unknown airport code or unsupported airline.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleError'
              example:
                detail:
                  message: 'Errore: inserito codice aeroporto inesistente XXX'
        '422':
          description: Malformed field (e.g. flight number or date format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleValidationError'
        '500':
          description: Internal error, e.g. a search by airports only sent with IATA codes (use ICAO codes),
            or flight-data provider unreachable.
  /reverse-proxy/blockchain/flightdelay/insurance:
    post:
      tags:
      - Adhesions
      operationId: emitAdhesion
      summary: Create an adhesion (emission)
      security:
      - bearerAuth: []
      description: |
        Issues an adhesion to the collective policy. Same API for R042, R043 and R044; the product-specific data are in `datiTecnici`, a JSON **string** (see `TechnicalData`).

        Checks performed (any failure → `400`, nothing is issued):

        - `polizzaMadre` exists and is valid today; `prodotto` is the product of that master policy; `intermediario.partitaIVA` matches the one registered;
        - exactly one of `aderentePF` / `aderentePG`, with the mandatory data and an e-mail;
        - at least one guarantee consistent with the product;
        - at most 6 flights in `datiTecnici.voliAssicurati`; for R043 every flight must carry `numeroVolo` and `aeroportoArrivo`;
        - `timestampPartenza` and `timestampArrivo` parseable.

        Each guarantee × flight generates a monitored policy. Emission is asynchronous: the response returns the adhesion number at once, the certificate and the terms are then e-mailed to the policyholder.

        Store the `numeroAdesione` and include it in the monthly statement sent to the intermediary, to reconcile premiums.

        **Claim communications:** if the e-mails of all the insured are filled in, REVO can send a separate communication to each insured. If one or more are missing, the communication goes to the policyholder's e-mail.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmissionRequest'
            examples:
              R044_PF:
                summary: R044 — Individual policyholder, delay + cancellation
                value:
                  polizzaMadre: OX44444444
                  adesione: ''
                  prodotto: R044
                  contraente: Contraente Esempio S.r.l.
                  datiTecnici: '{"numeroAssicurati": 2, "voliAssicurati": [{"vendor": {"ident": "EZY5182",
                    "ident_icao": "EZY5182", "ident_iata": "U25182", "actual_ident": null, "actual_ident_icao":
                    null, "actual_ident_iata": null, "aircraft_type": "A319", "scheduled_in": "2026-12-04T08:25:00Z",
                    "scheduled_out": "2026-12-04T06:40:00Z", "origin": "LSGG", "origin_icao": "LSGG",
                    "origin_iata": "GVA", "origin_lid": null, "destination": "EDDB", "destination_icao":
                    "EDDB", "destination_iata": "BER", "destination_lid": null, "fa_flight_id": "EZY5182-1796000000-schedule-0000p",
                    "meal_service": "Economy: No meal", "seats_cabin_business": 0, "seats_cabin_coach":
                    156, "seats_cabin_first": 0}, "numero_volo_pdf": "EJU5182", "numeroVoloPdf": "EJU5182",
                    "numeroVolo": "EZY5182", "numero_volo_iata": "U25182", "timestampPartenza_utc": "2026-12-04T06:40:00Z",
                    "timestampArrivo_utc": "2026-12-04T08:25:00Z", "timestampPartenzaUtc": "2026-12-04T06:40:00Z",
                    "timestampArrivoUtc": "2026-12-04T08:25:00Z", "timestampPartenza": "2026-12-04T07:40:00+01:00",
                    "timestampArrivo": "2026-12-04T09:25:00+01:00", "timezonePartenza": "Europe/Zurich",
                    "timezoneArrivo": "Europe/Berlin", "timezone_partenza": "Europe/Zurich", "timezone_arrivo":
                    "Europe/Berlin", "aeroportoPartenza": "LSGG", "aeroportoArrivo": "EDDB", "aeroportoPartenzaNome":
                    "Geneva Cointrin Int''l", "aeroportoPartenzaIata": "GVA", "aeroportoArrivoNome": "Berlin-Brandenburg",
                    "aeroportoArrivoIata": "BER"}], "assicurati": [{"nome": "MARIO", "cognome": "ROSSI",
                    "mail": "mario.rossi@example.com"}, {"nome": "ANNA", "cognome": "VERDI", "mail": "anna.verdi@example.com"}],
                    "codiceEmissionePartner": "PRT-157642678"}'
                  aderentePF: &id003
                    nome: MARIO
                    cognome: ROSSI
                    codiceFiscale: RSSMRA80A01F205X
                    mail: mario.rossi@example.com
                    telefono: '+393331234567'
                    indirizzo: &id001
                      indirizzo: Via Roma 1
                      comune: Milano
                      cap: '20121'
                      provincia: MI
                      nazione: Italia
                  intermediario: &id002
                    denominazioneSociale: Intermediario Esempio S.r.l.
                    codiceFiscale: 01234567890
                    partitaIVA: 01234567890
                    mail: intermediario@example.com
                  premio:
                    idQuotazione: ''
                    garanzie:
                    - id: ''
                      keyGaranzia: ritardoVoloPar
                      descrizione: Ritardo Volo
                      lordo: 12.13
                      netto: 10.0
                      imposte: 2.13
                    - id: ''
                      keyGaranzia: cancellazioneVoloPar
                      descrizione: Cancellazione Volo
                      lordo: 24.25
                      netto: 20.0
                      imposte: 4.25
                    lordo: 36.38
                    netto: 30.0
                    imposte: 6.38
              R044_PG:
                summary: R044 — Legal-entity policyholder
                value:
                  polizzaMadre: OX44444444
                  adesione: ''
                  prodotto: R044
                  contraente: Contraente Esempio S.r.l.
                  datiTecnici: '{"numeroAssicurati": 2, "voliAssicurati": [{"vendor": {"ident": "EZY5182",
                    "ident_icao": "EZY5182", "ident_iata": "U25182", "actual_ident": null, "actual_ident_icao":
                    null, "actual_ident_iata": null, "aircraft_type": "A319", "scheduled_in": "2026-12-04T08:25:00Z",
                    "scheduled_out": "2026-12-04T06:40:00Z", "origin": "LSGG", "origin_icao": "LSGG",
                    "origin_iata": "GVA", "origin_lid": null, "destination": "EDDB", "destination_icao":
                    "EDDB", "destination_iata": "BER", "destination_lid": null, "fa_flight_id": "EZY5182-1796000000-schedule-0000p",
                    "meal_service": "Economy: No meal", "seats_cabin_business": 0, "seats_cabin_coach":
                    156, "seats_cabin_first": 0}, "numero_volo_pdf": "EJU5182", "numeroVoloPdf": "EJU5182",
                    "numeroVolo": "EZY5182", "numero_volo_iata": "U25182", "timestampPartenza_utc": "2026-12-04T06:40:00Z",
                    "timestampArrivo_utc": "2026-12-04T08:25:00Z", "timestampPartenzaUtc": "2026-12-04T06:40:00Z",
                    "timestampArrivoUtc": "2026-12-04T08:25:00Z", "timestampPartenza": "2026-12-04T07:40:00+01:00",
                    "timestampArrivo": "2026-12-04T09:25:00+01:00", "timezonePartenza": "Europe/Zurich",
                    "timezoneArrivo": "Europe/Berlin", "timezone_partenza": "Europe/Zurich", "timezone_arrivo":
                    "Europe/Berlin", "aeroportoPartenza": "LSGG", "aeroportoArrivo": "EDDB", "aeroportoPartenzaNome":
                    "Geneva Cointrin Int''l", "aeroportoPartenzaIata": "GVA", "aeroportoArrivoNome": "Berlin-Brandenburg",
                    "aeroportoArrivoIata": "BER"}], "assicurati": [{"nome": "MARIO", "cognome": "ROSSI",
                    "mail": "mario.rossi@example.com"}, {"nome": "ANNA", "cognome": "VERDI", "mail": "anna.verdi@example.com"}],
                    "codiceEmissionePartner": "PRT-157642678"}'
                  aderentePG:
                    denominazioneSociale: Agenzia Viaggi Esempio S.r.l.
                    codiceFiscale: ''
                    partitaIVA: 09876543210
                    mail: agenzia@example.com
                    telefono: ''
                    indirizzo: *id001
                  intermediario: *id002
                  premio:
                    idQuotazione: ''
                    garanzie:
                    - id: ''
                      keyGaranzia: ritardoVoloPar
                      descrizione: Ritardo Volo
                      lordo: 12.13
                      netto: 10.0
                      imposte: 2.13
                    - id: ''
                      keyGaranzia: cancellazioneVoloPar
                      descrizione: Cancellazione Volo
                      lordo: 24.25
                      netto: 20.0
                      imposte: 4.25
                    lordo: 36.38
                    netto: 30.0
                    imposte: 6.38
              R044_DI:
                summary: R044 — Sole proprietorship (ditta individuale), delay only
                value:
                  polizzaMadre: OX44444444
                  adesione: ''
                  prodotto: R044
                  contraente: Contraente Esempio S.r.l.
                  datiTecnici: '{"numeroAssicurati": 1, "voliAssicurati": [{"vendor": {"ident": "EZY5182",
                    "ident_icao": "EZY5182", "ident_iata": "U25182", "actual_ident": null, "actual_ident_icao":
                    null, "actual_ident_iata": null, "aircraft_type": "A319", "scheduled_in": "2026-12-04T08:25:00Z",
                    "scheduled_out": "2026-12-04T06:40:00Z", "origin": "LSGG", "origin_icao": "LSGG",
                    "origin_iata": "GVA", "origin_lid": null, "destination": "EDDB", "destination_icao":
                    "EDDB", "destination_iata": "BER", "destination_lid": null, "fa_flight_id": "EZY5182-1796000000-schedule-0000p",
                    "meal_service": "Economy: No meal", "seats_cabin_business": 0, "seats_cabin_coach":
                    156, "seats_cabin_first": 0}, "numero_volo_pdf": "EJU5182", "numeroVoloPdf": "EJU5182",
                    "numeroVolo": "EZY5182", "numero_volo_iata": "U25182", "timestampPartenza_utc": "2026-12-04T06:40:00Z",
                    "timestampArrivo_utc": "2026-12-04T08:25:00Z", "timestampPartenzaUtc": "2026-12-04T06:40:00Z",
                    "timestampArrivoUtc": "2026-12-04T08:25:00Z", "timestampPartenza": "2026-12-04T07:40:00+01:00",
                    "timestampArrivo": "2026-12-04T09:25:00+01:00", "timezonePartenza": "Europe/Zurich",
                    "timezoneArrivo": "Europe/Berlin", "timezone_partenza": "Europe/Zurich", "timezone_arrivo":
                    "Europe/Berlin", "aeroportoPartenza": "LSGG", "aeroportoArrivo": "EDDB", "aeroportoPartenzaNome":
                    "Geneva Cointrin Int''l", "aeroportoPartenzaIata": "GVA", "aeroportoArrivoNome": "Berlin-Brandenburg",
                    "aeroportoArrivoIata": "BER"}], "assicurati": [{"nome": "MARIO", "cognome": "ROSSI",
                    "mail": "mario.rossi@example.com"}], "codiceEmissionePartner": "PRT-157642678"}'
                  aderentePG:
                    denominazioneSociale: Rossi Mario Ditta Individuale
                    codiceFiscale: ''
                    partitaIVA: '05555555550'
                    mail: agenzia@example.com
                    telefono: ''
                    indirizzo: *id001
                  intermediario: *id002
                  premio:
                    idQuotazione: ''
                    garanzie:
                    - id: ''
                      keyGaranzia: ritardoVoloPar
                      descrizione: Ritardo Volo
                      lordo: 12.13
                      netto: 10.0
                      imposte: 2.13
                    lordo: 12.13
                    netto: 10.0
                    imposte: 2.13
              R042_PF:
                summary: R042 — Individual policyholder
                value:
                  polizzaMadre: OX42222222
                  adesione: ''
                  prodotto: R042
                  contraente: Contraente Esempio S.r.l.
                  datiTecnici: '{"numeroAssicurati": 2, "voliAssicurati": [{"vendor": {"ident": "EZY5182",
                    "ident_icao": "EZY5182", "ident_iata": "U25182", "actual_ident": null, "actual_ident_icao":
                    null, "actual_ident_iata": null, "aircraft_type": "A319", "scheduled_in": "2026-12-04T08:25:00Z",
                    "scheduled_out": "2026-12-04T06:40:00Z", "origin": "LSGG", "origin_icao": "LSGG",
                    "origin_iata": "GVA", "origin_lid": null, "destination": "EDDB", "destination_icao":
                    "EDDB", "destination_iata": "BER", "destination_lid": null, "fa_flight_id": "EZY5182-1796000000-schedule-0000p",
                    "meal_service": "Economy: No meal", "seats_cabin_business": 0, "seats_cabin_coach":
                    156, "seats_cabin_first": 0}, "numero_volo_pdf": "EJU5182", "numeroVoloPdf": "EJU5182",
                    "numeroVolo": "EZY5182", "numero_volo_iata": "U25182", "timestampPartenza_utc": "2026-12-04T06:40:00Z",
                    "timestampArrivo_utc": "2026-12-04T08:25:00Z", "timestampPartenzaUtc": "2026-12-04T06:40:00Z",
                    "timestampArrivoUtc": "2026-12-04T08:25:00Z", "timestampPartenza": "2026-12-04T07:40:00+01:00",
                    "timestampArrivo": "2026-12-04T09:25:00+01:00", "timezonePartenza": "Europe/Zurich",
                    "timezoneArrivo": "Europe/Berlin", "timezone_partenza": "Europe/Zurich", "timezone_arrivo":
                    "Europe/Berlin", "aeroportoPartenza": "LSGG", "aeroportoArrivo": "EDDB", "aeroportoPartenzaNome":
                    "Geneva Cointrin Int''l", "aeroportoPartenzaIata": "GVA", "aeroportoArrivoNome": "Berlin-Brandenburg",
                    "aeroportoArrivoIata": "BER"}], "assicurati": [{"nome": "MARIO", "cognome": "ROSSI",
                    "mail": "mario.rossi@example.com"}, {"nome": "ANNA", "cognome": "VERDI", "mail": "anna.verdi@example.com"}],
                    "codiceEmissionePartner": "PRT-157642678"}'
                  aderentePF: *id003
                  intermediario: *id002
                  premio:
                    idQuotazione: ''
                    garanzie:
                    - id: ''
                      keyGaranzia: ritardoVoloPar
                      descrizione: Ritardo Volo
                      lordo: 2.99
                      netto: 2.46
                      imposte: 0.53
                    lordo: 2.99
                    netto: 2.46
                    imposte: 0.53
              R043_PF:
                summary: R043 — Individual policyholder
                value:
                  polizzaMadre: OX43333333
                  adesione: ''
                  prodotto: R043
                  contraente: Contraente Esempio S.r.l.
                  datiTecnici: '{"numeroAssicurati": 2, "voliAssicurati": [{"vendor": {"ident": "EZY5182",
                    "ident_icao": "EZY5182", "ident_iata": "U25182", "actual_ident": null, "actual_ident_icao":
                    null, "actual_ident_iata": null, "aircraft_type": "A319", "scheduled_in": "2026-12-04T08:25:00Z",
                    "scheduled_out": "2026-12-04T06:40:00Z", "origin": "LSGG", "origin_icao": "LSGG",
                    "origin_iata": "GVA", "origin_lid": null, "destination": "EDDB", "destination_icao":
                    "EDDB", "destination_iata": "BER", "destination_lid": null, "fa_flight_id": "EZY5182-1796000000-schedule-0000p",
                    "meal_service": "Economy: No meal", "seats_cabin_business": 0, "seats_cabin_coach":
                    156, "seats_cabin_first": 0}, "numero_volo_pdf": "EJU5182", "numeroVoloPdf": "EJU5182",
                    "numeroVolo": "EZY5182", "numero_volo_iata": "U25182", "timestampPartenza_utc": "2026-12-04T06:40:00Z",
                    "timestampArrivo_utc": "2026-12-04T08:25:00Z", "timestampPartenzaUtc": "2026-12-04T06:40:00Z",
                    "timestampArrivoUtc": "2026-12-04T08:25:00Z", "timestampPartenza": "2026-12-04T07:40:00+01:00",
                    "timestampArrivo": "2026-12-04T09:25:00+01:00", "timezonePartenza": "Europe/Zurich",
                    "timezoneArrivo": "Europe/Berlin", "timezone_partenza": "Europe/Zurich", "timezone_arrivo":
                    "Europe/Berlin", "aeroportoPartenza": "LSGG", "aeroportoArrivo": "EDDB", "aeroportoPartenzaNome":
                    "Geneva Cointrin Int''l", "aeroportoPartenzaIata": "GVA", "aeroportoArrivoNome": "Berlin-Brandenburg",
                    "aeroportoArrivoIata": "BER"}], "assicurati": [{"nome": "MARIO", "cognome": "ROSSI",
                    "mail": "mario.rossi@example.com"}, {"nome": "ANNA", "cognome": "VERDI", "mail": "anna.verdi@example.com"}],
                    "codiceEmissionePartner": "PRT-157642678"}'
                  aderentePF: *id003
                  intermediario: *id002
                  premio:
                    idQuotazione: ''
                    garanzie:
                    - id: ''
                      keyGaranzia: cancellazioneVoloPar
                      descrizione: Cancellazione Volo
                      lordo: 11.75
                      netto: 9.69
                      imposte: 2.06
                    lordo: 11.75
                    netto: 9.69
                    imposte: 2.06
      responses:
        '201':
          description: Adhesion accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmissionResponse'
              example:
                numeroAdesione: OX44444444-000000012
                emissione: 1796000000
        '400':
          description: 'Rejected. `code`: `E001` too many flights; `E002` validation of the request; `E003`
            master policy / intermediary / product not valid. Other errors (e.g. unreadable `datiTecnici`
            or timestamps) have no code.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmissionError'
              example:
                message: '`polizzaMadre` is not valid'
                code: E003
        '401':
          description: Invalid or expired token.
        '403':
          description: Missing token.
  /reverse-proxy/blockchain/collettive/annullamento/adesioni:
    post:
      tags:
      - Adhesions
      operationId: cancelAdhesion
      summary: Cancel an adhesion
      security:
      - bearerAuth: []
      description: |
        Cancels an adhesion of the collective policy. The adhesion is deactivated and flagged for the refund of the premium.

        - The call must be made with the credentials of the intermediary registered on the master policy.
        - For R042/R043/R044 cancellation is possible **until the departure day of the first flight of the adhesion (included)**; afterwards it is refused (`E003`). To cancel afterwards, open a ticket to the REVO AM team through the dedicated portal.
        - The cancellation date is the day of the call.
        - Cancelling an adhesion that is already cancelled is refused (`E004`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancellationRequest'
            example:
              numeroPolizzaMadre: OX44444444
              numeroAdesione: OX44444444-000000012
      responses:
        '200':
          description: Adhesion cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationResponse'
              example:
                policy_number: OX44444444-000000012
        '400':
          description: Adhesion not active (`E004`), concurrent modification (`E006`) or technical error
            (`E005`, …).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationError'
              example:
                errorMessage: l'adesione non è attiva
                errorCode: E004
        '401':
          description: 'Refused (`E003`): adhesion not belonging to the master policy, intermediary not
            authorised, or cancellation after the departure day. A `401` without body means an invalid
            token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationError'
              example:
                errorMessage: impossibile annullare la polizza dopo inizio copertura
                errorCode: E003
        '403':
          description: Missing token.
        '404':
          description: Invalid request, master policy or adhesion not found (`E002`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationError'
              example:
                errorMessage: adesione non trovata
                errorCode: E002
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    LoginRequest:
      type: object
      required:
      - username
      - password
      properties:
        username:
          type: string
          description: Username provided by REVO.
        password:
          type: string
          description: Password provided by REVO.
          format: password
    LoginResponse:
      type: object
      properties:
        access_token:
          type: string
          description: 'JWT to send as `Authorization: Bearer <access_token>` on all the other calls.'
    FlightScheduleRequest:
      type: object
      description: |
        Search criteria. Two valid combinations:

        - `numeroVolo` + `dataPartenza`; `aeroportoPartenza` / `aeroportoArrivo` are optional filters (use `aeroportoArrivo` to pick one leg of a multi-leg flight number);
        - without `numeroVolo`: `dataPartenza` + **both** `aeroportoPartenza` and `aeroportoArrivo`.
      properties:
        numeroVolo:
          type: string
          description: Flight number shown on the ticket (IATA or ICAO designator), uppercase, e.g. `AZ610`,
            `EZY5182`. Format `[A-Z]{1,3}` followed by 1-4 digits. The prefix `EJU` is normalised to `U2`.
          example: EZY5182
        dataPartenza:
          type: string
          description: Local departure date, `YYYY-MM-DD`. Always required.
          format: date
          example: '2026-12-04'
        aeroportoPartenza:
          type: string
          description: 'Departure airport. With `numeroVolo`: IATA (3 letters) or ICAO (4 letters) code.
            Without `numeroVolo` (search by airports only): **ICAO code (4 letters) only**, IATA codes
            make the call fail with `500`. Must exist in the airport registry.'
          minLength: 3
          maxLength: 5
          example: LSGG
        aeroportoArrivo:
          type: string
          description: 'Arrival airport. With `numeroVolo`: IATA (3 letters) or ICAO (4 letters) code.
            Without `numeroVolo` (search by airports only): **ICAO code (4 letters) only**, IATA codes
            make the call fail with `500`. Must exist in the airport registry.'
          minLength: 3
          maxLength: 5
          example: EDDB
    ScheduledFlight:
      type: object
      description: |
        One leg found for the search. **Do not read or alter it**: the selected element must be copied as-is into
        `datiTecnici.voliAssicurati` of the emission request (see `InsuredFlight`).
      properties:
        vendor:
          type: object
          description: Raw schedule data from the flight-data provider. Informative; forwarded unchanged.
          additionalProperties: true
        numeroVolo:
          type: string
          description: Flight identifier used by REVO to monitor the flight (may differ from the number
            on the ticket because of IATA/ICAO conversion or codeshare).
          example: EZY5182
        numeroVoloPdf:
          type: string
          description: 'Flight number as requested/shown on the ticket and on the certificate. Null when
            the search is by airports only: the certificate then shows `numeroVolo`.'
          nullable: true
          example: EJU5182
        numero_volo_pdf:
          type: string
          description: Same value as `numeroVoloPdf` (snake_case twin, the one read at emission).
          nullable: true
          example: EJU5182
        numero_volo_iata:
          type: string
          example: U25182
        timestampPartenza:
          type: string
          description: Scheduled departure, airport local time with UTC offset (ISO 8601). Use for display.
          format: date-time
          example: '2026-12-04T07:40:00+01:00'
        timestampArrivo:
          type: string
          description: Scheduled arrival, airport local time with UTC offset (ISO 8601). Use for display.
          format: date-time
          example: '2026-12-04T09:25:00+01:00'
        timestampPartenza_utc:
          type: string
          description: Scheduled departure in UTC.
          example: '2026-12-04T06:40:00Z'
        timestampArrivo_utc:
          type: string
          description: Scheduled arrival in UTC.
          example: '2026-12-04T08:25:00Z'
        timestampPartenzaUtc:
          type: string
          example: '2026-12-04T06:40:00Z'
        timestampArrivoUtc:
          type: string
          example: '2026-12-04T08:25:00Z'
        timezonePartenza:
          type: string
          description: IANA time zone of the departure airport.
          example: Europe/Zurich
        timezoneArrivo:
          type: string
          description: IANA time zone of the arrival airport.
          example: Europe/Berlin
        timezone_partenza:
          type: string
          example: Europe/Zurich
        timezone_arrivo:
          type: string
          example: Europe/Berlin
        aeroportoPartenza:
          type: string
          description: Departure airport (ICAO).
          example: LSGG
        aeroportoArrivo:
          type: string
          description: Arrival airport (ICAO).
          example: EDDB
        aeroportoPartenzaNome:
          type: string
          example: Geneva Cointrin Int'l
        aeroportoPartenzaIata:
          type: string
          example: GVA
        aeroportoArrivoNome:
          type: string
          example: Berlin-Brandenburg
        aeroportoArrivoIata:
          type: string
          example: BER
    FlightScheduleResponse:
      type: object
      properties:
        scheduled:
          type: array
          description: One element per leg found. Empty if nothing matches the number/date/airports.
          items:
            $ref: '#/components/schemas/ScheduledFlight'
    Address:
      type: object
      properties:
        indirizzo:
          type: string
        comune:
          type: string
        cap:
          type: string
        provincia:
          type: string
        nazione:
          type: string
    Intermediary:
      type: object
      required:
      - denominazioneSociale
      - partitaIVA
      description: |
        The intermediary registered by REVO on the master policy. `partitaIVA` must match the registered one,
        otherwise the request is rejected (`E003`). If `mail` (and/or a complete `indirizzo`) is sent, it replaces the registered one
        in the documents generated for this adhesion.
      properties:
        denominazioneSociale:
          type: string
          description: Business name. Required.
        codiceFiscale:
          type: string
        partitaIVA:
          type: string
          description: VAT number. Required; must match the master policy.
        mail:
          type: string
          format: email
        pec:
          type: string
        telefono:
          type: string
        fax:
          type: string
        indirizzo:
          $ref: '#/components/schemas/Address'
    PolicyholderPerson:
      type: object
      required:
      - nome
      - cognome
      - mail
      description: 'Individual policyholder (persona fisica). Alternative to `aderentePG`: send exactly
        one of the two.'
      properties:
        nome:
          type: string
        cognome:
          type: string
        codiceFiscale:
          type: string
        mail:
          type: string
          description: Required. Receives the certificate and the policy terms.
          format: email
        dataDiNascita:
          type: string
        telefono:
          type: string
        indirizzo:
          $ref: '#/components/schemas/Address'
    PolicyholderCompany:
      type: object
      required:
      - denominazioneSociale
      - mail
      description: |
        Legal-entity policyholder (persona giuridica), also used for sole proprietorships (ditta individuale).
        At least one of `codiceFiscale` and `partitaIVA` is required. Alternative to `aderentePF`: send exactly one of the two.
      properties:
        denominazioneSociale:
          type: string
        codiceFiscale:
          type: string
        partitaIVA:
          type: string
        mail:
          type: string
          description: Required. Receives the certificate and the policy terms.
          format: email
        telefono:
          type: string
        indirizzo:
          $ref: '#/components/schemas/Address'
    GuaranteePremium:
      type: object
      required:
      - keyGaranzia
      - lordo
      properties:
        id:
          type: string
          description: Leave empty.
        keyGaranzia:
          type: string
          description: Guarantee key (case-sensitive).
          enum:
          - ritardoVoloPar
          - cancellazioneVoloPar
        descrizione:
          type: string
          description: Free text.
        lordo:
          type: number
          description: Gross premium of the guarantee.
          format: double
        netto:
          type: number
          description: 'Net premium of the guarantee. Recorded on the policy: always send it.'
          format: double
        imposte:
          type: number
          description: 'Taxes of the guarantee. Recorded on the policy: always send it.'
          format: double
    Premium:
      type: object
      required:
      - garanzie
      - lordo
      - netto
      - imposte
      description: Premium computed by the partner's tariff engine. REVO records the amounts as received
        and does not recompute them.
      properties:
        idQuotazione:
          type: string
          description: Leave empty.
        garanzie:
          type: array
          minItems: 1
          description: |
            Guarantees purchased. Accepted keys by product: `R042` → `ritardoVoloPar`; `R043` → `cancellazioneVoloPar`;
            `R044` → `ritardoVoloPar` and/or `cancellazioneVoloPar`. Send only the guarantees of the product.
          items:
            $ref: '#/components/schemas/GuaranteePremium'
        lordo:
          type: number
          description: Total gross premium (sum of the guarantees). Must be greater than 0.
          format: double
        netto:
          type: number
          description: Total net premium = `lordo` − `imposte`.
          format: double
        imposte:
          type: number
          description: Total taxes.
          format: double
    InsuredFlight:
      type: object
      required:
      - numeroVolo
      - timestampPartenza
      - timestampArrivo
      - aeroportoArrivo
      description: |
        The element chosen from `scheduled` in the flight-search response, copied **unchanged** (all its fields, including `vendor`).
        The fields below are the ones REVO reads; any other field is kept but ignored.
      properties:
        numeroVolo:
          type: string
          description: Identifier used for monitoring.
        numero_volo_pdf:
          type: string
          description: Number shown on the certificate (falls back to `numeroVolo` if missing).
        timestampPartenza:
          type: string
          description: Local departure, ISO 8601 with offset.
          format: date-time
        timestampArrivo:
          type: string
          description: Local arrival, ISO 8601 with offset. Must be parseable.
          format: date-time
        aeroportoArrivo:
          type: string
          description: Arrival airport. Together with number and date it identifies the monitored flight.
        aeroportoArrivoNome:
          type: string
        aeroportoArrivoIata:
          type: string
        vendor:
          type: object
          additionalProperties: true
      additionalProperties: true
    Insured:
      type: object
      required:
      - nome
      - cognome
      properties:
        nome:
          type: string
        cognome:
          type: string
        mail:
          type: string
          description: Optional. See the note on claim communications in the emission operation.
          format: email
    TechnicalData:
      type: object
      required:
      - numeroAssicurati
      - voliAssicurati
      description: |
        Content of `datiTecnici`. **It must be sent as a JSON string** (the object serialised to text), not as a nested object.
      properties:
        numeroAssicurati:
          type: integer
          description: Total number of insured people.
        voliAssicurati:
          type: array
          maxItems: 6
          description: Flights chosen by the user (e.g. outbound and return), at most 6. Each element
            is a record from the flight search, unchanged. Not to be confused with all the legs returned
            by the search.
          items:
            $ref: '#/components/schemas/InsuredFlight'
        assicurati:
          type: array
          description: Insured people. If all the e-mails are filled in, REVO can send the claim communications
            to each insured; if one or more are missing, they go to the policyholder's e-mail. Avoid mixed
            configurations.
          items:
            $ref: '#/components/schemas/Insured'
        codiceEmissionePartner:
          type: string
          description: Optional free reference of the partner (e.g. booking code). Stored with the request;
            not interpreted and not returned by the APIs.
        indennizzo:
          type: number
          description: 'Ignored: the indemnity amount is defined by REVO on the master policy.'
    EmissionRequest:
      type: object
      required:
      - polizzaMadre
      - prodotto
      - datiTecnici
      - premio
      - intermediario
      description: Same structure for R042, R043 and R044. Exactly one of `aderentePF` / `aderentePG`.
      properties:
        polizzaMadre:
          type: string
          description: Master policy number provided by REVO, e.g. `OX44444444`. It must be valid today.
        prodotto:
          type: string
          description: Product code; must be the product of the master policy.
          enum:
          - R042
          - R043
          - R044
        contraente:
          type: string
          description: Business name of the collective policyholder, as agreed with REVO.
        intermediario:
          $ref: '#/components/schemas/Intermediary'
        aderentePF:
          $ref: '#/components/schemas/PolicyholderPerson'
        aderentePG:
          $ref: '#/components/schemas/PolicyholderCompany'
        datiTecnici:
          type: string
          description: '`TechnicalData` serialised as a JSON string. See the `TechnicalData` schema.'
        premio:
          $ref: '#/components/schemas/Premium'
        adesione:
          type: string
          description: 'Leave empty: the adhesion number is generated by REVO.'
    EmissionResponse:
      type: object
      properties:
        numeroAdesione:
          type: string
          description: 'Adhesion number, `<polizzaMadre>-<9 digits>`. Store it: it is needed to cancel
            the adhesion and for reconciliation.'
          example: OX44444444-000000012
        emissione:
          type: integer
          description: Emission timestamp, Unix epoch in seconds.
          format: int64
          example: 1796000000
    CancellationRequest:
      type: object
      required:
      - numeroPolizzaMadre
      - numeroAdesione
      properties:
        numeroPolizzaMadre:
          type: string
          description: Master policy of the adhesion. The adhesion number must start with it.
          example: OX44444444
        numeroAdesione:
          type: string
          example: OX44444444-000000012
    CancellationResponse:
      type: object
      properties:
        policy_number:
          type: string
          description: The cancelled adhesion.
          example: OX44444444-000000012
    EmissionError:
      type: object
      properties:
        message:
          type: string
          description: Reason.
        code:
          type: string
          description: 'Present for the main errors: `E001`, `E002`, `E003`.'
    CancellationError:
      type: object
      properties:
        errorMessage:
          type: string
          description: Reason.
        errorCode:
          type: string
          description: '`E002`, `E003`, `E004`, …'
    ScheduleError:
      type: object
      properties:
        detail:
          type: object
          properties:
            message:
              type: string
    ScheduleValidationError:
      type: object
      properties:
        errors:
          type: string
          description: 'Field-level reasons, e.g. `numeroVolo: String should match pattern …`.'
