Descripción

La API de gas permite contratar un suministro para un particular o una empresa, consultar su información y gestionar el contrato individual y su firma. Cada solicitud de alta corresponde a un único CUPS.

Entorno de pruebas (PRE)

URL base: https://pre-webhooks.imaginaenergia.com

En los ejemplos, BASE_URL representa esta dirección y TOKEN el JWT obtenido con tus credenciales. Sustituye los datos ilustrativos por los del cliente y utiliza IDs de los catálogos de tu canal.

Flujo recomendado

  1. Obtén el token y consulta el SIPS del CUPS.
  2. Recupera las maestras, las tarifas del canal y los precios para el peaje del suministro.
  3. Completa los datos del titular, contactos y condiciones de contratación.
  4. Solicita el alta con una clave de idempotencia propia y conserva el request_id.
  5. Comprueba el resultado del alta y gestiona los documentos y la firma del contrato confirmado.

Autenticación

Utiliza la autenticación habitual de la API. El token se obtiene en el servicio de autenticación; las llamadas de gas se envían a la URL base de HERS.

curl --request POST 'https://oezimzeqmtmncuipqgwd.supabase.co/functions/v1/initiateauthcommand' \
  --header 'Content-Type: application/json' \
  --data '{"email":"su_usuario@ejemplo.com","password":"su_contraseña"}'
CabeceraCuándo enviarlaValor
AuthorizationEn todas las operaciones.Bearer <token>
Content-TypeEn peticiones con cuerpo JSON.application/json
Idempotency-KeyEn altas, adjuntos y solicitudes de firma.Clave estable y distinta para cada operación.
X-CanalSolo para seleccionar otro canal con autorización.Valor de impersonación autorizado.

Si omites X-Canal, se utiliza el canal asociado al token. No se envían credenciales de Neuro ni identificadores de agente en el JSON del alta.

Claves de idempotencia

La clave admite de 8 a 128 caracteres: letras, números, punto, guion, guion bajo y dos puntos. Por ejemplo: gas-alta-20261104-0001.

La misma clave con el mismo contenido recupera la misma operación. Reutilizarla con otro contenido o modalidad devuelve 409. Si se pierde una respuesta, conserva la clave original y consulta el resultado antes de iniciar otra operación.

Endpoints

Las siguientes direcciones corresponden a PRE. Sustituye los parámetros entre llaves por el CUPS, el identificador de solicitud o el identificador de contrato correspondiente.

MétodoURL completaUso
POSThttps://pre-webhooks.imaginaenergia.com/contrato/gas/residencialAlta para persona física.
POSThttps://pre-webhooks.imaginaenergia.com/contrato/gas/empresaAlta para empresa con representante.
POSThttps://pre-webhooks.imaginaenergia.com/contrato/gas/rawAlta con IDs de maestras y callback obligatorio.
GEThttps://pre-webhooks.imaginaenergia.com/sips/gas/{cups}Consulta de SIPS.
GEThttps://pre-webhooks.imaginaenergia.com/maestras/gasCatálogos necesarios para contratar.
GEThttps://pre-webhooks.imaginaenergia.com/tarifas/gasTarifas y grupos del canal.
POSThttps://pre-webhooks.imaginaenergia.com/tarifas/gas/preciosPrecios del día para un peaje.
GEThttps://pre-webhooks.imaginaenergia.com/contrato/gas/solicitudes/{request_id}Seguimiento de una solicitud de alta.
GEThttps://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/pdfDescarga del contrato individual.
POSThttps://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/documentosAdjuntar un PDF.
POSThttps://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/firmaSolicitar firma.
GEThttps://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/firmaConsultar el estado de firma.
GEThttps://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/firmadoDescargar el documento firmado.

SIPS, maestras y tarifas

Consultar el suministro

curl "$BASE_URL/sips/gas/ES0021000000000000AA" \
  --header "Authorization: Bearer $TOKEN"

Comprueba disponible. Si es true, la respuesta incluye el consumo en Wh y kWh y el peaje. El consumo utilizado en el alta se expresa en kWh.

{
  "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"
}

importe_scoring es una valoración de riesgo en EUR; no representa el precio de la tarifa ni el importe de una factura.

Si el CUPS no tiene SIPS

La consulta responde HTTP 200 con disponible=false y data=null. Para un alta nueva, puedes aportar expresamente consumo positivo en kWh, peaje, CNAE y direcciones, e indicar operacion.datos_suministro_aportados=true. Si existe SIPS, se deben utilizar sus datos.

Consultar las maestras

curl "$BASE_URL/maestras/gas" \
  --header "Authorization: Bearer $TOKEN"

La respuesta contiene cnae, tipos_via, tipos_identificador, tipos_persona, modos_pago, provincias y municipios. Utiliza sus IDs y comprueba que el municipio pertenece a la provincia. El tipo de vía se envía mediante su codigo, como CL o PZ. Selecciona el CNAE del catálogo de gas.

Consultar el catálogo del canal

curl "$BASE_URL/tarifas/gas" \
  --header "Authorization: Bearer $TOKEN"

Conserva id_tarifa_precios, los peajes admitidos y id_grupo_tarifa. Una tarifa puede aparecer en más de un grupo; en ese caso, indica el grupo elegido en operacion.id_grupo_tarifa.

Precios y márgenes

curl --request POST "$BASE_URL/tarifas/gas/precios" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"peaje":"R2"}'

La respuesta devuelve todas las tarifas ofertables para ese peaje, con precios del día de la consulta y las condiciones de duración y prórroga. No se admite solicitar un precio para otra fecha. Una lista tarifas=[] indica que el canal no tiene oferta para ese peaje.

Ejemplo de respuesta de precios
{
  "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"
      }
    }
  ]
}
ConceptoUnidad / interpretación
Precio fijo personalizado€/mes.
Precio variable de tarifa fija€/kWh.
Precio variable de indexada o mixtanull: la energía no tiene un precio cerrado. No equivale a cero.
Impuestos, márgenes y conceptos adicionalesNo están incluidos en los precios base. Los conceptos facturables se devuelven por separado.

Utilizar el precio en el alta

Selecciona la tarifa y su grupo. Puedes enviar solo su id_tarifa_precios; la API comprueba el precio vigente. Si también envías precios personalizados, deben coincidir con los actuales. Para una tarifa fija, los campos son:

{
  "tarifas": [{
    "id_tarifa_precios": 30,
    "precio_termino_fijo_personalizado": "6.793137",
    "unidades_termino_fijo_personalizado": "€/mes",
    "precio_termino_variable_personalizado": "0.06024",
    "unidades_termino_variable_personalizado": "€/kWh"
  }]
}

Este fragmento se añade dentro de contrato_suministro. En indexadas y mixtas, omite los campos de precio y unidades del término variable. Ajusta meses a los límites recibidos y envía prorroga_tacita=true si la tarifa devuelve forzar_si. Las tarifas con otra regla de prórroga informada requieren revisión antes de contratar.

Márgenes del canal

Los márgenes se informan en contrato_suministro.conceptos_formula_agente, separados del precio base, sin impuestos y con un máximo de seis decimales:

{
  "conceptos_formula_agente": [
    {"abreviatura": "FEE_CC_TF", "valor": "0.02"},
    {"abreviatura": "FEE_CC_TV", "valor": "0.004"}
  ]
}

FEE_CC_TF se expresa en €/día y FEE_CC_TV en €/kWh. Para mostrar el fijo mensual con margen, convierte el margen diario a mensual con días del año / 12. No sumes el margen al precio personalizado que envías al alta: se declara mediante los conceptos anteriores.

Solicitud de alta

Tipo de titular y estructura

BloqueContenido
clienteIdentificación, nombre y apellidos del particular, o razón social y NIF de la empresa; dirección y datos de contacto.
contactosPersonas de contacto y destinatarios de firma. Una empresa requiere un representante físico con id_tipo_contacto=1.
punto_suministroCUPS y dirección del suministro. No confundir estos campos con el domicilio del titular.
contrato_suministroTarifa, gestión, duración, consumo en kWh, IBAN español, datos del pagador, condiciones de cobro e hidrocarburos.
operacionOpciones de scoring, firma, selección de grupo y datos aportados cuando no hay SIPS.

En cliente.id_tipo_persona, utiliza 1 para particular y 2 para empresa. Los tipos de documento admitidos son 3 (DNI), 4 (NIF) y 8 (NIE), siempre coherentes con la persona identificada. Para empresas, razon_social identifica al titular y los datos de la persona que firma se indican en contactos.

Tipo de gestión

El campo opcional contrato_suministro.marcar_revisado admite los booleanos JSON true y false. Se reenvía a Neuro tal como se recibe y no se añade si se omite. Indica la marca de revisado del contrato; no significa que esté firmado ni sustituye el proceso de firma.

Estos campos pertenecen a contrato_suministro:

Gestióninfo_altainfo_titularinfo_caudal
Cambio de comercializadora manteniendo titularsinono lo se
Cambio de comercializadora con cambio de titularsisino lo se
Alta nuevanono lo seno lo se

Opciones de la petición

CampoUso
operacion.no_credit_checkPor defecto false. true omite la evaluación de riesgo. Si se evalúa, solo Aprobado permite crear.
operacion.no_enviar_firmaPor defecto false. true crea sin solicitar firma. La firma puede pedirse después.
operacion.datos_suministro_aportadostrue para un alta nueva sin SIPS con datos expresamente aportados.
operacion.id_grupo_tarifaGrupo elegido cuando la tarifa aparece en varios grupos del canal.
operacion.fecha_precioOpcional. Si se informa, debe ser el día actual; otra jornada requiere volver a validar el precio.
referencia_externaReferencia de tu sistema que se devuelve con el resultado.
callback_urlActiva el modo asíncrono. Obligatorio en RAW; requiere HTTPS y dominio autorizado.
callback_execCon callback, false suprime la notificación; el procesamiento sigue siendo asíncrono.

Para una fecha de inicio concreta, informa tipo_inicio_info=fecha_fija y fecha_inicio_info en formato AAAA-MM-DD. Con cuanto_antes, deja la fecha de inicio vacía. Si aportas fecha_fin, no puede ser anterior a fecha_inicio_info. HERS conserva la fecha final aportada y no la calcula a partir de la duración.

Ejemplos de petición

Antes de enviar: descarga el ejemplo y sustituye cliente, CUPS, IBAN, contactos, tarifa, grupo y maestras. Comprueba también duración y prórroga. Los IDs y datos de estos ficheros son ilustrativos.

Persona física

Descargar JSON de alta residencial. El ejemplo evalúa el riesgo y omite la solicitud de firma mediante no_enviar_firma=true.

curl --request POST "$BASE_URL/contrato/gas/residencial" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: gas-alta-20261104-0001' \
  --data @ejemplo_contrato_gas.json
Ver JSON completo para persona física
{
  "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
  }
}

Empresa con representante

Descargar JSON de alta de empresa. La empresa consta como titular; el contacto de tipo Firmante identifica a la persona que la representa.

curl --request POST "$BASE_URL/contrato/gas/empresa" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: gas-empresa-20261104-0001' \
  --data @ejemplo_contrato_gas_empresa.json
Ver JSON completo para empresa
{
  "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
  }
}

Alta RAW

Envía la estructura completa con IDs de maestras a POST /contrato/gas/raw e incorpora callback_url en la raíz. El dominio debe estar autorizado antes de utilizar esta modalidad. No es un envoltorio neuro_data.

Respuestas y seguimiento

Procesamiento síncrono

Sin callback_url, residencial y empresa devuelven el resultado en la respuesta. Para confirmar el alta, comprueba contrato_result.content.id.

{
  "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"
  }
}

HTTP 200 no confirma por sí solo un alta. Un scoring no aprobado puede devolver 200 con contrato_result=null. Revisa siempre los tres bloques: riesgo, contrato y solicitud de firma. Un envío a firma correcto no significa que el cliente ya haya firmado.

Procesamiento asíncrono

Con callback_url, una solicitud nueva válida devuelve HTTP 202, el identificador y una ruta Location para consultar el estado.

{"request_id":12345,"producto":"gas","state":"ready"}
curl "$BASE_URL/contrato/gas/solicitudes/12345" \
  --header "Authorization: Bearer $TOKEN"

La consulta devuelve state, result y, si se solicitó notificación, callback. El objeto result tiene la misma estructura del resultado síncrono; no hay que interpretar ambos cuerpos como si fueran idénticos.

Estado de solicitudQué hacer
validating, ready, processing, creating, created, signingLa solicitud continúa en curso. Conserva el request_id y consulta su evolución.
completedRevisa result.contrato_result y result.firma_result.
rejectedLa evaluación de riesgo no permite continuar con el alta.
failedRevisa el error y corrige la causa antes de preparar otro intento.
uncertainNo se puede confirmar si la operación se completó. Solicita revisión a soporte y no generes otra clave para repetir el alta.

Una repetición con la misma clave puede añadir la cabecera Idempotency-Replayed: true. Si recibes un timeout, consulta el request_id o recupera la petición con la misma clave y el mismo contenido.

Documentos y firma

Utiliza el identificador contrato_result.content.id, no el request_id. Todas las operaciones comprueban que el contrato pertenece al canal autorizado.

Descargar el contrato

curl "$BASE_URL/contrato/gas/9001/pdf" \
  --header "Authorization: Bearer $TOKEN" \
  --output contrato-gas.pdf

La respuesta es un fichero PDF, no un JSON. Guarda la respuesta binaria. La descarga no solicita firma.

Adjuntar un PDF

curl --request POST "$BASE_URL/contrato/gas/9001/documentos" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Idempotency-Key: gas-anexo-20261104-0001' \
  --form 'fichero=@anexo.pdf;type=application/pdf' \
  --form 'tipo_fichero=34' \
  --form 'descripcion=Anexo del contrato'

Envía multipart/form-data; no fijes manualmente su cabecera Content-Type, para que tu cliente añada el separador multipart. Tamaño máximo del PDF: 20 MiB.

  • tipo_fichero=34: anexo.
  • tipo_fichero=11 con fecha_firma: contrato firmado en papel. Puede actualizar la fecha de firma del contrato.
  • También se admiten los tipos 6, 8, 16 y 17. Usa el tipo documental que corresponda al fichero.
  • Campos opcionales: descripcion, fecha_documento, fecha_firma y obligatorio_firma (0 o 1).

Si el contrato todavía no está firmado, omite fecha_firma. No uses una fecha de ejemplo, la fecha de subida ni la fecha de solicitud: ese campo declara una firma ya realizada. Adjuntar el PDF y solicitar su firma son operaciones distintas.

Solicitar firma individual

curl --request POST "$BASE_URL/contrato/gas/9001/firma" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Idempotency-Key: gas-firma-20261104-0001'

El POST de firma no lleva cuerpo, tampoco un objeto vacío. Utiliza los contactos del contrato y puede avisar al cliente. No se admiten destinatarios alternativos en esta petición.

{"state":"completed","producto":"gas","data":{"circuito_id":12345}}

Consultar firma y descargar el documento firmado

curl "$BASE_URL/contrato/gas/9001/firma" \
  --header "Authorization: Bearer $TOKEN"

curl "$BASE_URL/contrato/gas/9001/firmado" \
  --header "Authorization: Bearer $TOKEN" \
  --output contrato-gas-firmado.pdf

El GET de firma sigue el último circuito solicitado por HERS para este contrato y canal. También puedes fijar el circuito devuelto por el POST con ?circuito_id=404304. No necesita cuerpo ni Idempotency-Key y no abre circuitos ni envía avisos.

Con alcance=circuito, devuelve el estado de esa solicitud mediante eEvidSign, como en electricidad: data.finalizado, data.estado, data.fecha_completado y data.firmantes[].fecha_firma. Las fechas son nulas mientras no consten. Si falla la consulta o la última solicitud no tiene circuito confirmado, no se presenta una firma anterior como si fuera la nueva.

Estas consultas de eEvidSign no confirman la entrega del correo/SMS: detalle_entrega_disponible=false y los campos de envío son nulos. Los firmantes sin completar se cuentan como pendientes. Solo cuando HERS no tiene ninguna solicitud registrada se conserva la consulta histórica de Neuro con alcance=contrato; Neuro puede elegir una firma antigua ya completada. La descarga firmada puede devolver 404 si el documento aún no está disponible.

Callbacks

Para recibir el resultado del alta, informa una URL HTTPS cuyo dominio haya sido autorizado para tu integración. Una dirección no autorizada se rechaza antes de aceptar la solicitud.

El callback envía el resultado del alta e incluye request_id. La entrega puede repetirse: el receptor debe deduplicar por ese identificador y responder con un estado HTTP 2xx. Se realizan hasta cinco intentos de entrega. Un fallo del callback no implica que el contrato no se haya creado.

Verifica las cabeceras X-Signature, X-Signature-Timestamp y X-Signature-Algorithm siguiendo la guía de seguridad de callbacks. No se siguen redirecciones del receptor.

Este callback comunica el resultado de la solicitud; no es una suscripción a futuros cambios del contrato. La opción url_notificaciones_cambios_contrato no está disponible para gas.

Manejo de errores

HTTPInterpretación y acción
400Petición inválida o datos incoherentes. Revisa error y field.
401 / 403Token, permisos o canal no autorizados para la operación.
404Solicitud, contrato o documento no encontrado o no disponible para el canal.
409Clave reutilizada con otro contenido o una operación documental pendiente de revisión.
413Petición o fichero demasiado grande.
422Condición comercial o de contratación no admitida. Revisa el mensaje devuelto.
501Operación no disponible, como las notificaciones de futuros cambios de contrato.
502 / 503 / 504Servicio no disponible o respuesta no confirmada. Si hay request_id, consulta su estado antes de repetir el alta.
{"error":"La duración no cumple los límites de la tarifa","field":"contrato_suministro.meses","request_id":12345,"producto":"gas"}

Operaciones admitidas

Estas rutas cubren las tres gestiones de alta descritas, personas físicas y jurídicas, IBAN español, consulta de catálogos y precios, documentos y firma del contrato individual.

  • La consulta de precios admite R1–R9, L0 y L1. El alta con valoración de SIPS/riesgo está limitada a R1–R6.
  • tipo_distribucion permite consultar precios de plantas satélite; su alta no está disponible en estas rutas.
  • La modificación de caudal, la sustitución o anulación de contratos y la cancelación de firmas no se realizan mediante estos endpoints.
  • Los documentos y circuitos de firma corresponden a cada contrato individual; no se genera ni se firma un contrato conjunto multicups mediante estas rutas.
  • La disponibilidad del servicio y de cada canal se comprueba en cada operación. Si recibes 503 o 403, consulta a soporte antes de repetirla.

Soporte

Para revisar una incidencia, incluye el método, la URL, la fecha y hora, el estado HTTP, el request_id y, cuando corresponda, el identificador de contrato. Conserva la clave de idempotencia. No incluyas contraseñas ni tokens en la comunicación.

Contacto: api.agentes@imaginaenergia.com.