swagger: '2.0'
info:
  title: Clevergy connect-api
  description: Connect enables Clevergy customers to build integrations with the Clevergy platform. To request access please write to info@clever.gy.
  version: 1.0.0
host: connect.clever.gy
x-google-endpoints:
  - name: connect.clever.gy
    allowCors: true
schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: 'https://public-front-back-tl56gypzra-ew.a.run.app'
security:
  - firebase: []
securityDefinitions:
  firebase:
    authorizationUrl: ''
    flow: implicit
    type: oauth2
    x-google-issuer: public-front-back@clevergy.iam.gserviceaccount.com
    x-google-jwks_uri: 'https://www.googleapis.com/robot/v1/metadata/x509/public-front-back@clevergy.iam.gserviceaccount.com'
    x-google-audiences: 'https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit'
  key:
    type: apiKey
    in: header
    name: clevergy-api-key
paths:
  '/auth/{userId}/token':
    get:
      summary: Get user access token
      description: |
        Returns user jwt based on the email. The jwt can be used in some endpoints
        of the API to obtain energy data from the user.
      tags:
        - Access control
      operationId: retrieveUserAccessToken
      parameters:
        - name: userId
          in: path
          description: Clevergy ID from the user (also available with email)
          required: true
          type: string
      responses:
        '200':
          description: User jwt
          schema:
            $ref: '#/definitions/AuthUser'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  /users:
    get:
      summary: Get users
      description: |
        Returns a paginated list of users filtered by a given criteria. If no filter
        parameter is included (nif, email), all the tenant users shall be returned.
      tags:
        - Users
      operationId: getUsers
      parameters:
        - name: page
          in: query
          description: Number of the page starting at 1
          required: false
          type: integer
          format: int32
        - name: size
          in: query
          description: Size of the page
          required: false
          type: integer
          format: int32
        - name: sort
          in: query
          description: Field to order by.
          required: false
          type: string
          default: id
          enum:
            - id
            - name
            - surname
            - email
            - nif
        - name: direction
          in: query
          description: Direction of the order.
          required: false
          type: string
          default: ASC
          enum:
            - ASC
            - DESC
        - name: nif
          in: query
          description: Filter by nif
          type: string
        - name: email
          in: query
          description: Filter by email
          type: string
      security:
        - key: []
      responses:
        '200':
          description: paginated list of users
          schema:
            $ref: '#/definitions/UsersPage'
        '400':
          description: Incorrect sort criteria or no filter parameter provided
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: Create new user
      description: Creates a new user and returns the id and the status of the created user
      tags:
        - Users
      operationId: createUser
      parameters:
        - name: userRegistration
          in: body
          description: User registration attributes
          schema:
            $ref: '#/definitions/UserRegistration'
      responses:
        '200':
          description: Record successfully added.
          schema:
            $ref: '#/definitions/UserCreated'
        '400':
          description: Bad request (user already exists)
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '409':
          description: User already exists with this email
          schema:
            $ref: '#/definitions/HttpErrorUserExists'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/users/{userId}/houses':
    get:
      summary: Get user houses
      description: |
        Returns the user houses
      deprecated: true
      operationId: getUserHouses
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
      responses:
        '200':
          description: Houses of a given user
          schema:
            $ref: '#/definitions/UserHouses'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/HttpErrorForbidden'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - firebase: []
    post:
      summary: Create a house
      description: |
        Create a new house for the user
      tags:
        - Houses
      operationId: createHouse
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
        - name: createHouse
          in: body
          schema:
            $ref: '#/definitions/CreateHouse'
      security:
        - key: []
      responses:
        '200':
          description: Created house
          schema:
            $ref: '#/definitions/HouseCreated'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/users/{userId}/supplies':
    get:
      summary: Get user houses
      description: |
        Search a list of houses of the user.
      tags:
        - Houses
      operationId: getUserSupplies
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
      responses:
        '200':
          description: Supplies of a given user
          schema:
            $ref: '#/definitions/UserHouses'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/users/{userId}/user-detail':
    get:
      summary: Get user details
      description: |
        Retrieves detailed information about a specific user.
      tags:
        - Users
      operationId: getUser
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
      responses:
        '200':
          description: Record successfully retrieved.
          schema:
            $ref: '#/definitions/User'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/users/{userId}':
    put:
      summary: Update an user
      description: |
        Updates user properties
      tags:
        - Users
      operationId: updateUser
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
        - name: updateUser
          in: body
          description: user properties to update
          required: true
          schema:
            $ref: '#/definitions/UpdateUser'
      responses:
        '200':
          description: Record successfully updated.
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
    delete:
      summary: Delete an user
      description: |
        Deletes the user's account and all its related information (meters, energy
        data...).

        **Please note that this action is irreversible.**

        When the response is a 202, the process is not immediate and usually takes
        several minutes until the user is permanently deleted.
      tags:
        - Users
      operationId: deleteUserAccount
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
      responses:
        '202':
          description: Record successfully deleted.
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/users/{userId}/integrations/smartmeter':
    post:
      description: |
        This endpoint links a smart meter to a house:

        - Individuals must already have a CUPS Code.
        - Companies must already have a CUPS Code.

        A 403 forbidden response is returned if these conditions aren't met. Payload
        data will overwrite existing information.
      summary: Link a smartmeter to a house
      tags:
        - Integrations
      operationId: integrateSmartmeter
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
        - name: integrateSmartmeter
          in: body
          schema:
            $ref: '#/definitions/IntegrateSmartmeter'
      responses:
        '201':
          description: Smartmeter successfully integrated.
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/HttpErrorForbidden'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/users/{userId}/integrations/audinfor':
    post:
      summary: Assign Audinfor to user
      description: |
        Assigns an audinfor user id to an existing user
      tags:
        - Integrations
      operationId: assignAudinforUserIdToUser
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
        - name: assignAudinforUserIdToUser
          in: body
          schema:
            $ref: '#/definitions/AssignAudinforUserIdToUser'
      responses:
        '200':
          description: Audinfor user id successfully assigned to user
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/HttpErrorForbidden'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/users/{userId}/integrations/selectra/acceptTerms':
    post:
      summary: Accept Terms
      description: |
        Confirms user registration in selectra' datadis by acepting terms and conditions
      tags:
        - Integrations
      operationId: acceptTermsFromSelectra
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
      responses:
        '201':
          description: terms and conditions accepted
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/HttpErrorForbidden'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/users/{userId}/authorize-user':
    post:
      description: Authorizes a user resource (a house) to another user
      summary: Authorize a user
      tags:
        - Users
      operationId: authorizeUser
      parameters:
        - name: userId
          in: path
          description: The ID of the owner user
          required: true
          type: string
          format: uuid
        - name: authorizeUserRequest
          in: body
          description: User authorization attributes
          schema:
            $ref: '#/definitions/AuthorizeUserRequest'
      responses:
        '201':
          description: Authorized successfully
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/houses/{houseId}/update':
    put:
      summary: Update a house
      description: |
        Update a house
      tags:
        - Houses
      operationId: updateHouse
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: house
          in: body
          schema:
            $ref: '#/definitions/UpdateHouse'
      security:
        - key: []
      responses:
        '200':
          description: House updated successfully
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/house-detail':
    get:
      summary: Get house details
      description: |
        Returns house details.
      tags:
        - Houses
      operationId: getHouseDetail
      parameters:
        - name: houseId
          in: path
          description: ID of the house
          required: true
          type: string
          format: uuid
      security:
        - key: []
      responses:
        '200':
          description: House details
          schema:
            $ref: '#/definitions/UserHouseWithIntegrations'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/disaggregation':
    get:
      summary: Get house disaggregation
      description: |
        Returns the consumption disaggregation of a house.
      tags:
        - Disaggregation
      operationId: getDisaggregationByHouse
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: startDate
          in: query
          description: 'Start date to filter by. p.e. 2025-04-01T00:00:00Z'
          required: true
          type: string
          format: date-time
        - name: endDate
          in: query
          description: 'End date to filter by. p.e. 2025-04-30T00:00:00Z'
          required: true
          type: string
          format: date-time
      security:
        - key: []
      responses:
        '200':
          description: Disaggregation
          schema:
            $ref: '#/definitions/HouseDisaggregation'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/energy':
    get:
      summary: Get house energy
      description: |
        Returns the energy of a house for a date period (from startDate to endDate)
        grouped by date based on granularity
      tags:
        - Energy
      operationId: getEnergyByHouseId
      parameters:
        - name: houseId
          in: path
          description: ID of a house
          required: true
          type: string
        - name: startDate
          in: query
          description: Start date to filter by
          required: true
          type: string
          format: date-time
        - name: endDate
          in: query
          description: End date to filter by
          required: true
          type: string
          format: date-time
        - name: granularity
          in: query
          description: Granularity to group by
          required: true
          type: string
          enum:
            - YEARLY
            - MONTHLY
            - DAILY
            - HOURLY
        - name: includeTimeSpanStart
          in: query
          description: 'Time span start to filter within a day in hh:mm format (example 01:00)'
          required: false
          type: string
        - name: includeTimeSpanEnd
          in: query
          description: 'Time span end to filter within a day in hh:mm format (example 01:00)'
          required: false
          type: string
      security:
        - key: []
      responses:
        '200':
          description: House consumption
          schema:
            type: array
            items:
              $ref: '#/definitions/EnergyItem'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/energy-comparison':
    get:
      summary: Get energy comparison
      description: |
        Returns the energy of a house for a month and a comparison with different profiles
      tags:
        - Energy
      operationId: getEnergyComparison
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: month
          in: query
          description: Month to filter by
          required: true
          type: string
          format: MM/yyyy
      security:
        - key: []
      responses:
        '200':
          description: User house profile
          schema:
            $ref: '#/definitions/EnergyComparison'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/settings':
    get:
      summary: Get house settings
      description: |
        Returns house settings.
      tags:
        - Settings
      operationId: getHouseSettings
      parameters:
        - name: houseId
          in: path
          description: ID of the house
          required: true
          type: string
      security:
        - key: []
      responses:
        '200':
          description: House settings
          schema:
            $ref: '#/definitions/HouseSettings'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: Update house settings
      description: |
        Updates house settings.
      tags:
        - Settings
      operationId: updateHouseSettings
      parameters:
        - name: houseId
          in: path
          description: ID of the house
          required: true
          type: string
        - name: houseSettings
          in: body
          schema:
            $ref: '#/definitions/HouseSettings'
      security:
        - key: []
      responses:
        '200':
          description: House settings
          schema:
            $ref: '#/definitions/HouseSettings'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/contracts':
    post:
      summary: Create a contract
      description: |
        Creates a house contract
      tags:
        - Contracts
      operationId: createHouseContract
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: createHouseContract
          in: body
          schema:
            $ref: '#/definitions/CreateHouseContract'
      security:
        - key: []
      responses:
        '200':
          description: Contract created successfully
          schema:
            type: string
        '400':
          description: 'Bad request (e.g., house cups not found)'
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: House not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/invoices':
    post:
      summary: Create an invoice
      description: |
        This endpoint provides a signed URL for uploading a PDF invoice:
        - Step 1: POST invoice metadata to obtain the upload URL.
        - Step 2: PUT the PDF file to the returned URL (valid for 15 minutes).
      tags:
        - Invoices
      operationId: createHouseInvoice
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: createHouseInvoice
          in: body
          schema:
            $ref: '#/definitions/CreateHouseInvoice'
      security:
        - key: []
      responses:
        '200':
          description: Invoice created successfully
          schema:
            $ref: '#/definitions/SignedUrl'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: House Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/invoices/{invoiceId}':
    delete:
      summary: Delete house invoice
      description: Deletes a house invoice
      tags:
        - Invoices
      operationId: deleteHouseInvoice
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: invoiceId
          in: path
          description: Id of the invoice
          required: true
          type: string
      security:
        - key: []
      responses:
        '200':
          description: Invoice deleted successfully
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: House or Invoice Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/integrations/{vendor}:update-status':
    post:
      summary: Update integration status
      description: |
        Updates integration status of a vendor for an specific house
      tags:
        - Integrations
      operationId: updateIntegrationStatus
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: vendor
          in: path
          description: Data provider
          required: true
          type: string
        - name: updateSupplyContract
          in: body
          schema:
            $ref: '#/definitions/UpdateDatadisIntegrationStatus'
      security:
        - key: []
      responses:
        '200':
          description: Updated successfully
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/power':
    get:
      summary: Get house power
      description: |
        Returns the power of a house for a date period (from startDate to endDate)
      tags:
        - Power
      operationId: getPowerByHouseId
      parameters:
        - name: houseId
          in: path
          description: ID of a house
          required: true
          type: string
        - name: startDate
          in: query
          description: Start date to filter by
          required: true
          type: string
          format: date-time
        - name: endDate
          in: query
          description: End date to filter by
          required: true
          type: string
          format: date-time
      security:
        - key: []
      responses:
        '200':
          description: House power
          schema:
            type: array
            items:
              $ref: '#/definitions/PowerItem'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /connections:
    get:
      summary: Get all connections
      description: Get connections
      tags:
        - Connections
      operationId: getConnection
      security:
        - key: []
      responses:
        '200':
          description: List of connections
          schema:
            $ref: '#/definitions/ConnectionResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /installations:
    get:
      summary: Get all installations
      description: |
        Get all installations
      tags:
        - Integrations
      operationId: getInstallations
      parameters:
        - name: page
          in: query
          description: Number of the page starting at 1
          required: true
          type: integer
          format: int32
        - name: size
          in: query
          description: Size of the page
          required: true
          type: integer
          format: int32
        - name: sort
          in: query
          description: |
            Order by this param (ex:capacity, plantName, plantAddress,
            plantCode...).
          required: false
          type: string
          default: plantName
        - name: direction
          in: query
          description: Direction of the order.
          required: false
          type: string
          default: DESC
          enum:
            - ASC
            - DESC
        - name: integrationId
          in: query
          description: Filter by integration id
          required: false
          type: string
          format: uuid
        - name: name
          in: query
          description: Filter by installation name
          required: false
          type: string
        - name: hasHouseLinked
          in: query
          description: Filter by installation linked with house
          required: false
          type: boolean
      responses:
        '200':
          description: List of installations
          schema:
            $ref: '#/definitions/Installation'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/installations/{installationId}':
    put:
      summary: Update an installation
      description: |
        Update an installation
      tags:
        - Integrations
      operationId: updateInstallation
      parameters:
        - name: installationId
          in: path
          description: Id of the installation to update
          required: true
          type: string
        - name: updateInstallation
          in: body
          schema:
            $ref: '#/definitions/UpdateInstallation'
      responses:
        '200':
          description: Installation updated successfully
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Installation not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/houses/{houseId}/installations':
    post:
      summary: Link installation to a house
      description: |
        Link installation to a house
      tags:
        - Integrations
      operationId: connectInstallation
      parameters:
        - name: houseId
          in: path
          required: true
          type: string
        - name: connectInstallationRequest
          in: body
          schema:
            $ref: '#/definitions/ConnectInstallationRequest'
      security:
        - key: []
      responses:
        '200':
          description: Assigned installation to house
        '404':
          description: House not found
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/equipments':
    get:
      summary: Get equipments of a house
      description: |
        Returns the equipments of a house
      tags:
        - Equipments
      operationId: getHouseEquipments
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
      security:
        - key: []
      responses:
        '200':
          description: House equipments
          schema:
            $ref: '#/definitions/HouseEquipments'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: House Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/integrations/audinfor':
    post:
      summary: Assign Audinfor contract to house
      description: |
        Assigns an Audinfor contract id to an existing house
      tags:
        - Integrations
      operationId: assignAudinforContractIdToHouse
      parameters:
        - name: houseId
          in: path
          description: Alphanumeric id from a house
          required: true
          type: string
        - name: assignAudinforContractIdToHouse
          in: body
          description: Request
          schema:
            $ref: '#/definitions/AssignAudinforContractIdToHouse'
      responses:
        '202':
          description: Audinfor contract id successfully assigned to house
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/HttpErrorForbidden'
        '404':
          description: House not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  /tips:
    get:
      summary: Get tips
      description: Get all public tips
      tags:
        - Tips
      operationId: getPublicSavingTips
      produces:
        - application/json
      responses:
        '200':
          description: List of public saving tips
          schema:
            type: array
            items:
              type: object
              $ref: '#/definitions/PublicSavingTip'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security: []
  '/energy-communities/{energyCommunityId}/houses':
    post:
      summary: Assign a house to an energy community
      description: |
        Assign a house to an energy community
      tags:
        - Energy communities
      operationId: assignHouseToEnergyCommunity
      parameters:
        - name: energyCommunityId
          in: path
          description: Alphanumeric id from energy community
          required: true
          type: string
        - name: energyCommunityHouse
          in: body
          schema:
            $ref: '#/definitions/EnergyCommunityHouse'
      security:
        - key: []
      responses:
        '201':
          description: House successfully assigned
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Resource not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/energy-communities/{energyCommunityId}/update-share':
    post:
      summary: Update share
      description: |
        Update share for an energy community house
      tags:
        - Energy communities
      operationId: updateEnergyCommunityHouseShare
      parameters:
        - name: energyCommunityId
          in: path
          description: Alphanumeric id from energy community
          required: true
          type: string
        - name: UpdateEnergyCommunityHouseRequest
          in: body
          schema:
            $ref: '#/definitions/UpdateEnergyCommunityHouseRequest'
      security:
        - key: []
      responses:
        '200':
          description: House successfully updated
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/HttpErrorForbidden'
        '404':
          description: Resource not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/energy-communities/{communityId}/remove-house':
    post:
      summary: Remove a house from an energy community
      description: |
        Removes a house from an energy community
      tags:
        - Energy communities
      operationId: removeEnergyCommunityHouseFromInstallation
      parameters:
        - name: communityId
          in: path
          description: Alphanumeric id from energy community
          required: true
          type: string
        - name: removeEnergyCommunityHouseRequest
          in: body
          schema:
            $ref: '#/definitions/RemoveEnergyCommunityHouseRequest'
      security:
        - key: []
      responses:
        '200':
          description: House successfully removed
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/HttpErrorForbidden'
        '404':
          description: Resource not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/users/{userId}/virtual-wallet':
    post:
      summary: Create virtual wallet transaction
      description: |
        Creates user virtual wallet transaction
      tags:
        - Virtual wallet
      operationId: createVirtualWalletTransaction
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
        - name: virtualWalletRequest
          in: body
          description: User virtual wallet transaction request
          schema:
            $ref: '#/definitions/UserVirtualWalletTransaction'
      responses:
        '201':
          description: User virtual wallet transaction created
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '422':
          description: Unprocessable entity
          schema:
            $ref: '#/definitions/HttpErrorUnprocessableEntity'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/users/{userId}/virtual-battery':
    post:
      summary: Create virtual battery transaction
      description: |
        Creates a user virtual battery transaction
      tags:
        - Virtual battery
      operationId: createVirtualBatteryTransaction
      parameters:
        - name: userId
          in: path
          description: ID of user
          required: true
          type: string
        - name: virtualBatteryRequest
          in: body
          description: User virtual battery transaction request
          schema:
            $ref: '#/definitions/UserVirtualBatteryTransaction'
      responses:
        '201':
          description: User virtual wallet transaction created
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '422':
          description: Unprocessable entity
          schema:
            $ref: '#/definitions/HttpErrorUnprocessableEntity'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  /tariffs:
    post:
      summary: Create new tariff
      description: Creates a new tariff and returns it
      tags:
        - Tariffs
      operationId: createTariff
      parameters:
        - name: tariff
          in: body
          description: Tariff attributes
          schema:
            $ref: '#/definitions/CreateTariff'
      security:
        - key: []
      responses:
        '200':
          description: Tariff successfully added.
          schema:
            $ref: '#/definitions/Tariff'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '409':
          description: Conflict. Tariff already exists
          schema:
            $ref: '#/definitions/HttpErrorConflict'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Get tariffs
      description: |
        Returns a list of tariffs
      tags:
        - Tariffs
      operationId: getTariffs
      security:
        - key: []
      responses:
        '200':
          description: list of tariffs
          schema:
            type: array
            items:
              $ref: '#/definitions/Tariff'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/tariffs/{tariffId}':
    get:
      summary: Get tariff details
      description: |
        Returns the details of a tariff
      tags:
        - Tariffs
      operationId: getTariff
      parameters:
        - name: tariffId
          in: path
          description: ID of tariff
          required: true
          type: string
      security:
        - key: []
      responses:
        '200':
          description: tariff details
          schema:
            $ref: '#/definitions/Tariff'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: Update tariff
      description: Updates a tariff and returns it
      tags:
        - Tariffs
      operationId: updateTariff
      parameters:
        - name: tariffId
          in: path
          description: ID of tariff
          required: true
          type: string
        - name: tariff
          in: body
          description: Tariff attributes
          schema:
            $ref: '#/definitions/CreateTariff'
      security:
        - key: []
      responses:
        '200':
          description: Tariff successfully updated.
          schema:
            $ref: '#/definitions/Tariff'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Delete tariff
      description: Deletes a tariff
      tags:
        - Tariffs
      operationId: deleteTariff
      parameters:
        - name: tariffId
          in: path
          description: ID of tariff
          required: true
          type: string
      security:
        - key: []
      responses:
        '200':
          description: Tariff successfully deleted.
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/tariffs/{tariffId}/energy-prices':
    put:
      summary: Set tariff energy prices
      description: |
        Sets the energy prices of a tariff, excluding taxes. The given dates should be in UTC, and sets the price (in €/kWh) for the given hour.
        Eg.: if a price for 2025-03-12T10:00:00Z is provided, it sets the price for the energy from 10:00 to 11:00.
      tags:
        - Tariffs
      operationId: setTariffEnergyPrices
      parameters:
        - name: tariffId
          in: path
          description: ID of tariff
          required: true
          type: string
        - name: tariffEnergyPrices
          in: body
          description: tariff energy prices to set
          required: true
          schema:
            $ref: '#/definitions/TariffEnergyPrices'
      responses:
        '200':
          description: Record successfully set.
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  /integrations/users:
    post:
      summary: Assign an external user id to a user
      description: |
        Assign an external user id to a user for an integration
      tags:
        - Integrations
      operationId: assignExternalUserIdToUser
      parameters:
        - name: assignExternalUserIdToUser
          in: body
          schema:
            $ref: '#/definitions/AssignExternalUserIdToUser'
      responses:
        '200':
          description: External user id successfully assigned to user.
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
    get:
      summary: Get assigned users for an integration
      description: |
        Get assigned users for an integration.
      tags:
        - Integrations
      operationId: getAssignedUsersOfIntegration
      parameters:
        - name: userId
          in: query
          description: user id
          type: string
        - name: externalUserId
          in: query
          description: external user id
          required: true
          type: string
        - name: vendor
          in: query
          description: integration vendor
          required: true
          type: string
          enum:
            - AUDINFOR
            - GISCE
      responses:
        '200':
          description: Assigned users successfully retrieved.
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  /houses:
    get:
      summary: Get all the tenant houses
      description: |
        Get tenant houses
      tags:
        - Houses
      operationId: getTenantHouses
      parameters:
        - name: cursor
          in: query
          description: Cursor for pagination (not inclusive)
          required: false
          type: string
          format: uuid
        - name: limit
          in: query
          description: Maximum number of houses to return (max 100)
          required: false
          type: integer
          format: int32
      responses:
        '200':
          description: Page of houses
          schema:
            $ref: '#/definitions/HousesPage'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/houses/{houseId}/contracts/{contractId}/energy-prices':
    put:
      summary: Add energy prices to a contract
      description: |
        Adds the contract energy prices for specific dates
      tags:
        - Contracts
      operationId: addHouseContractEnergyPrices
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: contractId
          in: path
          description: Id of the contract
          required: true
          type: string
        - name: houseContractEnergyPriceRequest
          in: body
          description: Request containing contract energy prices and dates
          required: true
          schema:
            $ref: '#/definitions/HouseContractEnergyPriceRequest'
      security:
        - key: []
      responses:
        '200':
          description: Contract prices added succesfully
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/external-contracts':
    post:
      summary: Link a contract with an external id
      description: |
        Links a contract with an external id
      tags:
        - Contracts
      operationId: assignExternalContractIdToContract
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: assignExternalContractToContractRequest
          in: body
          schema:
            $ref: '#/definitions/AssignExternalContractToContractRequest'
      security:
        - key: []
      responses:
        '200':
          description: Contract assigned successfully
          schema:
            type: string
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/external-contracts/{externalContractId}':
    get:
      summary: Get contract id from external id
      description: |
        Gets contract id from the external id it is linked to
      tags:
        - Contracts
      operationId: getHouseContractIdByExternalId
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: externalContractId
          in: path
          description: External id of the contract
          required: true
          type: string
      security:
        - key: []
      responses:
        '200':
          description: Contract id
          schema:
            type: string
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/houses/{houseId}/smartmeter':
    post:
      summary: Store energies for a house
      description: |
        Stores a list of energies and dates for a specific house.
        :::warning
        This endpoint is experimental. Please, contact us if you want to use it.
        :::
      operationId: storeHouseEnergies
      parameters:
        - name: houseId
          in: path
          description: Id of the house
          required: true
          type: string
        - name: storeHouseEnergiesRequest
          in: body
          schema:
            $ref: '#/definitions/StoreHouseEnergiesRequest'
      security:
        - key: []
      responses:
        '200':
          description: Energies stored correctly
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/HttpErrorForbidden'
        '404':
          description: House Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/invoice-analysis/{invoiceAnalysisId}':
    get:
      summary: Get invoice analysis
      description: |
        Get latest available invoice analysis
      tags:
        - Invoices
      operationId: getInvoiceAnalysisById
      parameters:
        - name: invoiceAnalysisId
          in: path
          description: ID of invoice analysis.
          required: true
          type: string
          format: uuid
      security:
        - key: []
      responses:
        '200':
          description: latest invoice analysis
          schema:
            $ref: '#/definitions/InvoiceAnalysis'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/invoice-analysis/{invoiceAnalysisId}/tariffs':
    get:
      summary: Get invoice analysis tariffs
      description: |
        Get all available tariffs based on the invoice with their monthly invoice saving
      tags:
        - Tariffs
      operationId: getInvoiceTariffs
      parameters:
        - name: invoiceAnalysisId
          in: path
          description: ID of invoice analysis
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: Tariffs with its monthly savings
          schema:
            $ref: '#/definitions/InvoiceTariffs'
        '204':
          description: No content. Returned when there are no defined tariffs.
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  /invoice-analysis:
    post:
      summary: Analyze invoice
      description: |
        Analizes an invoice from an url
      tags:
        - Invoices
      operationId: analyzeInvoice
      parameters:
        - name: analyzeInvoice
          in: body
          description: Invoice url. (Should be a public url)
          schema:
            $ref: '#/definitions/AnalyzeInvoice'
      security:
        - key: []
      responses:
        '200':
          description: Invoice analized and recorded.
          schema:
            $ref: '#/definitions/InvoiceAnalysisId'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/tickets/{ticketId}':
    get:
      summary: Get ticket details
      description: |
        Returns the details of a ticket
      tags:
        - Tickets
      operationId: getTicketDetails
      parameters:
        - name: ticketId
          in: path
          description: ID of ticket
          required: true
          type: string
      security:
        - key: []
      responses:
        '200':
          description: ticket details
          schema:
            $ref: '#/definitions/Ticket'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: Update ticket
      description: Updates a ticket
      tags:
        - Tickets
      operationId: updateTicket
      parameters:
        - name: ticketId
          in: path
          description: ID of ticket
          required: true
          type: string
        - name: updateTicketRequest
          in: body
          description: Ticket attributes to be updated
          schema:
            $ref: '#/definitions/UpdateTicketRequest'
      security:
        - key: []
      responses:
        '200':
          description: ticket details
          schema:
            $ref: '#/definitions/Ticket'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/tickets/{ticketId}/comment':
    post:
      summary: Add comment
      description: |
        Add comment to ticket
      tags:
        - Tickets
      operationId: addCommentToTicket
      parameters:
        - name: ticketId
          in: path
          description: ID of ticket
          required: true
          type: string
        - name: commentRequest
          in: body
          description: message of the comment to add
          required: true
          schema:
            $ref: '#/definitions/CommentRequest'
      responses:
        '201':
          description: Comment successfully added to ticket
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  /equipments:
    get:
      summary: Get all the tenant equipments of a given type
      description: |
        Get tenant equipments of a given type.
      tags:
        - Equipments
      operationId: getTenantEquipments
      parameters:
        - name: integrationType
          in: query
          description: Filter by integration type
          required: true
          type: string
          enum:
            - DISTRIBUTOR
            - SOLAR
            - SMART_DEVICE
            - STORAGE
        - name: cursor
          in: query
          description: Cursor for pagination (not inclusive)
          required: false
          type: string
          format: uuid
        - name: limit
          in: query
          description: Maximum number of equipments to return (max 100)
          required: false
          type: integer
          format: int32
      responses:
        '200':
          description: Page of equipments
          schema:
            $ref: '#/definitions/EquipmentsPage'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Bad request
          schema:
            $ref: '#/definitions/HttpErrorBadRequest'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - key: []
  '/equipments/{equipmentId}/storage':
    get:
      summary: Get storage equipment data
      description: |
        Returns the storage equipment information.
      tags:
        - Equipments
      operationId: getStorageEquipment
      parameters:
        - name: equipmentId
          in: path
          description: Id of the equipment
          required: true
          type: string
      security:
        - key: []
      responses:
        '200':
          description: StorageEquipment
          schema:
            $ref: '#/definitions/StorageEquipment'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/equipments/{equipmentId}/storage/soc':
    get:
      summary: Get storage equipment state of charge
      description: |
        Returns the storage equipment state of charge information.
      tags:
        - Equipments
      operationId: getStorageEquipmentSoc
      parameters:
        - name: equipmentId
          in: path
          description: Id of the equipment
          required: true
          type: string
        - name: startDate
          in: query
          description: Start date to filter by
          required: true
          type: string
          format: date-time
        - name: endDate
          in: query
          description: End date to filter by
          required: true
          type: string
          format: date-time
      security:
        - key: []
      responses:
        '200':
          description: StorageEquipmentSoc
          schema:
            $ref: '#/definitions/StorageEquipmentSoc'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/equipments/{equipmentId}/storage/schedule':
    post:
      summary: Schedule an action for a storage equipment
      description: |
        Schedules an action (charge or discharge) for a storage equipment.
      tags:
        - Equipments
      operationId: scheduleStorageEquipmentAction
      parameters:
        - name: equipmentId
          in: path
          description: Id of the equipment
          required: true
          type: string
        - name: scheduleStorageActionRequest
          in: body
          description: Request body to schedule an action
          required: true
          schema:
            $ref: '#/definitions/ScheduleStorageActionRequest'
      security:
        - key: []
      responses:
        '201':
          description: Action scheduled successfully
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/HttpErrorUnauthorized'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/HttpErrorNotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  AuthUser:
    type: object
    properties:
      jwt:
        type: string
        example: eyJhbGciOiJSJhdWQiOiJodHRwczopdC5nb29nbGVhcGlzLmNvbS9nb29nbGUuaWRlbnRpdHkuaWRlbnRpdHl0b29sa2l0LnYxLklkZW50aXRF0IjoxNzAzODU0NzY5LCJpc3MiOiJwdWJsaWMtZnJvbnQtYmFja0BjbGV2ZXJneS5pYW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIsInN1YiI6InB1YmxpYy1mcm9udC1iYWNrQGNXA
      userId:
        type: string
        example: U7Q02aMJm9VokGsNIZmID3BK25p3
  User:
    type: object
    properties:
      id:
        type: string
        example: U4NW5zdmstUtRZW5Oi3S2CR5l0U2
      name:
        type: string
        example: Pedro
      surname:
        type: string
        example: García
      email:
        type: string
        example: pedro.garcia@mail.com
      nif:
        type: string
        example: 00000000T
  UsersPage:
    type: object
    description: Paginated list of users
    properties:
      size:
        type: integer
        description: Number of elements in the page requested
      page:
        type: integer
        description: Number of the page requested
      totalPages:
        type: integer
        description: Number of total pages
      totalElements:
        type: integer
        description: Number of total elements in the list
      elements:
        type: array
        description: List of users
        items:
          type: object
          $ref: '#/definitions/UsersPageElement'
    required:
      - size
      - page
      - totalPages
      - totalElements
      - elements
  UsersPageElement:
    type: object
    properties:
      id:
        type: string
        example: U4NW5zdmstUtRZW5Oi3S2CR5l0U2
      name:
        type: string
        example: Pedro
      surname:
        type: string
        example: García
      email:
        type: string
        example: pedro.garcia@mail.com
      nif:
        type: string
        example: 00000000T
  UserCreated:
    type: object
    properties:
      id:
        type: string
        example: U4NW5zdmstUtRZW5Oi3S2CR5l0U2
      status:
        type: string
        example: INITIAL
  UserRegistration:
    type: object
    properties:
      name:
        type: string
        example: John
      surname:
        type: string
        example: Doe
      email:
        type: string
        format: email
        example: john.doe@example.com
      dni:
        type: string
        example: 12345678X
      phoneNumber:
        type: string
        example: '600000000'
  UpdateUser:
    type: object
    properties:
      name:
        type: string
        example: John
      surname:
        type: string
        example: Doe
      email:
        type: string
        format: email
        example: john.doe@example.com
      dni:
        type: string
        example: 12345678X
      phoneNumber:
        type: string
        example: '600000000'
  UserHouses:
    type: array
    items:
      type: object
      properties:
        houseId:
          type: string
          example: 8ec307fc-3b4c-4f6f-b320-fa2587990a46
        cups:
          type: string
          example: ES0022123456781234AB0F
        address:
          type: string
          example: Leonardo da Vinci 7
        postalCode:
          type: string
          example: '41092'
        firstConsumptionDate:
          type: string
          format: date-time
          example: '2022-12-31T23:00:00'
        lastConsumptionDate:
          type: string
          format: date-time
          example: '2023-12-31T22:00:00'
  UserHouseWithIntegrations:
    type: object
    properties:
      details:
        type: object
        properties:
          houseId:
            type: string
            format: uuid
          userId:
            type: string
          cups:
            type: string
          address:
            type: string
          postalCode:
            type: string
          timeZone:
            type: string
          addressBlockNumber:
            type: string
          addressFloor:
            type: string
          addressStaircase:
            type: string
          addressDoor:
            type: string
          addressAdditionalInfo:
            type: string
        required:
          - houseId
          - userId
      houseMetadata:
        type: object
        properties:
          firstDateEnergy:
            type: string
            format: date
          lastDateEnergy:
            type: string
            format: date
          firstDatePower:
            type: string
            format: date
          lastDatePower:
            type: string
            format: date
          firstDateCost:
            type: string
            format: date
          lastDateCost:
            type: string
            format: date
          isOwner:
            type: boolean
          mayBeSolar:
            type: boolean
      houseIntegrations:
        type: object
        $ref: '#/definitions/HouseIntegrations'
    required:
      - details
      - houseMetadata
      - houseIntegrations
  CreateHouse:
    type: object
    description: Create house request
    properties:
      address:
        type: string
        description: House address
        example: Leonardo da Vinci 7
      postalCode:
        type: string
        description: House postal code
        example: '41092'
      cups:
        type: string
        description: 'When filled, CUPS of the supply to connect'
        example: ES0022123456781234AB0F
      addressBlockNumber:
        type: string
        description: address block number
      addressFloor:
        type: string
        description: address floor
      addressStaircase:
        type: string
        description: address staircase
      addressDoor:
        type: string
        description: address door
      addressAdditionalInfo:
        type: string
        description: address additional info
      selfConsumptionTypeCode:
        type: string
        description: self consumption type code (2 digits)
  HouseCreated:
    type: object
    description: Create house response
    properties:
      id:
        type: string
        description: House id
        example: f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454
      address:
        type: string
        description: House address
        example: Leonardo da Vinci 7
      postalCode:
        type: string
        description: House postal code
        example: '41092'
  UpdateHouse:
    type: object
    properties:
      cups:
        type: string
        description: CUPS of the house
      address:
        type: string
        description: 'address (horizontal address. street, number, etc)'
      postalCode:
        type: string
        description: postal code
      addressBlockNumber:
        type: string
        description: address block number
      addressFloor:
        type: string
        description: address floor
      addressStaircase:
        type: string
        description: address staircase
      addressDoor:
        type: string
        description: address door
      addressAdditionalInfo:
        type: string
        description: address additional info
      selfConsumptionTypeCode:
        type: string
        description: self consumption type code (2 digits)
  PowerItem:
    type: object
    properties:
      date:
        type: string
        format: date-time
      solar:
        type: object
        properties:
          production:
            type: number
            format: float
      grid:
        type: object
        properties:
          power:
            type: number
            format: float
      house:
        type: object
        properties:
          power:
            type: number
            format: float
      battery:
        type: object
        properties:
          power:
            type: number
            format: float
          chargePower:
            type: number
            format: float
          dischargePower:
            type: number
            format: float
      energyCommunities:
        type: array
        items:
          type: object
          $ref: '#/definitions/EnergyCommunityPower'
      smartDevices:
        type: array
        items:
          type: object
          $ref: '#/definitions/SmartDevicesPower'
  EnergyItem:
    type: object
    properties:
      date:
        type: string
        format: date-time
      solar:
        type: object
        properties:
          production:
            type: number
            format: float
      house:
        type: object
        properties:
          consumption:
            type: number
            format: float
          selfConsumption:
            type: number
            format: float
      grid:
        type: object
        properties:
          import:
            type: number
            format: float
          export:
            type: number
            format: float
      battery:
        type: object
        properties:
          charge:
            type: number
            format: float
          discharge:
            type: number
            format: float
      energyCommunities:
        type: array
        items:
          type: object
          properties:
            type:
              type: string
              enum:
                - SOLAR
                - WIND
                - HYDRO
            production:
              type: number
              format: float
          required:
            - type
            - production
      smartDevices:
        type: array
        items:
          type: object
          properties:
            subtype:
              type: string
            vendor:
              type: string
              enum:
                - SHELLY
            energy:
              type: number
              format: float
          required:
            - subtype
            - vendor
            - energy
    required:
      - date
  EnergyComparison:
    required:
      - currentYear
      - profile
    properties:
      consumption:
        type: number
        format: float
        description: Energy consumption of the house
      currentYear:
        type: boolean
        description: If the comparison is for the current year
      profile:
        type: string
        enum:
          - 'EFFICIENT,'
          - 'MEDIUM,'
          - INEFFICIENT
          - NO_PROFILE
        description: Current profile of the house
      similarHomesConsumption:
        type: number
        format: float
        description: Average consumption of similar homes. Can  be null (depends on configuration)
      energyEfficientHomesConsumption:
        type: number
        format: float
        description: Average consumption of energy efficient homes. Can be null (depends on configuration)
      neighborhoodHomesConsumption:
        type: number
        format: float
        description: Average consumption of homes in the neighborhood
  EnergyCommunityPower:
    type: object
    properties:
      type:
        type: string
        enum:
          - SOLAR
          - WIND
          - HYDRO
      production:
        type: number
        format: float
  CreateHouseContract:
    type: object
    description: Create house contract request
    properties:
      contractPower:
        type: array
        items:
          type: number
        description: 'Contracted power. One item per period (P1, P2)'
        example:
          - 3.5
          - 3.5
      startDate:
        type: string
        format: date-time
        example: '2022-12-31T23:00:00'
        description: Contract start date
      endDate:
        type: string
        format: date-time
        example: '2022-12-31T23:00:00'
        description: Contract end date
      powerPrices:
        type: array
        items:
          type: number
        description: 'Price of power. One item per period (P1, P2)'
        example:
          - 0.09
          - 0.03
      energyPrices:
        type: array
        items:
          type: number
        description: 'Price of energy. One item per period (P1, P2)'
        example:
          - 0.13
          - 0.12
      provider:
        type: string
        example: EnergyProvider
        description: Contract provider
      codefare:
        type: string
        example: 2.0TD
        description: Contract codefare
      distributor:
        type: string
        example: '8'
        description: Contract distributor
      pvpc:
        type: boolean
        example: true
        description: Contract flag for PVPC
      socialBonus:
        type: boolean
        example: true
        description: Contract flag for social bonus
      tariffName:
        type: string
        example: Tariff name
        description: Contract tariff name
      status:
        type: string
        example: Active
        description: Contract status
      solarPrice:
        type: number
        format: float
        example: '0.012'
        description: Price of solar energy surplus
      commercialName:
        type: string
        example: Commercial name
        description: Contract commercial name
      holderName:
        type: string
        example: John Doe
        description: Bank account holder name
      iban:
        type: string
        example: ES0000000000000000000000
        description: International Bank Account Number (IBAN)
  SignedUrl:
    type: object
    description: Bucket url to put a file
    properties:
      url:
        type: string
        example: 'https://signed_url_to_put_the_object'
        description: Signed url to put the object
  CreateHouseInvoice:
    type: object
    description: Create house invoice request
    required:
      - startDate
      - endDate
      - totalCost
    properties:
      startDate:
        type: string
        format: date
        example: '2022-12-31'
        description: Start of invoicing period
      endDate:
        type: string
        format: date
        example: '2022-12-31'
        description: End of invoicing period
      totalCost:
        type: number
        format: float
        example: '0.883'
        description: Total cost in €
      energyConsumptionP1:
        type: number
        format: float
        example: '0.883'
        description: P1 consumptions in kWh
      energyConsumptionP2:
        type: number
        format: float
        example: '0.883'
        description: P2 consumptions in kWh
      energyConsumptionP3:
        type: number
        format: float
        example: '0.883'
        description: P3 consumptions in kWh
      totalEnergyConsumption:
        type: number
        format: float
        example: '0.883'
        description: Total consumptions in kWh
      energyCost:
        type: number
        format: float
        example: '0.883'
        description: Energy cost in €
      powerCost:
        type: number
        format: float
        example: '0.883'
        description: Power cost in €
      otherCost:
        type: number
        format: float
        example: '0.883'
        description: Sum of other costs in €
      discountCost:
        type: number
        format: float
        example: '0.883'
        description: Total discounts in €
      taxCost:
        type: number
        format: float
        example: '0.883'
        description: Total taxes in €
      exportSaving:
        type: number
        format: float
        example: '-0.25'
        description: Total saving of export in €
      serviceCost:
        type: number
        format: float
        example: '0.25'
        description: Cost of service in €
      virtualWallet:
        type: number
        format: float
        example: '0.25'
        description: Virtual wallet balance €
  IntegrateSmartmeter:
    type: object
    description: Smartmeter integration request
    required:
      - name
      - nif
      - termsAndConditions
    properties:
      name:
        type: string
      surname:
        type: string
      nif:
        type: string
      termsAndConditions:
        type: boolean
      manualValidation:
        type: boolean
        description: Flag to manually validate a user. By default it is false.
  AssignAudinforUserIdToUser:
    type: object
    description: Audinfor user integration request
    required:
      - idCliente
    properties:
      idCliente:
        type: string
        example: '1234'
      connectionId:
        type: string
  AssignAudinforContractIdToHouse:
    type: object
    description: Audinfor house integration request
    required:
      - contratoId
    properties:
      contratoId:
        type: string
        example: '1234'
      connectionId:
        type: string
  UpdateDatadisIntegrationStatus:
    type: object
    description: Update datadis integration status request
    properties:
      status:
        type: string
        example: CONNECTED
        description: Supply contract start date
        enum:
          - CONNECTED
          - DISCONNECTED
      eventDate:
        type: string
        format: date-time
        example: '2023-12-31T22:00:00'
        description: Update status event date
  HouseDataConsumption:
    type: object
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/HouseConsumption'
      rateType:
        type: string
        example: REGULATED
      total:
        type: number
        format: float
        example: '0.883'
  HouseConsumption:
    type: object
    properties:
      date:
        type: string
        format: date-time
        example: '2023-12-01T00:00:00Z'
      categories:
        type: array
        items:
          $ref: '#/definitions/UserConsumptionCategory'
      kwh:
        type: number
        format: float
        example: '0.883'
  HouseDisaggregation:
    properties:
      devices:
        type: array
        items:
          $ref: '#/definitions/DisaggregationDevice'
  DisaggregationDevice:
    properties:
      device:
        type: string
        enum:
          - AEROTHERMAL_BOILER
          - AEROTHERMAL_HEATER
          - AIR_CONDITIONING
          - AUTOMATIC_IRRIGATION
          - CERAMIC_HOB
          - CHARGING_POINT
          - DISHWASHER
          - DRYER
          - ELECTRIC_BOILER
          - ELECTRIC_RADIATOR
          - ELECTRIC_VEHICLE
          - FILTER_PUMP
          - FRIDGE
          - FREEZER
          - INDUCTION
          - LIGHT
          - OVEN
          - OTHER
          - STANDBY
          - WASHING_MACHINE
        example: FRIDGE
      kwh:
        type: number
        format: float
        example: '20.0'
      percentage:
        type: number
        format: float
        example: '14.6'
  HouseSettings:
    type: object
    properties:
      houseId:
        type: string
      houseType:
        type: string
        enum:
          - FLAT
          - HOME
      meters:
        type: number
      housePeople:
        type: number
      devices:
        type: array
        items:
          type: string
          enum:
            - AEROTHERMAL_BOILER
            - AEROTHERMAL_HEATER
            - AIR_CONDITIONING
            - AUTOMATIC_IRRIGATION
            - BATTERY
            - CERAMIC_HOB
            - CENTRAL_HEATER
            - CHARGING_POINT
            - DISHWASHER
            - DRYER
            - ELECTRIC_BOILER
            - ELECTRIC_RADIATOR
            - ELECTRIC_VEHICLE
            - FILTER_PUMP
            - FRIDGE
            - FREEZER
            - GAS_BOILER
            - GAS_HEATER
            - GAS_KITCHEN
            - INDUCTION
            - OVEN
            - PHOTOVOLTAIC_SOLAR_PANEL
            - SOLAR_THERMAL_PANEL
            - WASHING_MACHINE
  HouseIntegration:
    type: object
    properties:
      status:
        type: string
        enum:
          - NONE
          - CONNECTED
    required:
      - status
  HouseIntegrations:
    type: object
    properties:
      huaweiB2C:
        type: object
        $ref: '#/definitions/HouseIntegration'
      froniusB2C:
        type: object
        $ref: '#/definitions/HouseIntegration'
  UserConsumptionCategory:
    type: object
    properties:
      label:
        type: string
        example: Valle
      kwh:
        type: number
        format: float
        example: 0.883
  PublicSavingTip:
    type: object
    properties:
      title:
        type: string
        example: Elige neveras con buena calificación energética
      text:
        type: string
        example: 'Si tu nevera es antigua, plantéate comprar una nevera con  calificación energética alta. Podrás ahorrar un 20% en tu factura.'
  EnergyCommunityHouse:
    type: object
    description: Assign a house to an energy community
    required:
      - houseId
      - share
    properties:
      houseId:
        type: string
        description: House Id
      share:
        type: number
        description: Share (in percentage) in the energy community
      installationId:
        type: string
        description: Installation Id
  RemoveEnergyCommunityHouseRequest:
    type: object
    description: Remove energy community house
    required:
      - houseId
    properties:
      houseId:
        type: string
        description: House Id
      installationId:
        type: string
        description: Installation Id
  UpdateEnergyCommunityHouseRequest:
    type: object
    description: Update energy community house share
    required:
      - houseId
      - share
    properties:
      houseId:
        type: string
        description: House Id
      share:
        type: number
        description: Share (in percentage) in the energy community
      installationId:
        type: string
        description: Installation Id
  UpdateInstallation:
    type: object
    properties:
      capacity:
        type: number
        format: float
        description: Capacity of the installation
        example: 10
      plantAddress:
        type: string
        description: Address of the installation
        example: Leonardo da Vinci 7
      plantName:
        type: string
        description: Name of the installation
        example: My installation
  UserVirtualWalletTransaction:
    type: object
    required:
      - date
      - amount
      - totalBalance
    properties:
      date:
        type: string
        format: date
      amount:
        type: number
        format: float
        description: Transaction amount (in Euros)
      totalBalance:
        type: number
        format: float
        description: Total balance after the transaction (in Euros)
  UserVirtualBatteryTransaction:
    type: object
    required:
      - date
      - amount
      - totalBalance
    properties:
      date:
        type: string
        format: date
      amount:
        type: number
        format: float
        description: Transaction amount (in kW)
      totalBalance:
        type: number
        format: float
        description: Total balance after the transaction (in kW)
  HttpErrorUnauthorized:
    type: object
    properties:
      timestamp:
        description: Request date and time
        type: string
        example: '2023-12-26T10:23:19.508+00:00'
      status:
        description: Http error code
        type: integer
        format: int32
        example: 401
      error:
        description: Http error description
        type: string
        example: Unauthorized
      path:
        description: Request path
        type: string
        example: /auth/john.doe@gmail.com/token
  HttpErrorNotFound:
    type: object
    properties:
      timestamp:
        description: Request date and time
        type: string
        example: '2023-12-26T10:23:19.508+00:00'
      status:
        description: Http error code
        type: integer
        format: int32
        example: 404
      error:
        description: Http error description
        type: string
        example: Not Found
      path:
        description: Request path
        type: string
        example: /auth/alice.smith@gmail.com/token
  HttpErrorBadRequest:
    type: object
    properties:
      timestamp:
        description: Request date and time
        type: string
        example: '2023-12-26T10:23:19.508+00:00'
      status:
        description: Http error code
        type: integer
        format: int32
        example: 400
      error:
        description: Http error description
        type: string
        example: Bad Request
      path:
        description: Request path
        type: string
        example: /users
  HttpErrorConflict:
    type: object
    properties:
      timestamp:
        description: Request date and time
        type: string
        example: '2025-01-01T12:00:00.508+00:00'
      status:
        description: Http error code
        type: integer
        format: int32
        example: 409
      error:
        description: Http error description
        type: string
        example: Conflict
  HttpErrorUnprocessableEntity:
    type: object
    properties:
      timestamp:
        description: Request date and time
        type: string
        example: '2023-12-26T10:23:19.508+00:00'
      status:
        description: Http error code
        type: integer
        format: int32
        example: 422
      error:
        description: Http error description
        type: string
        example: Unprocessable Entity
      path:
        description: Request path
        type: string
        example: /users
  HttpErrorForbidden:
    type: object
    properties:
      timestamp:
        description: Request date and time
        type: string
        example: '2023-12-26T10:23:19.508+00:00'
      status:
        description: Http error code
        type: integer
        format: int32
        example: 403
      error:
        description: Http error description
        type: string
        example: Forbidden
      path:
        description: Request path
        type: string
        example: /users/U4NW5zdmstUtRZW5Oi3S2CR5l0U2/houses
  HttpErrorUserExists:
    type: object
    properties:
      timestamp:
        description: Request date and time
        type: string
        example: '2023-12-26T10:23:19.508+00:00'
      status:
        description: Http error code
        type: integer
        format: int32
        example: 409
      error:
        description: Http error description
        type: string
        example: User exists
  Error:
    type: object
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
  ConnectInstallationRequest:
    type: object
    properties:
      installationId:
        type: string
    required:
      - installationId
  InstallationList:
    type: object
    description: List of installations
    properties:
      size:
        type: integer
        description: Number of elements in the page requested
      page:
        type: integer
        description: Number of the page requested
      totalPages:
        type: integer
        description: Number of total pages
      totalElements:
        type: integer
        description: Number of total elements in the list
      elements:
        type: array
        description: List of installations
        items:
          type: object
          $ref: '#/definitions/Installation'
    required:
      - size
      - page
      - totalPages
      - totalElements
      - elements
  Installation:
    type: object
    required:
      - installationId
      - integrationId
      - name
      - vendor
      - vendorId
      - status
    properties:
      installationId:
        type: string
        format: uuid
      integrationId:
        type: string
        format: uuid
      name:
        type: string
      address:
        type: string
      capacity:
        type: number
        format: float
      vendor:
        type: string
        enum:
          - HUAWEI
          - HUAWEI_OAUTH
          - SOLAR_EDGE
          - FRONIUS_B2C
          - FRONIUS
          - GOODWE
      connectionDate:
        type: string
        format: date-time
      vendorId:
        type: string
      status:
        type: string
        enum:
          - ACTIVE
          - DISCONNECTED
          - FAULTY
  ConnectionResponse:
    type: array
    items:
      type: object
      $ref: '#/definitions/Connection'
  Connection:
    type: object
    properties:
      connectionId:
        type: string
        format: uuid
        example: 1253a9ca-2b85-14f1-b93d-42010aeb51df
      name:
        type: string
        example: Audinfor
      vendor:
        type: string
        enum:
          - AUDINFOR
          - GISCE
          - ENEXPA
        example: AUDINFOR
      type:
        type: string
        enum:
          - ERP
        example: ERP
    required:
      - connectionId
      - name
      - type
      - vendor
  AssignExternalUserIdToUser:
    type: object
    description: External user  assignation request
    required:
      - userId
      - externalUserId
      - vendor
    properties:
      userId:
        type: string
      externalUserId:
        type: string
      vendor:
        type: string
        enum:
          - AUDINFOR
          - GISCE
      connectionId:
        type: string
  AssignedUsersList:
    type: object
    description: List of users assigned to an integration
    properties:
      assignedUsers:
        type: array
        description: List of users assigned
        items:
          type: object
          $ref: '#/definitions/AssignedUser'
    required:
      - assignedUsers
  AssignedUser:
    type: object
    properties:
      userId:
        type: string
      externalUserId:
        type: string
    required:
      - userId
      - externalUserId
  Tariff:
    type: object
    description: Tariff
    required:
      - id
      - internalName
      - commercialName
      - type
    properties:
      id:
        type: string
      internalName:
        type: string
      commercialName:
        type: string
      commercialDescription:
        type: string
      powerPrices:
        type: array
        items:
          type: number
      energyPrices:
        type: array
        items:
          type: number
      provider:
        type: string
      type:
        type: string
        enum:
          - PVPC_2_0_TD
          - MERCADO_LIBRE_2_0_TD_FIJA
          - MERCADO_LIBRE_2_0_TD
          - MERCADO_LIBRE_3_0_TD
          - INDEXADA_2_0_TD
          - MERCADO_LIBRE_6_1_TD
          - OMIE_MARGEN
      solarPrice:
        type: number
        format: float
      margin:
        type: number
        format: float
  CreateTariff:
    type: object
    description: Tariff
    required:
      - internalName
      - commercialName
      - type
    properties:
      internalName:
        type: string
      commercialName:
        type: string
      commercialDescription:
        type: string
      powerPrices:
        type: array
        items:
          type: number
      energyPrices:
        type: array
        items:
          type: number
      provider:
        type: string
      type:
        type: string
        enum:
          - PVPC_2_0_TD
          - MERCADO_LIBRE_2_0_TD_FIJA
          - MERCADO_LIBRE_2_0_TD
          - MERCADO_LIBRE_3_0_TD
          - INDEXADA_2_0_TD
          - MERCADO_LIBRE_6_1_TD
          - OMIE_MARGEN
      solarPrice:
        type: number
        format: float
      margin:
        type: number
        format: float
  TariffEnergyPrices:
    type: object
    description: Tariff energy prices
    properties:
      prices:
        type: array
        items:
          type: object
          $ref: '#/definitions/TariffEnergyPrice'
    required:
      - prices
  TariffEnergyPrice:
    type: object
    description: Tariff energy price
    properties:
      date:
        type: string
        format: date-time
        description: UTC date and hour of the price. Will be truncated to hours
        example: '2025-01-11T10:00:00Z'
      price:
        type: number
        format: float
        description: Price in €/kWh
        example: 0.11
    required:
      - date
      - price
  HouseContractEnergyPriceRequest:
    type: object
    description: Request to put energy prices for a contract
    properties:
      prices:
        type: array
        description: List of energy prices and dates
        items:
          type: object
          $ref: '#/definitions/HouseContractEnergyPriceInput'
  HouseContractEnergyPriceInput:
    type: object
    description: Request to put energy prices for a contract
    properties:
      date:
        type: string
        format: date-time
        example: '2022-12-31T23:00:00'
        description: Date for the energy
      price:
        type: number
        description: Price of the energy
  AssignExternalContractToContractRequest:
    type: object
    description: Request to link a contract with an eternal id
    required:
      - contractId
      - externalContractId
    properties:
      contractId:
        type: string
      externalContractId:
        type: string
  SmartDevicesPower:
    type: object
    properties:
      subtype:
        type: string
      vendor:
        type: string
      power:
        type: number
        format: float
  StoreHouseEnergiesRequest:
    type: object
    required:
      - energies
    properties:
      energies:
        type: array
        items:
          type: object
          $ref: '#/definitions/EnergyEntry'
  EnergyEntry:
    type: object
    properties:
      wh:
        type: number
        format: float
      date:
        type: string
        format: date-time
      dateTo:
        type: string
        format: date-time
        description: 'Not mandatory, if not provided, dateTo is one hour more than date.'
    required:
      - date
      - wh
  InvoiceAnalysis:
    type: object
    properties:
      dni:
        type: string
        example: 1111111A
      name:
        type: string
        example: John
      surname:
        type: string
        example: Doe
      houseCity:
        type: string
        example: Madrid
      houseStreet:
        type: string
        example: Avenida
      houseNumber:
        type: string
        example: '53'
      houseProvince:
        type: string
        example: Madrid
      postalCode:
        type: string
        example: '28005'
      cups:
        type: string
        example: ES0000000000000000EYOF
      marketer:
        type: string
        example: Iberdrola
      contractedPowerP1:
        type: number
        format: float
        example: '4.6'
      contractedPowerP2:
        type: number
        format: float
        example: '4.6'
      maxPowerDemandedP1:
        type: number
        format: float
        example: '3.4'
      maxPowerDemandedP2:
        type: number
        format: float
        example: '3.5'
      energyConsumptionP1:
        type: number
        format: float
        example: '50.0'
      energyConsumptionP2:
        type: number
        format: float
        example: '152.0'
      energyConsumptionP3:
        type: number
        format: float
        example: '108.0'
      totalEnergyConsumption:
        type: number
        format: float
        example: '210.0'
      totalCost:
        type: number
        format: float
        example: '78.77'
  AnalyzeInvoice:
    type: object
    properties:
      invoiceUrl:
        type: string
        example: 'https://example/invoice-123'
  InvoiceAnalysisId:
    type: object
    properties:
      invoiceAnalysisId:
        type: string
        format: uuid
        example: 044b7fef-4a80-42ac-a8c6-addd9c9d86a4
  InvoiceTariffs:
    type: array
    items:
      $ref: '#/definitions/InvoiceTariff'
  InvoiceTariff:
    type: object
    required:
      - invoiceSaving
      - tariff
    properties:
      invoiceSaving:
        type: number
      tariff:
        $ref: '#/definitions/Tariff'
  Ticket:
    type: object
    description: Ticket
    properties:
      id:
        type: string
      tenantId:
        type: string
      userId:
        type: string
      houseId:
        type: string
      equipmentId:
        type: string
      alertId:
        type: string
      status:
        type: string
        enum:
          - NEW
          - OPEN
          - PENDING
          - SOLVED
          - CLOSED
      title:
        type: string
      description:
        type: string
      comments:
        type: array
      items:
        $ref: '#/definitions/Comment'
      createdAt:
        type: string
        format: date-time
      updatedAt:
        type: string
        format: date-time
    required:
      - id
      - tenantId
      - status
      - title
      - description
      - createdAt
      - updatedAt
  Comment:
    type: object
    properties:
      id:
        type: number
      ticketId:
        type: string
      message:
        type: string
      author:
        type: string
        enum:
          - USER
          - SUPPORT
      createdAt:
        type: string
        format: date-time
      updatedAt:
        type: string
        format: date-time
    required:
      - id
      - ticketId
      - message
      - author
      - createdAt
      - updatedAt
  UpdateTicketRequest:
    type: object
    properties:
      status:
        type: string
        enum:
          - NEW
          - OPEN
          - PENDING
          - SOLVED
          - CLOSED
    required:
      - status
  CommentRequest:
    type: object
    properties:
      message:
        type: string
    required:
      - message
  HouseEquipment:
    type: object
    properties:
      equipmentId:
        type: string
      integrationType:
        type: string
      vendor:
        type: string
  HouseEquipments:
    type: object
    properties:
      equipments:
        type: array
        items:
          $ref: '#/definitions/HouseEquipment'
  StorageEquipment:
    type: object
    description: Storage equipment data
    required:
      - status
    properties:
      status:
        type: string
        description: Equipment status
        enum:
          - ACTIVE
          - INACTIVE
      maxChargePower:
        type: number
        format: float
        description: Maximum charge power in W
        example: 100
      maxDischargePower:
        type: number
        format: float
        description: Maximum discharge power in W
        example: 100
      ratedCapacity:
        type: number
        format: float
        description: Rated capacity in kWh
        example: 50
  StorageEquipmentSoc:
    type: object
    description: Storage equipment state of charge
    required:
      - time
      - soc
    properties:
      time:
        type: string
        format: date-time
        description: Time of measurement
      soc:
        type: number
        format: float
        description: State of charge in percentage
  ScheduleStorageActionRequest:
    type: object
    description: Request to create a set of scheduled actions for a storage equipment
    properties:
      actions:
        type: array
        description: List of actions to be scheduled
        items:
          type: object
          $ref: '#/definitions/ScheduleStorageActionItem'
  ScheduleStorageActionItem:
    type: object
    properties:
      date:
        type: string
        format: date-time
        description: 'Date of the action in UTC format (e.g., 2023-10-01T12:00:00Z)'
      action:
        type: string
        description: Action to be performed on the storage equipment
        enum:
          - CHARGE
          - DISCHARGE
          - PAUSE
      targetSOC:
        type: number
        format: float
        description: Target state of charge in percentage
    required:
      - date
      - action
      - targetSOC
  EquipmentsPage:
    type: object
    description: Page of equipments
    properties:
      cursor:
        type: string
        format: uuid
        description: Cursor for next page request
      elements:
        type: array
        description: List of equipments
        items:
          type: object
          $ref: '#/definitions/Equipment'
    required:
      - elements
  Equipment:
    type: object
    required:
      - equipmentId
      - integrationId
      - vendor
    properties:
      equipmentId:
        type: string
        format: uuid
      integrationId:
        type: string
        format: uuid
      vendor:
        type: string
  HousesPage:
    type: object
    description: Page of houses
    properties:
      cursor:
        type: string
        format: uuid
        description: Cursor for next page request
      elements:
        type: array
        description: List of houses
        items:
          type: object
          $ref: '#/definitions/House'
    required:
      - elements
  House:
    type: object
    required:
      - houseId
    properties:
      houseId:
        type: string
        format: uuid
      cups:
        type: string
      address:
        type: string
      postalCode:
        type: string
  AuthorizeUserRequest:
    type: object
    properties:
      houseId:
        description: The ID of the house to authorize
        type: string
      authorizedUserId:
        description: The ID of the user to authorize
        type: string
      status:
        description: The authorization status
        type: string
        enum:
          - AUTHORIZED
          - REVOKED
    required:
      - houseId
      - authorizedUserId
      - status
