openapi: 3.0.3
info:
  title: Consulta y descarga de facturas eléctricas - API de Imagina Energía
  version: 1.0.0
  description: |
    Listado de facturas eléctricas y descarga de facturas normales del canal efectivo. Usa el JWT y
    X-Canal habituales. Los IDs son internos de Neuro; no son códigos de factura
    ni IDs de contratos. Gas no está incluido en estas operaciones.
servers:
  - url: https://pre-webhooks.imaginaenergia.com
    description: PRE
security:
  - BearerAuth: []
tags:
  - name: Facturas
paths:
  /facturas:
    get:
      operationId: listarFacturas
      tags: [Facturas]
      summary: Listar las facturas eléctricas del canal
      description: |
        Devuelve facturas emitidas y numeradas, ordenadas por fecha e ID
        descendentes. Los filtros se combinan con AND y usan coincidencia exacta.
        url_pdf indica la ruta pública para descargar el PDF normal. En facturas
        multipunto y albaranes es null: su descarga no está disponible.
        No devuelve URLs de almacenamiento ni datos personales del titular.
      parameters:
        - $ref: '#/components/parameters/XCanal'
        - name: pagina
          in: query
          schema: {type: integer, minimum: 1, default: 1}
        - name: por_pagina
          in: query
          schema: {type: integer, minimum: 1, maximum: 100, default: 10}
        - name: codigo
          in: query
          description: Código o número de factura, no su ID interno.
          schema: {type: string, minLength: 1, maxLength: 128}
        - name: cups
          in: query
          schema: {type: string, minLength: 1, maxLength: 128}
        - name: contrato_codigo
          in: query
          description: Código comercial del contrato, no su ID interno.
          schema: {type: string, minLength: 1, maxLength: 128}
      responses:
        '200':
          description: Página de facturas del canal.
          headers:
            X-Request-ID:
              schema: {type: string}
          content:
            application/json:
              schema:
                type: object
                required: [request_id, facturas, paginacion]
                properties:
                  request_id: {type: integer}
                  facturas:
                    type: array
                    items: {$ref: '#/components/schemas/Factura'}
                  paginacion:
                    type: object
                    required: [pagina, por_pagina, total, ultima_pagina, hay_mas]
                    properties:
                      pagina: {type: integer, minimum: 1}
                      por_pagina: {type: integer, minimum: 1, maximum: 100}
                      total: {type: integer, minimum: 0}
                      ultima_pagina: {type: integer, minimum: 1}
                      hay_mas: {type: boolean}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/InternalError'}
        '502': {$ref: '#/components/responses/UpstreamError'}
        '503': {$ref: '#/components/responses/Unavailable'}
        '504': {$ref: '#/components/responses/Timeout'}
  /factura/{id_factura}/pdf:
    get:
      operationId: descargarFacturaPDF
      tags: [Facturas]
      summary: Descargar el PDF de una factura eléctrica de un suministro
      description: |
        Utilice el id del listado o directamente su url_pdf. Neuro comprueba
        que el contrato de la factura pertenece al canal del token. El PDF puede
        componerse y quedar almacenado en Neuro en la primera descarga.
        No envía la factura a terceros ni modifica sus importes o estado.
        La descarga multipunto y de albaranes no está incluida.
      parameters:
        - $ref: '#/components/parameters/InvoiceId'
        - $ref: '#/components/parameters/XCanal'
      responses:
        '200': {$ref: '#/components/responses/PDF'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '500': {$ref: '#/components/responses/InternalError'}
        '502': {$ref: '#/components/responses/UpstreamError'}
        '503': {$ref: '#/components/responses/Unavailable'}
        '504': {$ref: '#/components/responses/Timeout'}
components:
  securitySchemes:
    BearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
  parameters:
    InvoiceId:
      name: id_factura
      in: path
      required: true
      description: ID interno de la factura eléctrica de un suministro.
      schema: {type: integer, minimum: 1}
    XCanal:
      name: X-Canal
      in: header
      description: Selector de canal por lista o master, solo para cuentas autorizadas; no sustituye el JWT.
      schema: {type: string}
  schemas:
    Factura:
      type: object
      required: [id, producto, url_pdf]
      properties:
        id: {type: integer, minimum: 1}
        codigo: {type: string, nullable: true}
        producto: {type: string, enum: [Electricidad]}
        tipo: {type: string, nullable: true}
        fecha: {type: string, nullable: true}
        fecha_desde: {type: string, nullable: true}
        fecha_hasta: {type: string, nullable: true}
        total:
          nullable: true
          oneOf:
            - {type: string}
            - {type: number}
        contrato_codigo: {type: string, nullable: true}
        cups: {type: string, nullable: true}
        url_pdf:
          type: string
          nullable: true
          description: Ruta relativa para descargar el PDF normal; null si la descarga no está disponible.
    Error:
      type: object
      required: [error]
      properties:
        error: {type: string}
        request_id: {type: integer, nullable: true}
  responses:
    PDF:
      description: PDF binario de hasta 20 MiB, servido con Cache-Control no-store.
      headers:
        Content-Disposition:
          schema: {type: string}
          description: Nombre seguro generado con el ID de la factura.
        X-Request-ID:
          schema: {type: string}
          description: Referencia de auditoría para soporte.
      content:
        application/pdf:
          schema: {type: string, format: binary}
    BadRequest:
      description: Parámetros inválidos, tipo de descarga incorrecto o Neuro no puede componer el PDF. No reintentar en bucle; revisar el tipo o contactar con soporte.
      content: &errorContent
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    Unauthorized:
      description: JWT inválido, ausente, caducado o selección de canal no autorizada.
      content: *errorContent
    Forbidden:
      description: El canal no tiene una credencial de acceso configurada.
      content: *errorContent
    NotFound:
      description: Factura inexistente, sin contrato o ajena al canal. No se revela cuál de estos casos se produjo.
      content: *errorContent
    RateLimited:
      description: Límite habitual de peticiones alcanzado; respete Retry-After.
    InternalError:
      description: Fallo interno o al guardar la auditoría; no se entrega el PDF.
      content: *errorContent
    UpstreamError:
      description: Neuro devolvió un error, un listado inválido, un archivo no PDF o una respuesta demasiado grande.
      content: *errorContent
    Unavailable:
      description: Configuración no disponible o Neuro rechaza la credencial del canal.
      content: *errorContent
    Timeout:
      description: Neuro no respondió a tiempo.
      content: *errorContent
