openapi: 3.1.0
info:
  title: Contratos de gas - API de Imagina Energía
  version: 0.4.0
  description: |-
    Consulta los datos de un suministro, las tarifas y los precios del canal, solicita el alta de un contrato de gas y gestiona su documentación y firma.

    Cada alta corresponde a un único CUPS. Utiliza un token JWT en Authorization y una Idempotency-Key estable para cada alta, documento o solicitud de firma. El canal se obtiene de la autenticación; X-Canal permite seleccionar otro canal únicamente con los permisos correspondientes.

    Las rutas residencial y empresa pueden responder de forma síncrona o asíncrona. callback_url activa el modo asíncrono; su dominio HTTPS debe estar autorizado. RAW requiere callback_url. Revisa credit_result, contrato_result y firma_result: HTTP 200 no significa por sí solo que el contrato se haya creado o firmado.

    Guía y ejemplos: [Contratos de gas](contrato_gas.html). Los IDs y datos de los ejemplos son ilustrativos: consulta las maestras, tarifas y precios de tu canal antes de enviar una solicitud.
servers:
- url: https://pre-webhooks.imaginaenergia.com
security:
- bearerAuth: []
tags:
- name: Gas
  description: Consultas, contratación, seguimiento, documentos y firma de suministros de gas.
paths:
  /contrato/gas/residencial:
    post:
      operationId: altaGasResidencial
      tags:
      - Gas
      summary: Alta de gas para persona física
      description: |-
        Envía los datos del titular, contactos, suministro y condiciones. cliente.id_tipo_persona debe ser 1. Los identificadores de tarifa y CNAE deben corresponder a los catálogos del canal. Se admite IBAN español válido.

        Sin callback_url, la respuesta contiene el resultado. Con callback_url, la solicitud se procesa de forma asíncrona. El consumo aportado debe ser un entero positivo en kWh y tiene prioridad sobre SIPS. Si se informa en el contrato y en el punto, ambos valores deben coincidir. Si falta en ambos, se utiliza el de SIPS; sin consumo disponible se devuelve un error. Para un alta nueva sin SIPS, informa operacion.datos_suministro_aportados=true y aporta los datos del suministro.

        El scoring se ejecuta salvo operacion.no_credit_check=true. La firma se solicita tras el alta salvo operacion.no_enviar_firma=true. Los destinatarios y el canal de firma se indican en los contactos.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/XCanal'
      requestBody:
        $ref: '#/components/requestBodies/GasRequest'
      responses:
        '200':
          $ref: '#/components/responses/Finished'
        '202':
          $ref: '#/components/responses/Queued'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '413':
          description: Payload superior a 256 KiB
        '422':
          description: SIPS no proporciona consumo con unidad reconocida
        '501':
          description: Notificaciones de cambios de contrato no integradas
        '502':
          $ref: '#/components/responses/Error'
        '503':
          description: Servicio de gas no disponible para esta petición o canal.
        '504':
          $ref: '#/components/responses/Uncertain'
  /contrato/gas/empresa:
    post:
      operationId: altaGasEmpresa
      tags:
      - Gas
      summary: Alta de gas para empresa
      description: |-
        cliente.id_tipo_persona debe ser 2. Informa razon_social y NIF de la empresa. Incluye al menos un representante físico en contactos, con id_tipo_contacto=1, identificación, nombre, apellidos y email o teléfono de firma.

        El resto del flujo y las respuestas coinciden con el alta residencial. Los datos del representante no sustituyen los del titular jurídico.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/XCanal'
      requestBody:
        $ref: '#/components/requestBodies/GasCompanyRequest'
      responses:
        '200':
          $ref: '#/components/responses/Finished'
        '202':
          $ref: '#/components/responses/Queued'
        default:
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
  /contrato/gas/raw:
    post:
      operationId: altaGasRaw
      tags:
      - Gas
      summary: Alta de gas con IDs de maestras y callback
      description: |-
        Utiliza la misma estructura de titular, contactos, suministro y condiciones, con identificadores de maestras. Requiere callback_url HTTPS con dominio autorizado. El canal se obtiene del token.

        Una solicitud nueva válida se acepta con HTTP 202. Una repetición con la misma clave puede devolver un resultado ya finalizado. callback_exec=false permite consultar el resultado sin recibir la notificación, pero callback_url sigue siendo obligatorio en esta ruta.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/XCanal'
      requestBody:
        $ref: '#/components/requestBodies/GasRawRequest'
      responses:
        '202':
          $ref: '#/components/responses/Queued'
        '200':
          $ref: '#/components/responses/Finished'
        default:
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
  /tarifas/gas:
    get:
      operationId: tarifasGas
      tags:
      - Gas
      summary: Consultar tarifas de gas del canal
      parameters:
      - $ref: '#/components/parameters/XCanal'
      responses:
        '200':
          description: Catálogo por tarifa y grupo del canal; precio null hasta consultar precios calculados
          content:
            application/json:
              schema:
                type: object
                required:
                - producto
                - tarifas
                properties:
                  producto:
                    const: gas
                  tarifas:
                    type: array
                    items:
                      type: object
              example:
                producto: gas
                tarifas:
                - id_tarifa_precios: 30
                  id_grupo_tarifa: '7'
                  nombre: Gas fija
                  peaje_acceso:
                  - R2
                  tipo_tarifa: fija
                  precio: null
        default:
          $ref: '#/components/responses/Error'
      description: Devuelve una fila por tarifa y grupo del canal. Conserva id_tarifa_precios, id_grupo_tarifa,
        peajes y metadatos comerciales. Consulta /tarifas/gas/precios para obtener importes. Si una tarifa
        pertenece a varios grupos, selecciona operacion.id_grupo_tarifa al dar de alta.
  /maestras/gas:
    get:
      operationId: maestrasGas
      tags:
      - Gas
      summary: Consultar maestras de gas
      responses:
        '200':
          description: Catálogos CNAE gas
          tipos de vía: null
          identificadores: null
          personas: null
          pago y geografía: null
          content:
            application/json:
              schema:
                type: object
                properties:
                  producto:
                    const: gas
                  cnae:
                    type: array
                    items:
                      type: object
                  tipos_via:
                    type: array
                    items:
                      type: object
                  tipos_identificador:
                    type: array
                    items:
                      type: object
                  tipos_persona:
                    type: array
                    items:
                      type: object
                  modos_pago:
                    type: array
                    items:
                      type: object
                  provincias:
                    type: array
                    items:
                      type: object
                  municipios:
                    type: array
                    items:
                      type: object
              example:
                producto: gas
                cnae:
                - id: 628
                  codigo: '9820'
                  descripcion: Actividad de ejemplo
                tipos_via:
                - id: 18
                  codigo: CL
                  descripcion: Calle
                tipos_identificador:
                - id: 4
                  descripcion: NIF
                tipos_persona:
                - id: 1
                  descripcion: Física
                - id: 2
                  descripcion: Jurídica
                modos_pago:
                - id: 2
                  nombre: Domiciliación
                provincias:
                - id: 28
                  codigo: '28'
                  nombre: Madrid
                municipios:
                - id: 4369
                  id_provincia: 28
                  nombre: Madrid
        '503':
          description: El catálogo CNAE de gas no está cargado o las maestras no están disponibles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        default:
          $ref: '#/components/responses/Error'
      description: Devuelve los catálogos cnae, tipos_via, tipos_identificador, tipos_persona, modos_pago,
        provincias y municipios. Utiliza sus IDs en la solicitud y el codigo del tipo de vía. El CNAE
        debe proceder del catálogo de gas.
      parameters:
      - $ref: '#/components/parameters/XCanal'
  /tarifas/gas/precios:
    post:
      operationId: preciosCalculadosGas
      tags:
      - Gas
      summary: Consultar precios de gas para un peaje
      description: |-
        Envía peaje con el código exacto R1–R9, L0 o L1. tipo_distribucion es opcional: distribucion o monocliente para consulta de plantas satélite; omitido o null para red convencional. No se admiten fecha, canal, tarifa ni márgenes en la petición.

        Devuelve las tarifas ofertables por el canal con precios del día de la consulta. Fijo personalizado en €/mes y variable de tarifa fija en €/kWh; no incluyen impuestos, márgenes del canal ni conceptos adicionales de facturación. Los conceptos se devuelven por separado.

        En indexadas y mixtas, el precio de energía y sus unidades se devuelven null: no hay precio cerrado. tarifas=[] significa que no hay oferta para ese peaje. La consulta de precios de una planta satélite o un peaje adicional no habilita por sí sola su contratación.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - peaje
              properties:
                peaje:
                  type: string
                  enum:
                  - R1
                  - R2
                  - R3
                  - R4
                  - R5
                  - R6
                  - R7
                  - R8
                  - R9
                  - L0
                  - L1
                tipo_distribucion:
                  type:
                  - string
                  - 'null'
                  enum:
                  - distribucion
                  - monocliente
                  - null
            example:
              peaje: R2
      responses:
        '200':
          description: Precios base y condiciones del canal; tarifas vacío si no hay oferta
          content:
            application/json:
              schema:
                type: object
                required:
                - producto
                - fecha
                - peaje
                - tarifas
                - incluye_margenes_canal
                - incluye_impuestos
                - incluye_conceptos_facturables
                properties:
                  producto:
                    const: gas
                  fecha:
                    type: string
                    format: date
                  peaje:
                    type: string
                  tipo_distribucion:
                    type:
                    - string
                    - 'null'
                  incluye_margenes_canal:
                    const: false
                  incluye_impuestos:
                    const: false
                  incluye_conceptos_facturables:
                    const: false
                  tarifas:
                    type: array
                    items:
                      type: object
                      required:
                      - id_tarifa_precios
                      - nombre
                      - tipo_tarifa
                      - precio
                      - energia_precio_cerrado
                      properties:
                        id_tarifa_precios:
                          type: integer
                        id_grupo_tarifa:
                          type:
                          - integer
                          - string
                          - 'null'
                        tipo_tarifa:
                          enum:
                          - fija
                          - indexada
                          - mixta
                        energia_precio_cerrado:
                          type: boolean
                        precio:
                          type: object
                          properties:
                            precio_termino_fijo_personalizado:
                              type: string
                            unidades_termino_fijo_personalizado:
                              const: €/mes
                            precio_termino_variable_personalizado:
                              type:
                              - string
                              - 'null'
                            unidades_termino_variable_personalizado:
                              enum:
                              - €/kWh
                              - null
              example:
                producto: gas
                peaje: R2
                tipo_distribucion: null
                fecha: '2026-11-04'
                incluye_margenes_canal: false
                incluye_impuestos: false
                incluye_conceptos_facturables: false
                fuente: neuro_precios_calculados
                tarifas:
                - id_tarifa_precios: 30
                  id_grupo_tarifa: '7'
                  nombre: Gas fija
                  peaje_acceso:
                  - R2
                  tipo_tarifa: fija
                  energia_precio_cerrado: true
                  duracion_meses_min: 12
                  duracion_meses_max: 24
                  prorroga_tacita_config: forzar_si
                  conceptos_facturables_tarifa: []
                  conceptos_facturables_sistema: []
                  precio:
                    tarifa_id: 30
                    peaje: R2
                    planta_satelite: false
                    precio_termino_fijo_personalizado: '6.793137'
                    unidades_termino_fijo_personalizado: €/mes
                    precio_termino_variable_personalizado: '0.06024'
                    unidades_termino_variable_personalizado: €/kWh
        '400':
          description: Peaje o campos de consulta no válidos
        '502':
          description: Precio o unidades de Neuro fuera del contrato documentado
        default:
          $ref: '#/components/responses/Error'
      parameters:
      - $ref: '#/components/parameters/XCanal'
  /sips/gas/{cups}:
    get:
      operationId: sipsGas
      tags:
      - Gas
      summary: Consultar SIPS de gas por CUPS
      description: Devuelve disponibilidad, datos del suministro, consumo_anual_wh, consumo_anual_kwh
        y peaje_acceso. Con disponible=false no hay ficha SIPS. importe_scoring es una valoración de riesgo
        en EUR, no el precio de la tarifa ni un coste de factura. La valoración admite los peajes R1–R6.
      parameters:
      - name: cups
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/XCanal'
      responses:
        '200':
          description: Consumo anual en Wh y kWh
          peaje y fuente: null
          content:
            application/json:
              schema:
                type: object
                properties:
                  producto:
                    const: gas
                  cups:
                    type: string
                  disponible:
                    type: boolean
                  data:
                    type:
                    - object
                    - 'null'
                    additionalProperties: true
                  consumo_anual_wh:
                    type: integer
                  consumo_anual_kwh:
                    type: number
                  unidad_consumo:
                    const: kWh
                  peaje_acceso:
                    type: string
                  importe_scoring:
                    type: number
                  unidad_importe_scoring:
                    const: EUR
                  criterio_scoring:
                    type: string
                  fuente:
                    type: string
                required:
                - producto
                - cups
                - disponible
                - unidad_consumo
              examples:
                conSips:
                  value:
                    producto: gas
                    cups: ES0021000000000000AA
                    disponible: true
                    data:
                      consumo_anual: '7400000'
                      codigo_peaje_en_vigor: R2
                    consumo_anual_wh: 7400000
                    consumo_anual_kwh: 7400
                    unidad_consumo: kWh
                    peaje_acceso: R2
                    importe_scoring: 444.74
                    unidad_importe_scoring: EUR
                    criterio_scoring: tabla_gas_por_peaje
                    fuente: sips
                sinSips:
                  value:
                    producto: gas
                    cups: ES0021000000000000AA
                    disponible: false
                    data: null
                    unidad_consumo: kWh
        default:
          $ref: '#/components/responses/Error'
  /contrato/gas/solicitudes/{request_id}:
    get:
      operationId: estadoSolicitudGas
      tags:
      - Gas
      summary: Consultar una solicitud de alta
      description: Consulta la solicitud con el request_id de la respuesta inicial. Solo devuelve solicitudes
        del canal autorizado. result contiene el resultado cuando está disponible; callback informa del
        estado de entrega de la notificación, si se solicitó. Un estado uncertain requiere revisión antes
        de cualquier nuevo intento.
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
      - $ref: '#/components/parameters/XCanal'
      responses:
        '200':
          description: Estado, resultado y estado de entrega de callback
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GasStatus'
              example:
                request_id: 12345
                producto: gas
                state: completed
                result:
                  request_id: 12345
                  referencia_externa: gas-prueba-001
                  producto: gas
                  credit_result:
                    result_operation: Aprobado
                  contrato_result:
                    result_operation: OK
                    content:
                      id: 9001
                      codigo: GAS-0001
                  firma_result:
                    result_operation: SKIPPED
                callback: null
        '404':
          description: Solicitud inexistente o de otro canal
        default:
          $ref: '#/components/responses/Error'
  /contrato/gas/{contract_id}/pdf:
    parameters:
    - name: contract_id
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
    get:
      operationId: pdfContratoGas
      tags:
      - Gas
      summary: Descargar el contrato individual en PDF
      description: Descarga el PDF del contrato perteneciente al canal. La respuesta es binaria, con Content-Type
        application/pdf; guárdala como fichero. La descarga no solicita firma ni modifica el contrato.
      responses:
        '200':
          description: PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/Error'
      parameters:
      - $ref: '#/components/parameters/XCanal'
  /contrato/gas/{contract_id}/firmado:
    parameters:
    - name: contract_id
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
    get:
      operationId: pdfFirmadoGas
      tags:
      - Gas
      summary: Descargar el contrato firmado
      description: Descarga el PDF firmado disponible para el contrato. Devuelve 404 cuando no existe
        contrato autorizado o documento disponible. La descarga no inicia un circuito de firma.
      responses:
        '200':
          description: PDF firmado
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          description: Contrato o documento firmado no disponible
        default:
          $ref: '#/components/responses/Error'
      parameters:
      - $ref: '#/components/parameters/XCanal'
  /contrato/gas/{contract_id}/firma:
    parameters:
    - name: contract_id
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
    get:
      operationId: estadoFirmaGas
      tags:
      - Gas
      summary: Consultar el estado de firma
      responses:
        '200':
          description: Estado del circuito solicitado o consulta histórica del contrato si HERS no tiene una solicitud registrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GasSignatureStatus'
              example:
                producto: gas
                origen: eevidsign
                alcance: circuito
                data:
                  circuito_id: 12345
                  finalizado: false
                  estado: pendiente
                  fecha_inicio: '2026-11-12T11:15:52+01:00'
                  fecha_completado: null
                  fecha_cancelacion: null
                  detalle_entrega_disponible: false
                  contadores:
                    total: 1
                    firmados: 0
                    enviados: 0
                    pendientes: 1
                    error: 0
                  firmantes:
                  - nombre: Persona Ejemplo
                    email: firma@example.com
                    estado: pendiente
                    fecha_firma: null
                    envio: null
                    destino: null
                    motivo_error: null
        '409':
          description: La última solicitud de firma aún no tiene un circuito confirmado. No se devuelve una firma anterior en su lugar.
        '502':
          description: No se pudo consultar el circuito concreto o el proveedor devolvió datos incompatibles. No se sustituye por otro circuito firmado.
        '503':
          description: La consulta por circuito requiere las credenciales eEvidSign ya utilizadas para electricidad.
        default:
          $ref: '#/components/responses/Error'
      description: |-
        Sin parámetros, sigue el último circuito solicitado por HERS para este contrato y canal, tanto en el alta automática como con POST /firma. Consulta ese circuito directamente en eEvidSign, igual que la consulta de electricidad por circuito_id. Una firma histórica del contrato no completa una solicitud nueva.

        circuito_id permite seguir una solicitud concreta. Debe estar registrada por HERS para este contrato y canal; un circuito ajeno o desconocido devuelve 404. Un nuevo intento sin circuito confirmado devuelve 409, sin retroceder a una firma anterior. Reintentar un POST con su misma Idempotency-Key no lo convierte en una solicitud nueva.

        origen=eevidsign y alcance=circuito identifican la consulta concreta. data.fecha_inicio, data.fecha_completado y firmantes[].fecha_firma proceden de ese circuito y son null cuando no constan. finalizado depende del estado global, no de sumar firmantes. Una cancelación no se presenta como firma completada.

        eEvidSign no informa de entrega de email/SMS en estas consultas: detalle_entrega_disponible=false, envio/destino/motivo_error=null, contadores.enviados y error=0; los firmantes sin completar se cuentan como pendientes, sin afirmar entrega. El email identifica al firmante y no confirma el canal de envío utilizado.

        Solo si HERS no tiene ninguna solicitud de firma registrada se conserva la consulta de Neuro por contrato, con origen=neuro y alcance=contrato. Neuro prioriza un circuito histórico firmado, aunque haya otro más reciente; ese resultado no acredita una solicitud concreta ni garantiza fechas.

        Es un GET sin cuerpo y sin Idempotency-Key. No abre circuitos ni envía avisos. Si falla la consulta concreta no se usa la firma histórica como alternativa.
      parameters:
      - $ref: '#/components/parameters/XCanal'
      - name: circuito_id
        in: query
        required: false
        description: Circuito devuelto al solicitar firma. Debe pertenecer a una solicitud registrada por HERS para este contrato y canal.
        schema:
          type: integer
          minimum: 1
    post:
      operationId: solicitarFirmaGas
      tags:
      - Gas
      summary: Solicitar la firma del contrato
      description: |-
        Envía el POST sin cuerpo y con una Idempotency-Key propia de esta operación. Se utilizan los contactos y destinos que constan en el contrato; esta petición no admite otros destinatarios.

        La solicitud puede avisar al cliente. state=completed confirma la solicitud del circuito, no la firma del cliente. Si el resultado es incierto, consulta el estado de firma y solicita revisión; no repitas con otra clave.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/XCanal'
      responses:
        '200':
          description: state=completed, data.circuito_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GasDocumentOperation'
              example:
                state: completed
                producto: gas
                data:
                  circuito_id: 12345
        '202':
          description: Operación reservada pendiente de conciliación
          no reenviada: null
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GasDocumentOperation'
              example:
                state: uncertain
                error: Operación pendiente de conciliación; no se ha repetido.
        '409':
          description: Clave con otro contenido u operación anterior incierta
        default:
          $ref: '#/components/responses/Error'
  /contrato/gas/{contract_id}/documentos:
    parameters:
    - name: contract_id
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
    post:
      operationId: adjuntarDocumentoGas
      tags:
      - Gas
      summary: Adjuntar un PDF al contrato
      description: |-
        Envía multipart/form-data con fichero PDF (máximo 20 MiB), tipo_fichero y una Idempotency-Key propia. Se admite el contrato creado o una matriz existente, siempre que pertenezca al canal.

        tipo_fichero=34 incorpora un anexo. tipo_fichero=11 con fecha_firma incorpora un contrato firmado en papel y puede actualizar la fecha de firma. Si el contrato todavía no está firmado, omite fecha_firma; no uses una fecha de ejemplo, la de subida ni la de solicitud como fecha de firma. fecha_documento y fecha_firma usan AAAA-MM-DD. obligatorio_firma admite 0 o 1.

        La subida no solicita por sí sola la firma digital. Un resultado incierto debe revisarse antes de volver a adjuntar el documento.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/XCanal'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              required:
              - fichero
              - tipo_fichero
              properties:
                fichero:
                  type: string
                  format: binary
                tipo_fichero:
                  type: integer
                  enum:
                  - 11
                  - 34
                  - 16
                  - 17
                  - 6
                  - 8
                descripcion:
                  type: string
                fecha_documento:
                  type: string
                  format: date
                fecha_firma:
                  type: string
                  format: date
                obligatorio_firma:
                  type: string
                  enum:
                  - '0'
                  - '1'
                  default: '0'
      responses:
        '200':
          description: Documento incorporado o resultado de la misma clave
          sin duplicar subida: null
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GasDocumentOperation'
              example:
                state: completed
                producto: gas
                data:
                  id: 12
                  contrato_id: 9001
                  estado: Firmado
                  tipo_fichero_id: 11
                  fecha_firma: '2026-11-04'
        '202':
          description: Operación reservada pendiente de conciliación
        '413':
          description: PDF superior a 20 MiB
        '409':
          description: Clave con otro contenido u operación anterior incierta
        default:
          $ref: '#/components/responses/Error'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: Clave única por canal y operación, de 8 a 128 caracteres. Conserva la misma clave y
        contenido al recuperar una respuesta perdida. Reutilizarla con otro contenido o modalidad devuelve
        409. Usa una clave distinta para cada nueva alta, documento o solicitud de firma.
      schema:
        type: string
        pattern: ^[A-Za-z0-9._:-]{8,128}$
    XCanal:
      name: X-Canal
      in: header
      required: false
      description: Selección opcional de otro canal. Requiere autorización de impersonación; si se omite,
        se utiliza el canal asociado al token.
      schema:
        type: string
  requestBodies:
    GasRequest:
      required: true
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/GasInput'
            - type: object
              properties:
                cliente:
                  type: object
                  properties:
                    id_tipo_persona:
                      enum:
                      - 1
                      - '1'
          example:
            referencia_externa: gas-prueba-001
            cliente:
              nombre: Persona
              primer_apellido: Prueba
              segundo_apellido: ''
              direccion:
                pais: España
                calle: Mayor
                id_municipio: 4369
                id_provincia: 28
                numero_finca: '1'
                codigo_postal: '28001'
                aclarador_finca: ''
                tipo_via_codigo: CL
              prefijo_1: '34'
              telefono_1: '600000000'
              email_factura: prueba@example.com
              envio_factura: false
              identificador: 12345678Z
              id_tipo_persona: 1
              idioma_plantilla: ES
              correo_electronico: prueba@example.com
              id_tipo_identificador: 4
              aviso_modificacion_precios: false
            contactos:
            - contacto:
                email:
                - prueba@example.com
                nombre: Persona
                telefonos:
                - numero: '600000000'
                  extension: '34'
                tlf_firma: '600000000'
                email_firma: prueba@example.com
                identificador: 12345678Z
                id_canal_envio: 1
                id_tipo_persona: 1
                primer_apellido: Prueba
                segundo_apellido: ''
                id_tipo_identificador: 4
              email_factura: prueba@example.com
              envio_factura: true
              id_tipo_contacto: 9
              envio_factura_papel: false
              aviso_modificacion_precios: false
              email_modificacion_precios: prueba@example.com
            punto_suministro:
              cups: ES0021000000000000AA
              pais: España
              calle: Mayor
              telemedida: false
              municipio_id: 4369
              numero_finca: '1'
              provincia_id: 28
              codigo_postal: '28001'
              aclarador_finca: ''
              tipo_via_codigo: CL
              consumo_anual_estimado: '7400'
            contrato_suministro:
              dias: 0
              iban: ES9121000418450200051332
              anyos: 0
              meses: 12
              cnae_id: 628
              tarifas:
              - id_tarifa_precios: 30
              bic_swift: CAIXESBBXXX
              info_alta: si
              telemedida: false
              info_caudal: no lo se
              nombre_pago: Persona Prueba
              info_titular: 'no'
              modo_pago_id: 2
              peaje_acceso: R2
              periodicidad: bimestral
              tipo_mandato: CORE
              dias_denuncia: 30
              etiquetas_canal: []
              frecuencia_pago: R
              planta_satelite: false
              prorroga_tacita: false
              tipo_inicio_info: cuanto_antes
              vivienda_habitual: true
              identificador_pago: 12345678Z
              tipo_dias_denuncia: N
              id_tipo_plazo_cobro: 2
              dias_meses_plazo_pago: D
              naturaleza_suministro: firme
              consumo_anual_estimado: '7400'
              fecha_fija_fin_contrato: false
              impuestos_hidrocarburos:
              - valores:
                - tipo: no_carburante
                  porcentaje: 100
                  exencion_impuesto_hc: false
                descripcion: Impuesto especial hidrocarburos
                fecha_desde: '2026-01-01'
                fecha_hasta: '5000-01-01'
              inicio_fecha_activacion: true
              id_tipo_identificador_pago: 4
              valor_dias_meses_plazo_pago: 10
            operacion:
              no_enviar_firma: true
              no_credit_check: false
    GasCompanyRequest:
      required: true
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/GasInput'
            - type: object
              properties:
                cliente:
                  type: object
                  properties:
                    id_tipo_persona:
                      enum:
                      - 2
                      - '2'
          example:
            referencia_externa: gas-prueba-001
            cliente:
              direccion:
                pais: España
                calle: Mayor
                id_municipio: 4369
                id_provincia: 28
                numero_finca: '1'
                codigo_postal: '28001'
                aclarador_finca: ''
                tipo_via_codigo: CL
              prefijo_1: '34'
              telefono_1: '600000000'
              email_factura: prueba@example.com
              envio_factura: false
              identificador: B12345674
              id_tipo_persona: 2
              idioma_plantilla: ES
              correo_electronico: prueba@example.com
              id_tipo_identificador: 4
              aviso_modificacion_precios: false
              razon_social: Empresa Ejemplo, S.L.
            contactos:
            - contacto:
                email:
                - prueba@example.com
                nombre: Persona
                telefonos:
                - numero: '600000000'
                  extension: '34'
                tlf_firma: '600000000'
                email_firma: prueba@example.com
                identificador: 12345678Z
                id_canal_envio: 1
                id_tipo_persona: 1
                primer_apellido: Prueba
                segundo_apellido: ''
                id_tipo_identificador: 4
              email_factura: prueba@example.com
              envio_factura: true
              id_tipo_contacto: 1
              envio_factura_papel: false
              aviso_modificacion_precios: false
              email_modificacion_precios: prueba@example.com
            punto_suministro:
              cups: ES0021000000000000AA
              pais: España
              calle: Mayor
              telemedida: false
              municipio_id: 4369
              numero_finca: '1'
              provincia_id: 28
              codigo_postal: '28001'
              aclarador_finca: ''
              tipo_via_codigo: CL
              consumo_anual_estimado: '7400'
            contrato_suministro:
              dias: 0
              iban: ES9121000418450200051332
              anyos: 0
              meses: 12
              cnae_id: 628
              tarifas:
              - id_tarifa_precios: 30
              bic_swift: CAIXESBBXXX
              info_alta: si
              telemedida: false
              info_caudal: no lo se
              nombre_pago: Persona Prueba
              info_titular: 'no'
              modo_pago_id: 2
              peaje_acceso: R2
              periodicidad: bimestral
              tipo_mandato: CORE
              dias_denuncia: 30
              etiquetas_canal: []
              frecuencia_pago: R
              planta_satelite: false
              prorroga_tacita: false
              tipo_inicio_info: cuanto_antes
              vivienda_habitual: true
              identificador_pago: 12345678Z
              tipo_dias_denuncia: N
              id_tipo_plazo_cobro: 2
              dias_meses_plazo_pago: D
              naturaleza_suministro: firme
              consumo_anual_estimado: '7400'
              fecha_fija_fin_contrato: false
              impuestos_hidrocarburos:
              - valores:
                - tipo: no_carburante
                  porcentaje: 100
                  exencion_impuesto_hc: false
                descripcion: Impuesto especial hidrocarburos
                fecha_desde: '2026-01-01'
                fecha_hasta: '5000-01-01'
              inicio_fecha_activacion: true
              id_tipo_identificador_pago: 4
              valor_dias_meses_plazo_pago: 10
            operacion:
              no_enviar_firma: true
              no_credit_check: false
    GasRawRequest:
      required: true
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/GasInput'
            - type: object
              required:
              - callback_url
          example:
            referencia_externa: gas-prueba-001
            cliente:
              nombre: Persona
              primer_apellido: Prueba
              segundo_apellido: ''
              direccion:
                pais: España
                calle: Mayor
                id_municipio: 4369
                id_provincia: 28
                numero_finca: '1'
                codigo_postal: '28001'
                aclarador_finca: ''
                tipo_via_codigo: CL
              prefijo_1: '34'
              telefono_1: '600000000'
              email_factura: prueba@example.com
              envio_factura: false
              identificador: 12345678Z
              id_tipo_persona: 1
              idioma_plantilla: ES
              correo_electronico: prueba@example.com
              id_tipo_identificador: 4
              aviso_modificacion_precios: false
            contactos:
            - contacto:
                email:
                - prueba@example.com
                nombre: Persona
                telefonos:
                - numero: '600000000'
                  extension: '34'
                tlf_firma: '600000000'
                email_firma: prueba@example.com
                identificador: 12345678Z
                id_canal_envio: 1
                id_tipo_persona: 1
                primer_apellido: Prueba
                segundo_apellido: ''
                id_tipo_identificador: 4
              email_factura: prueba@example.com
              envio_factura: true
              id_tipo_contacto: 9
              envio_factura_papel: false
              aviso_modificacion_precios: false
              email_modificacion_precios: prueba@example.com
            punto_suministro:
              cups: ES0021000000000000AA
              pais: España
              calle: Mayor
              telemedida: false
              municipio_id: 4369
              numero_finca: '1'
              provincia_id: 28
              codigo_postal: '28001'
              aclarador_finca: ''
              tipo_via_codigo: CL
              consumo_anual_estimado: '7400'
            contrato_suministro:
              dias: 0
              iban: ES9121000418450200051332
              anyos: 0
              meses: 12
              cnae_id: 628
              tarifas:
              - id_tarifa_precios: 30
              bic_swift: CAIXESBBXXX
              info_alta: si
              telemedida: false
              info_caudal: no lo se
              nombre_pago: Persona Prueba
              info_titular: 'no'
              modo_pago_id: 2
              peaje_acceso: R2
              periodicidad: bimestral
              tipo_mandato: CORE
              dias_denuncia: 30
              etiquetas_canal: []
              frecuencia_pago: R
              planta_satelite: false
              prorroga_tacita: false
              tipo_inicio_info: cuanto_antes
              vivienda_habitual: true
              identificador_pago: 12345678Z
              tipo_dias_denuncia: N
              id_tipo_plazo_cobro: 2
              dias_meses_plazo_pago: D
              naturaleza_suministro: firme
              consumo_anual_estimado: '7400'
              fecha_fija_fin_contrato: false
              impuestos_hidrocarburos:
              - valores:
                - tipo: no_carburante
                  porcentaje: 100
                  exencion_impuesto_hc: false
                descripcion: Impuesto especial hidrocarburos
                fecha_desde: '2026-01-01'
                fecha_hasta: '5000-01-01'
              inicio_fecha_activacion: true
              id_tipo_identificador_pago: 4
              valor_dias_meses_plazo_pago: 10
            operacion:
              no_enviar_firma: true
              no_credit_check: false
            callback_url: https://callbacks.suempresa.example/gas
  responses:
    Finished:
      description: Procesamiento finalizado. Comprueba contrato_result.content.id para confirmar el alta;
        un resultado de scoring no aprobado también puede devolverse con HTTP 200. firma_result indica
        el envío a firma, no la firma completada.
      headers:
        X-Request-ID:
          schema:
            type: string
          description: Identificador de seguimiento de la petición.
        Location:
          schema:
            type: string
          description: Ruta para consultar el estado de la solicitud.
        Idempotency-Replayed:
          schema:
            type: string
            enum:
            - 'true'
          description: Presente cuando se devuelve una solicitud ya existente con la misma clave.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GasResult'
          examples:
            altaConfirmada:
              summary: Alta confirmada, sin solicitar firma
              value:
                request_id: 12345
                referencia_externa: gas-prueba-001
                producto: gas
                credit_result:
                  result_operation: Aprobado
                contrato_result:
                  result_operation: OK
                  content:
                    id: 9001
                    codigo: GAS-0001
                firma_result:
                  result_operation: SKIPPED
            riesgoNoAprobado:
              summary: Scoring rechazado; contrato no creado
              value:
                request_id: 12345
                referencia_externa: gas-prueba-001
                producto: gas
                credit_result:
                  result_operation: Rechazado
                contrato_result: null
                firma_result: null
    Queued:
      description: Solicitud aceptada para procesamiento asíncrono, o repetición de una solicitud que
        todavía está en curso. Consulta Location o /contrato/gas/solicitudes/{request_id}.
      headers:
        X-Request-ID:
          schema:
            type: string
          description: Identificador de seguimiento de la petición.
        Location:
          schema:
            type: string
          description: Ruta para consultar el estado de la solicitud.
        Idempotency-Replayed:
          schema:
            type: string
            enum:
            - 'true'
          description: Presente cuando se devuelve una solicitud ya existente con la misma clave.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GasQueued'
          example:
            request_id: 12345
            producto: gas
            state: ready
    Error:
      description: La solicitud no se ha podido completar. Revisa error y, cuando se incluya, field. Si
        existe request_id, consulta su estado antes de repetir el alta.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GasError'
          example:
            error: La duración no cumple los límites de la tarifa
            field: contrato_suministro.meses
            request_id: 12345
            producto: gas
    Uncertain:
      description: No se ha podido confirmar el resultado dentro del tiempo de espera. Consulta la solicitud.
        Si su estado es uncertain, solicita revisión a soporte y conserva la clave original; no envíes
        otra alta con una clave nueva.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GasError'
          example:
            request_id: 12345
            producto: gas
            error: No se pudo confirmar la respuesta del servicio de contratación
  # BEGIN GENERATED GAS INPUT
  schemas:
    GasInput:
      type: object
      additionalProperties: false
      properties:
        cliente:
          type: object
          additionalProperties: false
          properties:
            nombre:
              type: string
            primer_apellido:
              type: string
            segundo_apellido:
              type: string
            razon_social:
              type: string
              description: Nombre legal de la empresa. Obligatorio para persona jurídica.
            identificador:
              type: string
              description: NIF o NIE válido del titular, coherente con el tipo de persona.
            id_tipo_persona:
              type:
              - integer
              - string
              description: 1 para persona física; 2 para persona jurídica. Debe corresponder
                a la ruta residencial o empresa.
            id_tipo_identificador:
              type:
              - integer
              - string
              description: 'Identificador de maestra: 3 DNI, 4 NIF, 8 NIE. Consulte
                /maestras/gas.'
            direccion:
              type: object
              additionalProperties: false
              properties:
                pais:
                  type: string
                calle:
                  type: string
                numero_finca:
                  type: string
                codigo_postal:
                  type: string
                aclarador_finca:
                  type: string
                escalera:
                  type: string
                piso:
                  type: string
                puerta:
                  type: string
                portal:
                  type: string
                id_municipio:
                  type:
                  - integer
                  - string
                id_provincia:
                  type:
                  - integer
                  - string
                tipo_via_codigo:
                  type: string
                  minLength: 1
              required:
              - pais
              - calle
              - numero_finca
              - codigo_postal
              - id_municipio
              - id_provincia
              - tipo_via_codigo
              description: Domicilio del titular. Los IDs de provincia y municipio deben
                pertenecer a la misma relación geográfica.
            prefijo_1:
              type: string
            telefono_1:
              type: string
            correo_electronico:
              type: string
            email_factura:
              type: string
            idioma_plantilla:
              type: string
            envio_factura:
              type: boolean
            aviso_modificacion_precios:
              type: boolean
            autonomo:
              type: boolean
            es_firmante:
              type: boolean
          required:
          - identificador
          - id_tipo_persona
          - id_tipo_identificador
          - direccion
          - telefono_1
          - correo_electronico
          allOf:
          - if:
              properties:
                id_tipo_persona:
                  enum:
                  - 2
                  - '2'
              required:
              - id_tipo_persona
            then:
              required:
              - razon_social
              properties:
                razon_social:
                  type: string
                  minLength: 1
            else:
              required:
              - nombre
              - primer_apellido
              properties:
                nombre:
                  type: string
                  minLength: 1
                primer_apellido:
                  type: string
                  minLength: 1
          description: 'Titular del contrato: persona física o empresa.'
        punto_suministro:
          type: object
          additionalProperties: false
          properties:
            cups:
              type: string
              pattern: ^ES\d{16}[A-Z]{2}[A-Z0-9]{0,2}$
              description: CUPS de gas de 20 o 22 caracteres. Los dos caracteres de
                extensión no diferencian solicitudes del mismo suministro.
            pais:
              type: string
            calle:
              type: string
            numero_finca:
              type: string
            codigo_postal:
              type: string
            aclarador_finca:
              type: string
            escalera:
              type: string
            piso:
              type: string
            puerta:
              type: string
            portal:
              type: string
            tipo_via_codigo:
              type: string
            referencia_catastral:
              type: string
            municipio_id:
              type:
              - integer
              - string
            provincia_id:
              type:
              - integer
              - string
            telemedida:
              type: boolean
            consumo_anual_estimado:
              oneOf:
              - type: integer
                minimum: 1
              - type: string
                pattern: ^[0-9]*[1-9][0-9]*$
              description: Consumo aportado en kWh enteros positivos, sin decimales.
                Si también se informa en el contrato, ambos valores deben coincidir.
                Se conserva el valor aportado. Si falta en ambos objetos, se utiliza
                SIPS; solo el consumo del punto obtenido de SIPS se redondea al kWh
                más cercano (0,5 hacia arriba).
          required:
          - cups
          - pais
          - calle
          - numero_finca
          - codigo_postal
          - municipio_id
          - provincia_id
          - tipo_via_codigo
          - telemedida
          description: Datos del suministro. La dirección se informa directamente dentro
            de este objeto.
        contrato_suministro:
          type: object
          additionalProperties: false
          properties:
            iban:
              type: string
              description: IBAN español válido, sin espacios.
            bic_swift:
              type: string
            nombre_pago:
              type: string
            identificador_pago:
              type: string
            peaje_acceso:
              type: string
            periodicidad:
              type: string
            tipo_mandato:
              type: string
            frecuencia_pago:
              type: string
            tipo_dias_denuncia:
              type: string
            dias_meses_plazo_pago:
              type: string
            naturaleza_suministro:
              type: string
            tipo_inicio_info:
              type: string
            cnae_id:
              type:
              - integer
              - string
              description: Identificador del catálogo CNAE de gas devuelto por /maestras/gas.
            modo_pago_id:
              type:
              - integer
              - string
            id_tipo_identificador_pago:
              type:
              - integer
              - string
            id_tipo_plazo_cobro:
              type:
              - integer
              - string
            dias:
              type: integer
              minimum: 0
            anyos:
              type: integer
              minimum: 0
            meses:
              type: integer
              minimum: 0
              description: Duración en meses. Debe cumplir duracion_meses_min y duracion_meses_max
                de la tarifa elegida.
            dias_denuncia:
              type: integer
              minimum: 0
            valor_dias_meses_plazo_pago:
              type: integer
              minimum: 0
            telemedida:
              type: boolean
            planta_satelite:
              type: boolean
            prorroga_tacita:
              type: boolean
              description: Debe ser true cuando la tarifa devuelve prorroga_tacita_config=forzar_si.
            vivienda_habitual:
              type: boolean
            fecha_fija_fin_contrato:
              type: boolean
            inicio_fecha_activacion:
              type: boolean
            marcar_revisado:
              type: boolean
              description: Booleano opcional que indica si Neuro marca el contrato como
                revisado. Se conserva true o false cuando se informa; HERS no lo añade
                si se omite. No indica que el contrato esté firmado ni sustituye la
                firma.
            info_alta:
              type: string
              enum:
              - si
              - 'no'
              - no lo se
              description: si para cambio de comercializadora; no para alta nueva.
            info_titular:
              type: string
              enum:
              - si
              - 'no'
              - no lo se
              description: 'Cambio de comercializadora: no si se mantiene el titular;
                si cuando cambia. En alta nueva: no lo se.'
            info_caudal:
              type: string
              enum:
              - si
              - 'no'
              - no lo se
              description: Debe ser no lo se. La modificación de caudal no está disponible
                en estas rutas.
            fecha_inicio_info:
              type: string
              format: date
              description: Fecha de inicio solicitada (AAAA-MM-DD). Obligatoria con
                tipo_inicio_info=fecha_fija; debe omitirse con cuanto_antes.
            fecha_fin:
              type: string
              format: date
              description: Fecha final aportada (AAAA-MM-DD). No puede ser anterior
                a fecha_inicio_info. HERS no la calcula a partir de la duración ni la
                añade si se omite.
            fecha_firma:
              type: string
              format: date
            consumo_anual_estimado:
              oneOf:
              - type: integer
                minimum: 1
              - type: string
                pattern: ^[0-9]*[1-9][0-9]*$
              description: Consumo aportado en kWh enteros positivos, sin decimales.
                Tiene prioridad sobre SIPS y debe coincidir con el del punto si se informan
                ambos. Si falta en ambos objetos se utiliza SIPS; sin consumo en ninguna
                fuente se devuelve un error. Si SIPS informa el peaje, se conserva sin
                reclasificarlo por el consumo estimado. La comprobación del tramo se
                aplica al peaje aportado cuando no existe uno confirmado en SIPS.
            etiquetas_canal:
              type: array
              items:
                type:
                - integer
                - string
            conceptos_formula_agente:
              type: array
              maxItems: 2
              items:
                type: object
                additionalProperties: false
                properties:
                  abreviatura:
                    enum:
                    - FEE_CC_TF
                    - FEE_CC_TV
                  valor:
                    type:
                    - number
                    - string
                    pattern: ^\d+(\.\d+)?$
                required:
                - abreviatura
                - valor
              description: 'Márgenes sin impuestos: FEE_CC_TF en €/día y FEE_CC_TV en
                €/kWh. Hasta seis decimales; se envían separados del precio base.'
            tarifas:
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: object
                additionalProperties: false
                properties:
                  id_tarifa_precios:
                    type: integer
                    minimum: 1
                  precio_termino_fijo_personalizado:
                    type:
                    - number
                    - string
                    pattern: ^\d+(\.\d+)?$
                  precio_termino_variable_personalizado:
                    type:
                    - number
                    - string
                    pattern: ^\d+(\.\d+)?$
                  unidades_termino_fijo_personalizado:
                    const: €/mes
                  unidades_termino_variable_personalizado:
                    const: €/kWh
                required:
                - id_tarifa_precios
              description: Una tarifa de precios del canal. Consulte /tarifas/gas y
                /tarifas/gas/precios antes de contratar.
            impuestos_hidrocarburos:
              type: array
              minItems: 1
              items:
                type: object
                additionalProperties: false
                properties:
                  descripcion:
                    type: string
                  fecha_desde:
                    type: string
                    format: date
                  fecha_hasta:
                    type: string
                    format: date
                  valores:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        tipo:
                          type: string
                          enum:
                          - no_carburante
                          - carburante
                        porcentaje:
                          type: number
                          minimum: 0
                          maximum: 100
                        exencion_impuesto_hc:
                          type: boolean
                      required:
                      - tipo
                      - porcentaje
                      - exencion_impuesto_hc
                required:
                - descripcion
                - fecha_desde
                - fecha_hasta
                - valores
              description: Periodos y reparto del impuesto. Los porcentajes de cada
                periodo deben sumar 100 y la fecha final no puede preceder a la inicial.
          required:
          - iban
          - modo_pago_id
          - frecuencia_pago
          - naturaleza_suministro
          - tarifas
          - id_tipo_identificador_pago
          - identificador_pago
          - nombre_pago
          - meses
          - cnae_id
          - info_alta
          - info_titular
          - info_caudal
          - impuestos_hidrocarburos
          description: Condiciones de contratación, cobro, tarifa, gestión e impuesto
            de hidrocarburos.
        contactos:
          type: array
          minItems: 1
          items:
            type: object
            additionalProperties: false
            properties:
              contacto:
                type: object
                additionalProperties: false
                properties:
                  nombre:
                    type: string
                  primer_apellido:
                    type: string
                  segundo_apellido:
                    type: string
                  razon_social:
                    type: string
                  identificador:
                    type: string
                  id_tipo_persona:
                    type:
                    - integer
                    - string
                  id_tipo_identificador:
                    type:
                    - integer
                    - string
                  tlf_firma:
                    type: string
                  email_firma:
                    type: string
                  id_canal_envio:
                    type:
                    - integer
                    - string
                  email:
                    type: array
                    minItems: 1
                    items:
                      type: string
                      format: email
                  telefonos:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        numero:
                          type: string
                        extension:
                          type: string
                      required:
                      - numero
                required:
                - nombre
                - primer_apellido
                - identificador
                - id_tipo_persona
                - id_tipo_identificador
                - email
              id_tipo_contacto:
                type:
                - integer
                - string
              email_factura:
                type: string
              email_modificacion_precios:
                type: string
              envio_factura:
                type: boolean
              envio_factura_papel:
                type: boolean
              aviso_modificacion_precios:
                type: boolean
            required:
            - contacto
            - id_tipo_contacto
          description: Contactos y destinatarios de firma. Una empresa requiere al menos
            un representante físico de tipo Firmante (id_tipo_contacto=1).
        operacion:
          type: object
          additionalProperties: false
          properties:
            no_enviar_firma:
              type: boolean
              default: false
              description: true crea el contrato sin solicitar su firma. Si se omite
                o es false, se solicita la firma tras el alta aprobada.
            no_credit_check:
              type: boolean
              default: false
              description: true omite la evaluación de riesgo. Si se omite o es false,
                solo un resultado Aprobado permite crear el contrato.
            datos_suministro_aportados:
              type: boolean
              default: false
              description: Solo alta nueva sin SIPS, con consumo kWh, peaje, CNAE y
                dirección aportados por el cliente.
            canal_envio:
              type: string
              enum:
              - email
              - sms
              - email_otp
              description: 'Para gas, omita este campo: el canal de firma se indica
                en contactos[].contacto.id_canal_envio. No se permite sobrescribirlo
                al solicitar firma.'
            direcciones_firma:
              type: string
              description: 'Para gas, omita este campo: los destinatarios se indican
                en los contactos del contrato.'
            id_grupo_tarifa:
              type:
              - integer
              - string
              pattern: ^[0-9]+$
              description: Grupo devuelto por /tarifas/gas. Obligatorio si la tarifa
                elegida está disponible en varios grupos.
            fecha_precio:
              type: string
              format: date
              description: Debe ser hoy. Un precio de otra jornada requiere revalidación.
        callback_url:
          type: string
          format: uri
          pattern: ^https://
          description: URL HTTPS cuyo dominio debe estar autorizado. Su presencia activa
            el procesamiento asíncrono. Obligatoria en /contrato/gas/raw.
        callback_exec:
          type: boolean
          default: true
          description: Con callback_url, false conserva el procesamiento asíncrono pero
            suprime la entrega del resultado al callback.
        referencia_externa:
          type: string
          maxLength: 255
          description: Referencia de su sistema que se devuelve en el resultado para
            relacionar la solicitud.
        url_notificaciones_cambios_contrato:
          type: string
          description: No disponible para gas. Informar una URL devuelve HTTP 501; no
            confundir con callback_url, que comunica el resultado del alta.
      required:
      - cliente
      - punto_suministro
      - contrato_suministro
      - contactos
      title: Solicitud de alta de un contrato de gas
      description: Datos del titular, contactos, punto de suministro y condiciones del
        contrato. Cada solicitud corresponde a un suministro.
    GasResult:
      type: object
      properties:
        request_id:
          type: integer
        producto:
          const: gas
        referencia_externa:
          type:
          - string
          - 'null'
        credit_result:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: Resultado de riesgo. Aprobado permite continuar; SKIPPED indica
            que se solicitó omitir la evaluación.
        contrato_result:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: Si el alta está confirmada, result_operation=OK y content.id
            identifica el contrato.
        firma_result:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: Resultado de la solicitud de firma. OK confirma el envío, no
            que el cliente haya firmado; SKIPPED indica firma omitida.
        error:
          type: string
        provider_error:
          $ref: '#/components/schemas/GasProviderError'
      required:
      - request_id
      - producto
    GasQueued:
      type: object
      properties:
        request_id:
          type: integer
        producto:
          const: gas
        state:
          type: string
      required:
      - request_id
      - producto
      - state
    GasError:
      type: object
      properties:
        error:
          type: string
        field:
          type: string
        request_id:
          type: integer
        producto:
          const: gas
        uncertain:
          type: boolean
        provider_error:
          $ref: '#/components/schemas/GasProviderError'
      required:
      - error
    GasProviderError:
      type: object
      description: Evidencia acotada del error de Neuro. http_status es el código original
        del proveedor; el HTTP de HERS puede ser 502. El cuerpo oculta credenciales
        y datos personales y no incluye la petición original.
      properties:
        http_status:
          type: integer
        method:
          type: string
        path:
          type: string
        content_type:
          type: string
        body:
          description: Mensajes de negocio JSON o texto del proveedor, saneados y con
            límites de tamaño.
      required:
      - http_status
      - method
      - path
    GasStatus:
      type: object
      properties:
        request_id:
          type: integer
        producto:
          const: gas
        state:
          type: string
          enum:
          - validating
          - ready
          - processing
          - creating
          - created
          - signing
          - completed
          - rejected
          - failed
          - uncertain
        result:
          anyOf:
          - $ref: '#/components/schemas/GasResult'
          - type: 'null'
        callback:
          type:
          - object
          - 'null'
          properties:
            state:
              type: string
            attempts:
              type: integer
            last_status:
              type:
              - integer
              - 'null'
      required:
      - request_id
      - producto
      - state
    GasDocumentOperation:
      type: object
      properties:
        state:
          enum:
          - processing
          - completed
          - failed
          - uncertain
        producto:
          const: gas
        data:
          type: object
        error:
          type: string
      required:
      - state
    GasSignatureStatus:
      type: object
      properties:
        producto:
          const: gas
        origen:
          type: string
          enum:
          - eevidsign
          - neuro
        alcance:
          type: string
          enum:
          - circuito
          - contrato
        data:
          type: object
          properties:
            circuito_id:
              type:
              - integer
              - string
            finalizado:
              type: boolean
            estado:
              type: string
              enum:
              - pendiente
              - en_proceso
              - completado
              - rechazado
            fecha_inicio:
              type:
              - string
              - 'null'
              format: date-time
            fecha_completado:
              type:
              - string
              - 'null'
              format: date-time
            fecha_cancelacion:
              type:
              - string
              - 'null'
              format: date-time
            detalle_entrega_disponible:
              type: boolean
            contadores:
              type: object
            firmantes:
              type: array
              items:
                type: object
                properties:
                  estado:
                    type: string
                    enum:
                    - firmado
                    - error
                    - enviado
                    - pendiente
                  fecha_firma:
                    type:
                    - string
                    - 'null'
                    format: date-time
      required:
      - producto
      - data
