openapi: 3.0.3
info:
  title: Descarga de contratos eléctricos - API de Imagina Energía
  version: 1.0.0
  description: |
    Descarga de documentos contractuales existentes en Neuro. El id_contrato es el
    campo id devuelto por GET /contratos; no es el CUPS ni el código comercial.
    Se aplica el JWT y el canal efectivo de las demás operaciones de contratos,
    incluido X-Canal cuando la cuenta tiene la autorización correspondiente.
    Estas consultas no generan documentos ni inician firmas.
servers:
  - url: https://pre-webhooks.imaginaenergia.com
    description: PRE
security:
  - BearerAuth: []
tags:
  - name: Contratos
paths:
  /contrato/{id_contrato}/pdf:
    get:
      operationId: descargarContratoPDF
      tags: [Contratos]
      summary: Descargar el PDF original del contrato eléctrico
      description: |
        Devuelve el PDF original del contrato junto con los anexos pendientes de
        firma, tal como lo sirve Neuro. No incluye anexos ya firmados ni los
        adjuntos de identidad, bancarios o evidencias de firma. Para obtener
        la copia firmada, utilice /contrato/{id_contrato}/firmado.
        El contrato debe ser accesible para el canal autenticado o seleccionado
        mediante la suplantación existente. Un contrato ajeno devuelve 404.
      parameters:
        - $ref: '#/components/parameters/ContractId'
        - $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':
          description: Límite de peticiones de la API alcanzado; respete Retry-After.
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/Unavailable'
        '504':
          $ref: '#/components/responses/Timeout'
  /contrato/{id_contrato}/firmado:
    get:
      operationId: descargarContratoFirmado
      tags: [Contratos]
      summary: Descargar la copia firmada del contrato eléctrico
      description: |
        Devuelve la copia firmada que sirve Neuro, tanto para firma digital como
        para un documento adjuntado ya firmado en papel. La selección documental
        corresponde a Neuro; esta API no ordena ni selecciona documentos del expediente.
        No sustituye una copia firmada ausente por el original ni por evidencias.
        Devuelve 404 si el canal no puede acceder al contrato o no hay copia firmada
        disponible. Esta consulta no solicita una firma ni modifica el contrato.
      parameters:
        - $ref: '#/components/parameters/ContractId'
        - $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':
          description: Límite de peticiones de la API alcanzado; respete Retry-After.
        '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:
    ContractId:
      name: id_contrato
      in: path
      required: true
      description: ID interno de Neuro obtenido del campo id de GET /contratos.
      schema:
        type: integer
        minimum: 1
      example: 12345
    XCanal:
      name: X-Canal
      in: header
      required: false
      description: |
        Selector opcional del canal conforme a la autenticación habitual: UUID de
        autorización para impersonar_canal o selector master para canal_master.
        No concede permisos por sí mismo y no sustituye el JWT del usuario.
      schema:
        type: string
  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
        request_id:
          type: integer
          nullable: true
          description: Referencia de auditoría cuando la petición pudo registrarse.
  responses:
    PDF:
      description: Archivo PDF. Guárdelo como binario, no como JSON. Máximo 20 MiB.
      headers:
        Content-Disposition:
          schema:
            type: string
          description: Descarga como adjunto con un nombre generado por la API.
        Cache-Control:
          schema:
            type: string
            example: no-store
        X-Request-ID:
          schema:
            type: string
          description: Identificador de auditoría para soporte.
      content:
        application/pdf:
          schema:
            type: string
            format: binary
    BadRequest:
      description: El ID del contrato debe ser positivo.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: JWT ausente, inválido o caducado, o suplantación no autorizada.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: El canal autenticado no tiene una credencial de acceso configurada.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Contrato inexistente o ajeno al canal, o documento solicitado no disponible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: El documento contractual no está disponible
            request_id: 123
    InternalError:
      description: Error interno o de registro de la solicitud.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UpstreamError:
      description: Neuro devolvió un error, una ficha de contrato no válida, un archivo no PDF o una respuesta demasiado grande.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: El servicio de descarga no está disponible o Neuro rechaza el acceso documental del canal. Contacte con soporte.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Timeout:
      description: Neuro no respondió dentro del tiempo de espera.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
