openapi: 3.0.3
info:
  title: Partner Integration API — Fotovoltaico (PARC) — Index monitoring
  version: 1.0.0
  description: |
    OpenAPI specification of the **index monitoring API** of the parametric collective product **Fotovoltaico**.

    For each adhesion it returns the **daily solar irradiation** observed during the coverage period, so that
    the partner can monitor the index of its customers.

    ## What you need to start
    Provided by REVO: username and password for the login and the **intermediary code** (`codice_intermediario`)
    of the collective policy. The adhesion number (`numeroAdesione`) is returned by the emission flow
    (column `numero_adesione` of the output file).

    ## Authentication
    The call requires a **Bearer token** in the `Authorization` header, obtained with `POST /sicurezza/login`.
    The token expires after **2400 seconds (40 minutes)**: obtain a new one when the call answers `401`.
    A missing `Authorization` header returns `403` without body; a malformed or expired token returns `401`.

    ## Index returned

    | `TitoloPopup` | Index (`headers.indice`) | Time format |
    |---|---|---|
    | `Irraggiamento` | `Irraggiamento (GHI)` | `00:00` / `23:59` |

    The list contains **one element per day for which an index is available**, within the coverage period and up
    to the current date. Days without an available index are not returned, so the list can have gaps and can be
    empty. For adhesions with a multi-year coverage only the days of the first annual period are returned. The `highlight` field is used by the user interface to highlight the hours covered by the guarantee in the products with an hourly index; these products have a daily index, so it is always `0`.
  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: Monitoring
  description: Daily index of an adhesion
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
        (valid 2400 seconds).
      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>
                token_type: Bearer
                expires_in: 2400
                refresh_token: <refresh_token>
                refresh_expires_in: 28799
        '400':
          description: Wrong credentials, unknown user, missing `username` or empty values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginError'
              example:
                status: 5400
                message: Wrong login access
                error: WrongRequest
        '403':
          description: Empty body or body without the `password` field; no response body.
  /reverse-proxy/blockchain/collettive/adesione/oracolo:
    get:
      tags:
      - Monitoring
      operationId: getAdhesionIndex
      summary: Daily index of an adhesion
      description: |
        Returns the daily index values of the adhesion `adesione`, from the coverage start date to the current date
        (or to the end of the coverage). The adhesion must belong to the collective policy of the intermediary
        identified by `codice_intermediario`.

        The `data` parameter used by other products is **ignored** for Bolletta Protetta and Fotovoltaico.
      security:
      - bearerAuth: []
      parameters:
      - name: adesione
        in: query
        required: true
        description: Adhesion number, as returned by the emission flow (e.g. `E0000010455-000001242`). Case-sensitive, no
          spaces. An adhesion that has been cancelled is still returned.
        schema:
          type: string
        example: E0000010455-000001242
      - name: codice_intermediario
        in: query
        required: true
        description: Intermediary code of the collective policy, provided by REVO. It must match exactly (leading zeros included,
          `0539` is not `539`) the one of the policy the adhesion belongs to.
        schema:
          type: string
        example: '300'
      - name: data
        in: query
        required: false
        description: Not used by these products (ignored).
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Daily index values. `dettaglio` is `null` when no value is available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdhesionIndex'
              examples:
                fotovoltaico:
                  summary: Fotovoltaico
                  value:
                    idEvento: <event-id>
                    TitoloPopup: Irraggiamento
                    InfoGeneriche: Irraggiamento giornaliero da 01/06/2026 a 31/05/2027
                    headers:
                      data: Data
                      oraInizio: Ora Inizio
                      oraFine: Ora Fine
                      indice: Irraggiamento (GHI)
                    dettaglio:
                    - data: 01/06/2026
                      oraInizio: 00:00
                      oraFine: '23:59'
                      indice: 8234
                      highlight: 0
                    - data: 02/06/2026
                      oraInizio: 00:00
                      oraFine: '23:59'
                      indice: 8256
                      highlight: 0
        '400':
          description: '`codice_intermediario` missing (the text of the first message contains a typo that is part of the
            service response) or not matching the collective policy of the adhesion.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing:
                  value:
                    message: '''codiceIntermediaro'' non valido'
                mismatch:
                  value:
                    message: codice intermediario non valido
        '401':
          description: Malformed, invalid or expired token. Repeat the login.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '403':
          description: Missing `Authorization` header (no response body).
        '404':
          description: Adhesion not found (or `adesione` missing).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: adesione non trovata
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    LoginRequest:
      type: object
      required:
      - username
      - password
      properties:
        username:
          type: string
        password:
          type: string
          format: password
    LoginResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT to send as `Authorization&#58; Bearer <access_token>`.
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Validity of the access token, in seconds.
          example: 2400
        refresh_token:
          type: string
        refresh_expires_in:
          type: integer
          description: Validity of the refresh token, in seconds.
          example: 28799
    LoginError:
      type: object
      properties:
        status:
          type: integer
          example: 5400
        message:
          type: string
          example: Wrong login access
        error:
          type: string
          example: WrongRequest
    AdhesionIndex:
      type: object
      properties:
        idEvento:
          type: string
          description: Identifier of the monitored event (index source).
        TitoloPopup:
          type: string
          description: Title of the index (`Irraggiamento`).
        InfoGeneriche:
          type: string
          description: Description of the monitored period (`dd/MM/yyyy`).
        headers:
          type: object
          properties:
            data:
              type: string
            oraInizio:
              type: string
            oraFine:
              type: string
            indice:
              type: string
              description: Name and unit of the index.
        dettaglio:
          type: array
          nullable: true
          description: One element per day with an available index, in date order. `null` when there are no values.
          items:
            $ref: '#/components/schemas/IndexValue'
    IndexValue:
      type: object
      properties:
        data:
          type: string
          description: Day, format `dd/MM/yyyy`.
          example: 01/06/2026
        oraInizio:
          type: string
          description: Start of the observation (`00:00`).
        oraFine:
          type: string
          description: End of the observation (`23:59`).
        indice:
          type: number
          description: Daily global horizontal irradiation (GHI) of the day.
        highlight:
          type: integer
          description: Flag used by the user interface to highlight the hours covered by the guarantee (products with an hourly
            index). Always `0` for these products, whose index is daily.
          example: 0
    Error:
      type: object
      properties:
        message:
          type: string
    AuthError:
      type: object
      properties:
        error:
          type: string
          example: unauthorized
        error_description:
          type: string
        path:
          type: string
