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
- Obtén el token y consulta el SIPS del CUPS.
- Recupera las maestras, las tarifas del canal y los precios para el peaje del suministro.
- Completa los datos del titular, contactos y condiciones de contratación.
- Solicita el alta con una clave de idempotencia propia y conserva el
request_id. - 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"}'
| Cabecera | Cuándo enviarla | Valor |
|---|---|---|
Authorization | En todas las operaciones. | Bearer <token> |
Content-Type | En peticiones con cuerpo JSON. | application/json |
Idempotency-Key | En altas, adjuntos y solicitudes de firma. | Clave estable y distinta para cada operación. |
X-Canal | Solo 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étodo | URL completa | Uso |
|---|---|---|
| POST | https://pre-webhooks.imaginaenergia.com/contrato/gas/residencial | Alta para persona física. |
| POST | https://pre-webhooks.imaginaenergia.com/contrato/gas/empresa | Alta para empresa con representante. |
| POST | https://pre-webhooks.imaginaenergia.com/contrato/gas/raw | Alta con IDs de maestras y callback obligatorio. |
| GET | https://pre-webhooks.imaginaenergia.com/sips/gas/{cups} | Consulta de SIPS. |
| GET | https://pre-webhooks.imaginaenergia.com/maestras/gas | Catálogos necesarios para contratar. |
| GET | https://pre-webhooks.imaginaenergia.com/tarifas/gas | Tarifas y grupos del canal. |
| POST | https://pre-webhooks.imaginaenergia.com/tarifas/gas/precios | Precios del día para un peaje. |
| GET | https://pre-webhooks.imaginaenergia.com/contrato/gas/solicitudes/{request_id} | Seguimiento de una solicitud de alta. |
| GET | https://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/pdf | Descarga del contrato individual. |
| POST | https://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/documentos | Adjuntar un PDF. |
| POST | https://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/firma | Solicitar firma. |
| GET | https://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/firma | Consultar el estado de firma. |
| GET | https://pre-webhooks.imaginaenergia.com/contrato/gas/{contrato_id}/firmado | Descargar 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"
}
}
]
}| Concepto | Unidad / interpretación |
|---|---|
| Precio fijo personalizado | €/mes. |
| Precio variable de tarifa fija | €/kWh. |
| Precio variable de indexada o mixta | null: la energía no tiene un precio cerrado. No equivale a cero. |
| Impuestos, márgenes y conceptos adicionales | No 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
| Bloque | Contenido |
|---|---|
cliente | Identificación, nombre y apellidos del particular, o razón social y NIF de la empresa; dirección y datos de contacto. |
contactos | Personas de contacto y destinatarios de firma. Una empresa requiere un representante físico con id_tipo_contacto=1. |
punto_suministro | CUPS y dirección del suministro. No confundir estos campos con el domicilio del titular. |
contrato_suministro | Tarifa, gestión, duración, consumo en kWh, IBAN español, datos del pagador, condiciones de cobro e hidrocarburos. |
operacion | Opciones 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ón | info_alta | info_titular | info_caudal |
|---|---|---|---|
| Cambio de comercializadora manteniendo titular | si | no | no lo se |
| Cambio de comercializadora con cambio de titular | si | si | no lo se |
| Alta nueva | no | no lo se | no lo se |
Opciones de la petición
| Campo | Uso |
|---|---|
operacion.no_credit_check | Por defecto false. true omite la evaluación de riesgo. Si se evalúa, solo Aprobado permite crear. |
operacion.no_enviar_firma | Por defecto false. true crea sin solicitar firma. La firma puede pedirse después. |
operacion.datos_suministro_aportados | true para un alta nueva sin SIPS con datos expresamente aportados. |
operacion.id_grupo_tarifa | Grupo elegido cuando la tarifa aparece en varios grupos del canal. |
operacion.fecha_precio | Opcional. Si se informa, debe ser el día actual; otra jornada requiere volver a validar el precio. |
referencia_externa | Referencia de tu sistema que se devuelve con el resultado. |
callback_url | Activa el modo asíncrono. Obligatorio en RAW; requiere HTTPS y dominio autorizado. |
callback_exec | Con 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 solicitud | Qué hacer |
|---|---|
validating, ready, processing, creating, created, signing | La solicitud continúa en curso. Conserva el request_id y consulta su evolución. |
completed | Revisa result.contrato_result y result.firma_result. |
rejected | La evaluación de riesgo no permite continuar con el alta. |
failed | Revisa el error y corrige la causa antes de preparar otro intento. |
uncertain | No 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=11confecha_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_firmayobligatorio_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
| HTTP | Interpretación y acción |
|---|---|
| 400 | Petición inválida o datos incoherentes. Revisa error y field. |
| 401 / 403 | Token, permisos o canal no autorizados para la operación. |
| 404 | Solicitud, contrato o documento no encontrado o no disponible para el canal. |
| 409 | Clave reutilizada con otro contenido o una operación documental pendiente de revisión. |
| 413 | Petición o fichero demasiado grande. |
| 422 | Condición comercial o de contratación no admitida. Revisa el mensaje devuelto. |
| 501 | Operación no disponible, como las notificaciones de futuros cambios de contrato. |
| 502 / 503 / 504 | Servicio 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_distribucionpermite 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.