📘 Esta documentación refleja la API de ciflow disponible para partners. Algunos endpoints requieren acuerdos específicos o están bajo desarrollo activo según el roadmap acordado con cada partner. Para acceso, condiciones, ejemplos adicionales y la versión más reciente, contacta con el equipo de ciflow en partners@ciflow.net o solicita acceso desde Solicitar acceso partner.

Documentación de la API de ciflow

API REST para integrar el diagnóstico energético de edificios, telemetría de equipos e informes comerciales en tus sistemas. 56 endpoints documentados.

Introducción

ciflow es una plataforma de diagnóstico energético de edificios. La API para partners te permite dar de alta inmuebles a partir de su referencia catastral, obtener datos oficiales (Catastro, certificado energético, inspección técnica del edificio), simular escenarios de mejora, recibir recomendaciones del catálogo, ingerir telemetría de equipos instalados y generar informes que cierran ventas.

Cualifica visitas y prioriza presupuestos con datos reales del edificio.
Conecta tu CRM o ERP para sincronizar clientes, leads e informes.
Envía datos de PLC/equipos y deja que ciflow genere gráficas, anomalías e informes.

La API está versionada en la ruta. La versión actual es /api/v1/partner-api/.... URL base:

https://api.ciflow.net/api/v1/partner-api

Autenticación

Todas las peticiones se autentican con la cabecera X-API-Key. Las claves tienen el prefijo cf_live_… y se emiten a partners aprobados. ciflow solo persiste el hash y el prefijo de la clave: guárdala de forma segura, no podrás recuperarla. Para obtener una clave debes ser partner aprobado — solicita acceso partner.

curl https://api.ciflow.net/api/v1/partner-api/properties/8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Rate limits

Los límites se aplican por API key:

1000 peticiones/min en operaciones de lectura.
100 peticiones/min en operaciones de escritura.
5000 registros/min en ingesta de telemetría.

Cada respuesta incluye la cabecera X-RateLimit-Remaining con las peticiones restantes en la ventana actual. Al superar el límite la API responde 429 Too Many Requests; reintenta de forma exponencial.

Errores

La API usa códigos HTTP estándar. Los errores devuelven un cuerpo JSON con code, un message legible y un request_id que te pedimos al abrir una incidencia.

Código HTTP	Significado
200 OK	Petición correcta; el cuerpo contiene el recurso.
201 Created	Recurso creado correctamente.
202 Accepted	Aceptada para procesamiento asíncrono (telemetría, informes).
400 Bad Request	Petición mal formada.
401 Unauthorized	Falta o es inválida la X-API-Key.
403 Forbidden	La API key no tiene acceso a este recurso o función.
404 Not Found	El recurso no existe o no es tuyo.
409 Conflict	Conflicto de estado (p.ej. recurso duplicado).
422 Unprocessable Entity	El cuerpo no cumple el esquema esperado.
429 Too Many Requests	Se superó el rate limit.
500 Internal Server Error	Error interno; reintenta.

{
  "error": {
    "code": "validation_error",
    "message": "cadastral_reference is required",
    "request_id": "req_8f1c2d3e4a5b6c7d"
  }
}

Idempotencia

Las operaciones de escritura aceptan la cabecera Idempotency-Key (recomendamos un UUID v4). Si reenvías una petición con la misma clave dentro de 24 horas, ciflow devuelve el resultado original sin volver a ejecutar la operación. Úsala para proteger reintentos de red ante respuestas perdidas.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9a1c2e-1d3b-4a6c-9e8f-0b1c2d3e4f5a" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Properties

Alta y consulta de inmuebles. Al crear una propiedad, ciflow la enriquece con datos oficiales (Catastro, certificado energético, ITE) de forma asíncrona y resiliente.

POST/properties

Crear una propiedad

Da de alta un inmueble a partir de su referencia catastral. ciflow lanza el pipeline de enriquecimiento (Catastro + certificado energético + inspección técnica del edificio). El enriquecimiento que no se complete a tiempo se reintenta y se notifica vía webhook property.enriched; los campos no disponibles vuelven como null sin bloquear la respuesta.

Cuerpo de la petición

Campo	Tipo	Descripción
cadastral_reference*	string	Referencia catastral de 14 o 20 caracteres. Identifica unívocamente el inmueble en el Catastro.

Errores

HTTP	Código	Cuándo
400	invalid_cadastral_reference	Formato de referencia catastral inválido.
401	missing_api_key	Falta o es inválida la cabecera X-API-Key.
422	validation_error	El cuerpo no cumple el esquema esperado.
429	rate_limited	Se superó el límite de escritura (100 req/min).

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Respuesta de ejemplo

{
  "property_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "address": "Calle Mayor 5",
  "municipality": "Madrid",
  "province": "Madrid",
  "ccaa": "Comunidad de Madrid",
  "year_built": 1978,
  "climate_zone": "D3",
  "energy_certificate": { "rating": "E", "source": "estimated" },
  "ite_fetch_status": "ok"
}

GET/properties/{id}

Obtener una propiedad

Devuelve el inmueble con todos los datos enriquecidos disponibles: identificación catastral, superficie, año de construcción, zona climática, certificado energético e inspección técnica del edificio.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Falta o es inválida la cabecera X-API-Key.
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "property_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "cadastral_reference": "9872023VH5797S0001WX",
  "address": "Calle Mayor 5",
  "municipality": "Madrid",
  "province": "Madrid",
  "ccaa": "Comunidad de Madrid",
  "postcode": "28013",
  "year_built": 1978,
  "surface_m2_built": 92.0,
  "surface_m2_useful": 78.0,
  "n_rooms": 3,
  "climate_zone": "D3",
  "energy_certificate": { "rating": "E", "source": "estimated" },
  "ite_fetch_status": "ok",
  "ite_data": { "result": "favorable_con_deficiencias" }
}

GET/properties/{id}/cadastral

Datos catastrales

Devuelve la ficha catastral cruda asociada a la propiedad: uso, superficie, antigüedad y elementos constructivos según el Catastro.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/cadastral \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "cadastral_reference": "9872023VH5797S0001WX",
  "use": "residential",
  "surface_m2": 92.0,
  "year_built": 1978,
  "elements": [{ "type": "vivienda", "floor": "02", "door": "B" }]
}

GET/properties/{id}/energy-certificate

Certificado energético

Devuelve el certificado de eficiencia energética del inmueble. Si no se localiza en los registros oficiales de la comunidad autónoma, se devuelve una estimación basada en año de construcción y zona climática, marcada con source: "estimated".

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/energy-certificate \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "rating": "E",
  "primary_energy_kwh_m2_year": 168.4,
  "co2_kg_m2_year": 36.1,
  "source": "estimated",
  "registry": null
}

GET/properties/{id}/climate-zone

Zona climática (CTE)

Devuelve la zona climática del Código Técnico de la Edificación que aplica al inmueble, usada por el simulador para el cálculo de grados-día.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/climate-zone \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "climate_zone": "D3", "winter_zone": "D", "summer_zone": "3" }

GET/properties/{id}/ite

Inspección técnica del edificio

Devuelve los datos de inspección técnica del edificio obtenidos de los registros oficiales disponibles (actualmente Madrid y Comunitat Valenciana). Si no hay datos o el registro no responde, se devuelve ite_fetch_status distinto de "ok" y datos parciales o nulos.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/ite \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "ite_fetch_status": "ok",
  "result": "favorable_con_deficiencias",
  "inspection_date": "2021-06-14",
  "next_inspection_due": "2031-06-14",
  "deficiencies": ["fachada", "cubierta"]
}

GET/properties/{id}/thermal-envelope

Envolvente térmica estimada

Devuelve la estimación de la envolvente térmica (transmitancias y demanda) que el simulador determinista usa como base. Cálculo sin I/O, derivado de la zona climática y el año de construcción.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/thermal-envelope \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "u_wall_w_m2k": 1.42,
  "u_roof_w_m2k": 1.05,
  "heating_demand_kwh_m2_year": 96.0,
  "method": "cte_degree_days"
}

GET/properties/{id}/subsidies

Subvenciones aplicables

Devuelve las ayudas y subvenciones a la rehabilitación energética potencialmente aplicables al inmueble según su comunidad autónoma y características.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/subsidies \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "subsidies": [
    { "program": "PREE 5000", "scope": "municipio < 5000 hab", "max_pct": 0.4 },
    { "program": "Fondos Next Generation", "scope": "rehabilitación integral", "max_pct": 0.8 }
  ]
}

GET/properties/{id}/radon-risk

Riesgo de radón

Devuelve la clasificación de riesgo de radón del municipio según el mapa del CSN, relevante para recomendaciones de ventilación.

Endpoint en desarrollo activo según el roadmap acordado con cada partner. Contacta con el equipo para disponibilidad.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/radon-risk \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "radon_zone": "I", "risk_level": "low", "source": "CSN" }

PATCH/properties/{id}

Actualizar una propiedad

Actualiza campos editables del inmueble (datos que el partner aporta y que complementan el enriquecimiento automático).

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Cuerpo de la petición

Campo	Tipo	Descripción
n_rooms	integer	Número de estancias.
surface_m2_useful	number	Superficie útil en m².
year_built	integer	Año de construcción si difiere del catastral.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.
422	validation_error	Campo fuera de rango o tipo incorrecto.

curl -X PATCH https://api.ciflow.net/api/v1/partner-api/properties/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"n_rooms": 4}'

Respuesta de ejemplo

{ "property_id": "8f1c2d3e-...", "updated": true }

DELETE/properties/{id}

Eliminar una propiedad

Elimina el inmueble y sus datos derivados (simulaciones, recomendaciones e informes asociados). Operación irreversible.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X DELETE https://api.ciflow.net/api/v1/partner-api/properties/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "deleted": true }

Quick Lookup

Consultas puntuales sin crear una propiedad persistente. Útiles para validar datos antes de dar de alta el inmueble.

POST/lookup/cadastral

Lookup catastral

Resuelve una referencia catastral o una dirección de texto libre y devuelve la ficha catastral sin persistir nada.

Cuerpo de la petición

Campo	Tipo	Descripción
cadastral_reference	string	Referencia catastral (recomendado).
address	string	Dirección libre, alternativa si no hay referencia.

Errores

HTTP	Código	Cuándo
400	ambiguous_address	La dirección no se pudo geocodificar de forma unívoca.

curl -X POST https://api.ciflow.net/api/v1/partner-api/lookup/cadastral \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Respuesta de ejemplo

{
  "cadastral_reference": "9872023VH5797S0001WX",
  "address": "Calle Mayor 5, 28013 Madrid",
  "use": "residential",
  "year_built": 1978
}

POST/lookup/energy-certificate

Lookup certificado energético

Consulta el certificado energético por referencia catastral en los registros oficiales sin crear la propiedad.

Cuerpo de la petición

Campo	Tipo	Descripción
cadastral_reference*	string	Referencia catastral.

Errores

HTTP	Código	Cuándo
404	certificate_not_found	No hay certificado en los registros.

curl -X POST https://api.ciflow.net/api/v1/partner-api/lookup/energy-certificate \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Respuesta de ejemplo

{ "rating": "E", "source": "registry", "registry": "Comunidad de Madrid" }

POST/lookup/cups

Lookup CUPS

Resuelve el código CUPS (punto de suministro eléctrico) asociado a una dirección o referencia catastral.

Requiere acuerdo previo, contacta con el equipo.

Cuerpo de la petición

Campo	Tipo	Descripción
cadastral_reference	string	Referencia catastral.
address	string	Dirección libre.

Errores

HTTP	Código	Cuándo
403	agreement_required	El lookup de CUPS requiere acuerdo específico.

curl -X POST https://api.ciflow.net/api/v1/partner-api/lookup/cups \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cadastral_reference": "9872023VH5797S0001WX"}'

Respuesta de ejemplo

{ "cups": "ES0021000000000000XX0F", "distributor": "i-DE" }

Energy Data

Suministros, consentimientos de acceso a datos de distribuidora y facturas. La ingesta de consumo real alimenta el simulador y los informes.

GET/properties/{id}/consumption

Consumo energético

Devuelve la serie de consumo eléctrico del inmueble agregada a la granularidad solicitada. El origen puede ser distribuidora (con consentimiento) o facturas procesadas por OCR.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Parámetros de consulta

Campo	Tipo	Descripción
from*	date	Fecha inicio (ISO 8601, YYYY-MM-DD).
to*	date	Fecha fin (ISO 8601).
granularity	string	hourly \| daily \| monthly. Por defecto monthly.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.
409	no_consent	No hay consentimiento de distribuidora ni facturas cargadas.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/consumption?from=2026-01-01&to=2026-03-31&granularity=monthly \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "granularity": "monthly",
  "series": [
    { "period_start": "2026-01-01", "consumption_kwh": 412.0, "source": "datadis" },
    { "period_start": "2026-02-01", "consumption_kwh": 388.5, "source": "datadis" }
  ]
}

POST/properties/{id}/cups

Asociar un CUPS

Registra un punto de suministro eléctrico (CUPS) para el inmueble, incluyendo potencia contratada y tarifa.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Cuerpo de la petición

Campo	Tipo	Descripción
cups_code*	string	Código CUPS (20-22 caracteres).
distributor	string	Distribuidora.
contracted_power_p1_kw	number	Potencia contratada periodo 1.
tariff	string	Peaje de acceso, p.ej. 2.0TD.

Errores

HTTP	Código	Cuándo
422	invalid_cups	Formato de CUPS inválido.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/cups \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"cups_code": "ES0021000000000000XX0F", "tariff": "2.0TD"}'

Respuesta de ejemplo

{ "cups_id": "1a2b3c4d-...", "cups_code": "ES0021000000000000XX0F" }

POST/properties/{id}/cups/{cups}/datadis-consent

Solicitar consentimiento de distribuidora

Inicia el flujo de consentimiento para acceder a los datos de consumo de la distribuidora a través de Datadis para el CUPS indicado.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.
cups*	string	Código CUPS.

Cuerpo de la petición

Campo	Tipo	Descripción
nif*	string	NIF del titular del suministro.

Errores

HTTP	Código	Cuándo
409	consent_already_active	Ya existe un consentimiento vigente.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/cups/ES0021000000000000XX0F/datadis-consent \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"nif": "00000000T"}'

Respuesta de ejemplo

{ "consent_status": "pending", "expires_at": "2027-05-18T00:00:00Z" }

POST/properties/{id}/invoices

Subir una factura energética

Carga una factura (PDF o imagen) que ciflow procesa con OCR para extraer consumo, potencia y periodo. El resultado se incorpora a la serie de consumo del inmueble.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Cuerpo de la petición

Campo	Tipo	Descripción
file*	binary	Fichero de la factura (multipart/form-data).

Errores

HTTP	Código	Cuándo
422	unsupported_file	Formato de fichero no soportado.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/invoices \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@factura.pdf"

Respuesta de ejemplo

{ "invoice_id": "9f8e7d6c-...", "status": "processing" }

GET/properties/{id}/invoices

Listar facturas

Devuelve las facturas cargadas para el inmueble con su estado de procesamiento y los datos extraídos.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/invoices \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "invoices": [
    { "invoice_id": "9f8e7d6c-...", "status": "processed", "ocr_confidence": 0.97 }
  ]
}

Simulations

Simulador determinista de escenarios de mejora energética (aerotermia, aislamiento, fotovoltaica). Cálculo reproducible, sin I/O externo en caliente.

POST/properties/{id}/simulate

Ejecutar una simulación

Ejecuta un escenario de mejora energética sobre la propiedad. Combina la envolvente térmica estimada, datos de irradiación y tarifas, y devuelve ahorro, inversión y periodo de retorno junto con las subvenciones aplicables.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Cuerpo de la petición

Campo	Tipo	Descripción
scenario_type	string	heat_pump \| insulation \| pv \| full. Por defecto heat_pump.
inputs	object	Parámetros opcionales que sobrescriben los presets.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.
422	unknown_scenario	scenario_type no reconocido.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/simulate \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"scenario_type": "heat_pump"}'

Respuesta de ejemplo

{
  "scenario_type": "heat_pump",
  "outputs": {
    "annual_saving_eur": 612.0,
    "investment_eur": 8900.0,
    "payback_years": 11.4,
    "co2_reduction_kg_year": 1180.0
  },
  "thermal_envelope": { "heating_demand_kwh_m2_year": 96.0 },
  "subsidies": [{ "program": "Fondos Next Generation", "max_pct": 0.8 }]
}

GET/properties/{id}/simulations

Listar simulaciones

Devuelve el histórico de simulaciones ejecutadas sobre el inmueble.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/simulations \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "simulations": [
    { "id": "aa11bb22-...", "scenario_type": "heat_pump", "status": "completed" }
  ]
}

GET/simulations/{id}

Obtener una simulación

Devuelve el detalle de una simulación concreta, incluidos inputs y outputs.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la simulación.

Errores

HTTP	Código	Cuándo
404	simulation_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/simulations/aa11bb22-... \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "id": "aa11bb22-...",
  "scenario_type": "heat_pump",
  "status": "completed",
  "inputs": {},
  "outputs": { "annual_saving_eur": 612.0, "payback_years": 11.4 }
}

POST/simulations/{id}/compare

Comparar simulaciones

Compara la simulación indicada con otras del mismo inmueble y devuelve un cuadro comparativo de ahorro, inversión y retorno.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Simulación base.

Cuerpo de la petición

Campo	Tipo	Descripción
against*	string[]	IDs de simulaciones a comparar.

Errores

HTTP	Código	Cuándo
404	simulation_not_found	Alguna simulación no existe.

curl -X POST https://api.ciflow.net/api/v1/partner-api/simulations/aa11bb22-.../compare \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"against": ["cc33dd44-..."]}'

Respuesta de ejemplo

{
  "base": "aa11bb22-...",
  "comparison": [
    { "id": "cc33dd44-...", "delta_saving_eur": 120.0, "delta_payback_years": -1.8 }
  ]
}

Recommendations

Recomendación técnica de soluciones del catálogo: puntúa por specs reales (rendimiento, dimensionado de potencia frente a la demanda, U-valor, capacidad…), estado ITE y preferencia de fabricante del tenant. Opcionalmente recalcula la economía con el precio real del producto y añade un resumen en lenguaje natural.

GET/properties/{id}/recommendations

Obtener recomendaciones

Devuelve el ranking de soluciones recomendadas para el inmueble. El motor puntúa cada producto por adecuación técnica usando las specs del catálogo: rendimiento (SCOP/COP a -7 °C), dimensionado de potencia frente a la demanda térmica estimada del inmueble (penaliza equipos infra/sobredimensionados), temperatura mínima de operación en zonas frías, U-valor y espesor en aislamiento, eficiencia y Wp en fotovoltaica, MPPT/híbrido en inversores y capacidad/ciclos en baterías. Suma señales del estado ITE y, si el tenant tiene un fabricante preferente configurado, aplica el boost definido por configuración (nunca por nombre en código). Si se envía simulation_id, recalcula la economía con el coste real del producto mejor valorado e incluye un resumen en lenguaje natural.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Parámetros de consulta

Campo	Tipo	Descripción
scenario_type	string	Escenario base. Por defecto heat_pump.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/properties/{id}/recommendations?scenario_type=heat_pump \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "category": "heat_pump",
  "ranked_items": [
    { "sku": "GEN-A-12", "name": "Bomba de calor 12 kW", "score": 0.91,
      "reason": "SCOP 4.2 · 12 kW (bien dimensionada para ~10 kW)",
      "manufacturer_boost": false },
    { "sku": "GEN-B-08", "name": "Bomba de calor 8 kW", "score": 0.78,
      "reason": "SCOP 4.0 · 8 kW: puede quedarse corta para ~10 kW" }
  ],
  "manufacturer_boost_applied": false,
  "summary_text": "Para el escenario heat_pump, la opción mejor valorada es...",
  "recommended_economics": {
    "investment_eur": 7500, "annual_savings_eur": 848,
    "payback_years": 8.8, "sku": "GEN-A-12",
    "generic_investment_eur": 9971
  }
}

POST/recommendations/{id}/feedback

Enviar feedback de recomendación

Registra feedback del partner sobre una recomendación (aceptada, descartada, motivo) para alimentar el seguimiento comercial.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la recomendación.

Cuerpo de la petición

Campo	Tipo	Descripción
outcome*	string	accepted \| rejected \| deferred.
reason	string	Motivo opcional.

Errores

HTTP	Código	Cuándo
404	recommendation_not_found	No existe o no pertenece a tu tenant.

curl -X POST https://api.ciflow.net/api/v1/partner-api/recommendations/{id}/feedback \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "accepted"}'

Respuesta de ejemplo

{ "recorded": true }

Clients

Gestión de la cartera de clientes finales del partner, sus inmuebles e informes acumulados.

POST/clients

Crear un cliente

Da de alta un cliente final dentro de tu tenant.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Cuerpo de la petición

Campo	Tipo	Descripción
name*	string	Nombre del cliente.
email	string	Email de contacto.
external_ref	string	Referencia en tu CRM.

Errores

HTTP	Código	Cuándo
422	validation_error	Datos de cliente inválidos.

curl -X POST https://api.ciflow.net/api/v1/partner-api/clients \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Comunidad C/ Mayor 5"}'

Respuesta de ejemplo

{ "client_id": "dd44ee55-...", "name": "Comunidad C/ Mayor 5" }

GET/clients

Listar clientes

Devuelve la cartera de clientes con paginación por cursor. Usa el campo next_cursor para la siguiente página.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de consulta

Campo	Tipo	Descripción
cursor	string	Cursor de la página siguiente.
limit	integer	Tamaño de página (máx. 100, por defecto 50).

Errores

HTTP	Código	Cuándo
400	invalid_cursor	Cursor mal formado.

curl -X GET https://api.ciflow.net/api/v1/partner-api/clients?limit=50 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "clients": [{ "client_id": "dd44ee55-...", "name": "Comunidad C/ Mayor 5" }],
  "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}

GET/clients/{id}

Obtener un cliente

Devuelve el detalle de un cliente.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del cliente.

Errores

HTTP	Código	Cuándo
404	client_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/clients/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "client_id": "dd44ee55-...", "name": "Comunidad C/ Mayor 5", "properties_count": 3 }

PATCH/clients/{id}

Actualizar un cliente

Actualiza datos de contacto o referencia externa de un cliente.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del cliente.

Cuerpo de la petición

Campo	Tipo	Descripción
email	string	Nuevo email de contacto.

Errores

HTTP	Código	Cuándo
404	client_not_found	No existe o no pertenece a tu tenant.

curl -X PATCH https://api.ciflow.net/api/v1/partner-api/clients/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@finca.es"}'

Respuesta de ejemplo

{ "client_id": "dd44ee55-...", "updated": true }

GET/clients/{id}/properties

Inmuebles de un cliente

Devuelve los inmuebles asociados a un cliente.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del cliente.

Errores

HTTP	Código	Cuándo
404	client_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/clients/{id}/properties \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "properties": [{ "property_id": "8f1c2d3e-...", "address": "Calle Mayor 5" }] }

POST/clients/{id}/reports

Generar informe acumulado de cliente

Genera un informe acumulado que consolida todos los inmuebles del cliente: datos catastrales, consumo real, telemetría y simulaciones, en un único documento para cerrar la venta y fidelizar.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del cliente.

Cuerpo de la petición

Campo	Tipo	Descripción
period_start	date	Inicio del periodo del informe.
period_end	date	Fin del periodo del informe.

Errores

HTTP	Código	Cuándo
404	client_not_found	No existe o no pertenece a tu tenant.

curl -X POST https://api.ciflow.net/api/v1/partner-api/clients/{id}/reports \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"period_start": "2026-01-01", "period_end": "2026-04-30"}'

Respuesta de ejemplo

{ "report_id": "rep-77aa88-...", "status": "processing" }

GET/clients/{id}/reports

Listar informes de un cliente

Devuelve los informes acumulados generados para el cliente.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del cliente.

Errores

HTTP	Código	Cuándo
404	client_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/clients/{id}/reports \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "reports": [{ "report_id": "rep-77aa88-...", "status": "completed" }] }

Leads

Oportunidades comerciales. ciflow prioriza automáticamente edificios con ITE caducando o deficiencias relevantes como leads de alto valor.

POST/leads

Crear un lead

Crea una oportunidad comercial, opcionalmente vinculada a un inmueble.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Cuerpo de la petición

Campo	Tipo	Descripción
property_id	uuid	Inmueble asociado.
value_estimate_eur	number	Valor estimado de la oportunidad.

Errores

HTTP	Código	Cuándo
422	validation_error	Datos de lead inválidos.

curl -X POST https://api.ciflow.net/api/v1/partner-api/leads \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"value_estimate_eur": 8900}'

Respuesta de ejemplo

{ "lead_id": "lead-99cc-...", "status": "new" }

GET/leads

Listar leads

Devuelve los leads del tenant, filtrables por estado.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de consulta

Campo	Tipo	Descripción
status	string	new \| contacted \| won \| lost.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Falta o es inválida la cabecera X-API-Key.

curl -X GET https://api.ciflow.net/api/v1/partner-api/leads?status=new \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "leads": [{ "lead_id": "lead-99cc-...", "status": "new" }] }

PATCH/leads/{id}

Actualizar un lead

Actualiza el estado o los datos de un lead.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del lead.

Cuerpo de la petición

Campo	Tipo	Descripción
status	string	Nuevo estado del lead.

Errores

HTTP	Código	Cuándo
404	lead_not_found	No existe o no pertenece a tu tenant.

curl -X PATCH https://api.ciflow.net/api/v1/partner-api/leads/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "contacted"}'

Respuesta de ejemplo

{ "lead_id": "lead-99cc-...", "updated": true }

POST/leads/{id}/notes

Añadir una nota a un lead

Añade una nota de seguimiento comercial al lead.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del lead.

Cuerpo de la petición

Campo	Tipo	Descripción
text*	string	Contenido de la nota.

Errores

HTTP	Código	Cuándo
404	lead_not_found	No existe o no pertenece a tu tenant.

curl -X POST https://api.ciflow.net/api/v1/partner-api/leads/{id}/notes \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "Visita agendada"}'

Respuesta de ejemplo

{ "lead_id": "lead-99cc-...", "notes_count": 3 }

Devices & Telemetry

Registra los equipos instalados (climatización, fotovoltaica, monitorización) y envía su telemetría. ciflow la convierte en gráficas, anomalías e insights para el cliente final.

POST/devices

Registrar un dispositivo

Registra (o actualiza, si ya existe el external_id) un equipo dentro de tu tenant, opcionalmente vinculado a un inmueble. Operación idempotente respecto a external_id.

Cuerpo de la petición

Campo	Tipo	Descripción
external_id*	string	Tu identificador único del equipo.
device_type*	string	heat_pump \| pv_inverter \| meter \| sensor.
model	string	Modelo del equipo.
serial_number	string	Número de serie.
property_id	uuid	Inmueble donde está instalado.
metadata	object	Datos libres opacos para ciflow.

Errores

HTTP	Código	Cuándo
422	validation_error	Falta external_id o device_type.
429	rate_limited	Se superó el límite de escritura.

curl -X POST https://api.ciflow.net/api/v1/partner-api/devices \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "PLC-0427", "device_type": "heat_pump", "property_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f"}'

Respuesta de ejemplo

{
  "device_id": "dev-aa11-...",
  "external_id": "PLC-0427",
  "created": true
}

GET/devices

Listar dispositivos

Devuelve todos los equipos registrados en tu tenant con su estado y última telemetría recibida.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Falta o es inválida la cabecera X-API-Key.

curl -X GET https://api.ciflow.net/api/v1/partner-api/devices \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "devices": [
    {
      "device_id": "dev-aa11-...",
      "external_id": "PLC-0427",
      "device_type": "heat_pump",
      "status": "active",
      "last_telemetry_at": "2026-05-18T09:12:00Z"
    }
  ]
}

GET/devices/{external_id}

Obtener un dispositivo

Devuelve el detalle de un equipo por su external_id.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Tu identificador del equipo.

Errores

HTTP	Código	Cuándo
404	device_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "device_id": "dev-aa11-...",
  "external_id": "PLC-0427",
  "device_type": "heat_pump",
  "status": "active"
}

PATCH/devices/{external_id}

Actualizar un dispositivo

Actualiza estado, modelo, número de serie o metadatos de un equipo.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Tu identificador del equipo.

Cuerpo de la petición

Campo	Tipo	Descripción
status	string	active \| inactive \| maintenance.
model	string	Modelo.
serial_number	string	Número de serie.
metadata	object	Metadatos libres.

Errores

HTTP	Código	Cuándo
404	device_not_found	No existe o no pertenece a tu tenant.

curl -X PATCH https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "maintenance"}'

Respuesta de ejemplo

{ "ok": true }

DELETE/devices/{external_id}

Dar de baja un dispositivo

Marca el equipo como decommissioned. La telemetría histórica se conserva.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Tu identificador del equipo.

Errores

HTTP	Código	Cuándo
404	device_not_found	No existe o no pertenece a tu tenant.

curl -X DELETE https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "ok": true, "status": "decommissioned" }

POST/devices/{external_id}/telemetry

Enviar telemetría

Ingesta un lote de registros de telemetría para el equipo. Los registros válidos se aceptan (HTTP 202) y los inválidos se devuelven en drops sin abortar el lote. Dispara el evento device.telemetry_received.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Tu identificador del equipo.

Cuerpo de la petición

Campo	Tipo	Descripción
records*	array	Lista de objetos { ts (ISO 8601), metric, value_numeric \| value_string, unit }.

Errores

HTTP	Código	Cuándo
404	device_not_found	No existe o no pertenece a tu tenant.
429	rate_limited	Se superó el límite de telemetría (5000 records/min).

curl -X POST https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427/telemetry \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"records": [{"ts": "2026-05-18T09:00:00Z", "metric": "cop", "value_numeric": 3.8, "unit": "ratio"}, {"ts": "2026-05-18T09:05:00Z", "metric": "power", "value_numeric": 1.42, "unit": "kW"}]}'

Respuesta de ejemplo

{
  "accepted": 2,
  "dropped": 0,
  "drops": []
}

GET/devices/{external_id}/telemetry

Consultar telemetría

Devuelve la telemetría del equipo para una métrica y rango, opcionalmente agregada (avg, min, max, sum).

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Tu identificador del equipo.

Parámetros de consulta

Campo	Tipo	Descripción
metric*	string	Métrica a consultar (p.ej. cop, power).
from*	datetime	Inicio (ISO 8601).
to*	datetime	Fin (ISO 8601).
aggregation	string	raw \| hourly \| daily \| monthly.

Errores

HTTP	Código	Cuándo
404	device_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427/telemetry?metric=cop&from=2026-05-01T00:00:00Z&to=2026-05-18T00:00:00Z&aggregation=daily \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "metric": "cop",
  "aggregation": "daily",
  "points": [{ "period_start": "2026-05-18", "avg": 3.74, "min": 2.9, "max": 4.5 }]
}

GET/devices/{external_id}/insights

Insights del dispositivo

Devuelve los insights detectados sobre el equipo (anomalías de rendimiento, fallos, eficiencia degradada) con severidad y categoría.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
external_id*	string	Tu identificador del equipo.

Errores

HTTP	Código	Cuándo
404	device_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/devices/PLC-0427/insights \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "insights": [
    {
      "severity": "warning",
      "category": "efficiency_degradation",
      "message": "COP medio 18% por debajo de la línea base",
      "detected_at": "2026-05-17T22:00:00Z"
    }
  ]
}

POST/devices/bulk-telemetry

Telemetría masiva multi-dispositivo

Ingesta telemetría de varios equipos en una sola llamada. Pensado para sincronizaciones por lotes desde un gateway o PLC central.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Cuerpo de la petición

Campo	Tipo	Descripción
items*	array	Lista de objetos { external_id, records: [...] }.

Errores

HTTP	Código	Cuándo
429	rate_limited	Se superó el límite de telemetría.

curl -X POST https://api.ciflow.net/api/v1/partner-api/devices/bulk-telemetry \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"external_id": "PLC-0427", "records": [{"ts": "2026-05-18T09:00:00Z", "metric": "cop", "value_numeric": 3.8}]}]}'

Respuesta de ejemplo

{ "accepted": 240, "dropped": 0, "devices": 12 }

Reports

Generación y descarga de informes energéticos. El PDF se entrega proxied por la API (bytes), nunca como URL de almacenamiento.

POST/properties/{id}/report

Generar informe de inmueble

Ejecuta el escenario indicado, calcula recomendaciones y subvenciones y devuelve directamente el PDF del informe energético (application/pdf). El identificador del informe viaja en la cabecera X-Report-Id.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador de la propiedad.

Cuerpo de la petición

Campo	Tipo	Descripción
scenario_type	string	Escenario base. Por defecto heat_pump.

Errores

HTTP	Código	Cuándo
404	property_not_found	No existe o no pertenece a tu tenant.
422	unknown_scenario	scenario_type no reconocido.

curl -X POST https://api.ciflow.net/api/v1/partner-api/properties/{id}/report \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"scenario_type": "heat_pump"}' \
  --output informe.pdf

Respuesta de ejemplo

# Respuesta: application/pdf (bytes)
# Cabecera: X-Report-Id: rep-77aa88-99bb-...

GET/reports/{id}

Metadatos de un informe

Devuelve los metadatos del informe (estado, tamaño, fechas) sin descargar el PDF.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del informe.

Errores

HTTP	Código	Cuándo
404	report_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/reports/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "report_id": "rep-77aa88-...",
  "status": "completed",
  "file_size_bytes": 184320,
  "generated_at": "2026-05-18T09:20:00Z"
}

GET/reports/{id}/download

Descargar el PDF de un informe

Descarga el PDF de un informe ya generado. El contenido se sirve proxied por la API.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del informe.

Errores

HTTP	Código	Cuándo
404	report_not_found	No existe o no pertenece a tu tenant.

curl https://api.ciflow.net/api/v1/partner-api/reports/{id}/download \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  --output informe.pdf

Respuesta de ejemplo

# Respuesta: application/pdf (bytes)

GET/reports

Listar informes

Devuelve los informes generados en tu tenant.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Falta o es inválida la cabecera X-API-Key.

curl -X GET https://api.ciflow.net/api/v1/partner-api/reports \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "reports": [{ "report_id": "rep-77aa88-...", "status": "completed" }] }

Catalog

Catálogo de soluciones sobre el que razona el recomendador. Los planes Pro+ pueden cargar su propio catálogo.

GET/catalog/items

Listar ítems del catálogo

Devuelve los ítems del catálogo activo de tu tenant, filtrables por categoría.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de consulta

Campo	Tipo	Descripción
category	string	Categoría (p.ej. aerotermia, aislamiento).

Errores

HTTP	Código	Cuándo
401	missing_api_key	Falta o es inválida la cabecera X-API-Key.

curl -X GET https://api.ciflow.net/api/v1/partner-api/catalog/items?category=aerotermia \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "items": [
    { "sku": "GEN-A-12", "category": "aerotermia", "name": "Bomba de calor 12 kW", "price_eur": 6200 }
  ]
}

GET/catalog/items/{sku}

Obtener un ítem del catálogo

Devuelve el detalle de un ítem del catálogo por su SKU.

Endpoint en desarrollo activo según el roadmap acordado con cada partner.

Parámetros de ruta

Campo	Tipo	Descripción
sku*	string	SKU del ítem.

Errores

HTTP	Código	Cuándo
404	item_not_found	SKU no encontrado en tu catálogo.

curl -X GET https://api.ciflow.net/api/v1/partner-api/catalog/items/GEN-A-12 \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "sku": "GEN-A-12",
  "category": "aerotermia",
  "name": "Bomba de calor 12 kW",
  "specs": { "power_kw": 12, "scop": 4.6 },
  "price_eur": 6200
}

POST/catalog/items

Crear un ítem de catálogo (Pro+)

Añade un ítem al catálogo propio del tenant. Disponible en planes Pro y Enterprise.

Disponible en planes Pro+ y en desarrollo activo según el roadmap acordado con cada partner.

Cuerpo de la petición

Campo	Tipo	Descripción
sku*	string	SKU único en tu catálogo.
category*	string	Categoría del ítem.
name*	string	Nombre comercial.
specs	object	Especificaciones técnicas.
price_eur	number	Precio de referencia.

Errores

HTTP	Código	Cuándo
403	plan_required	Requiere plan Pro o Enterprise.
409	sku_exists	El SKU ya existe en tu catálogo.

curl -X POST https://api.ciflow.net/api/v1/partner-api/catalog/items \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"sku": "GEN-A-12", "category": "aerotermia", "name": "Bomba de calor 12 kW", "price_eur": 6200}'

Respuesta de ejemplo

{ "sku": "GEN-A-12", "created": true }

Webhooks

Notificaciones push firmadas con HMAC-SHA256. Suscríbete a eventos para reaccionar en tiempo real desde tu CRM.

Eventos disponibles

Evento	Descripción
property.created	Se ha dado de alta un inmueble.
property.enriched	El pipeline de enriquecimiento del inmueble ha finalizado.
simulation.completed	Una simulación ha terminado.
report.generated	Un informe se ha generado y está disponible.
device.telemetry_received	Se ha ingerido un lote de telemetría de un equipo.
device.insight_detected	Se ha detectado un insight sobre un equipo.
device.fault_detected	Se ha detectado un fallo en un equipo.
lead.created	Se ha creado un lead (incluye leads priorizados automáticamente).
lead.status_changed	Ha cambiado el estado de un lead.
client.report_ready	El informe acumulado de un cliente está listo.

Verificación de la firma (HMAC SHA-256)

Cada entrega incluye la cabecera X-Ciflow-Signature con formato sha256=…. Verifica siempre la firma con el secreto del webhook antes de procesar el cuerpo:

import hmac, hashlib

def verify(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

POST/webhooks

Registrar un webhook

Registra una URL a la que ciflow enviará eventos. La respuesta incluye el secret HMAC una única vez: guárdalo, se usa para verificar la firma X-Ciflow-Signature de cada entrega.

Cuerpo de la petición

Campo	Tipo	Descripción
url*	string	URL HTTPS de destino.
events	string[]	Lista de eventos a los que suscribirse. Vacío = todos.

Errores

HTTP	Código	Cuándo
422	validation_error	URL inválida o no HTTPS.

curl -X POST https://api.ciflow.net/api/v1/partner-api/webhooks \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://tu-crm.example.com/hooks/ciflow", "events": ["simulation.completed", "report.generated"]}'

Respuesta de ejemplo

{
  "id": "wh-aa11-...",
  "url": "https://tu-crm.example.com/hooks/ciflow",
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx",
  "note": "Guarda el secret: firma X-Ciflow-Signature (HMAC-SHA256). No se vuelve a mostrar."
}

GET/webhooks

Listar webhooks

Devuelve los webhooks registrados en tu tenant con su estado y última entrega.

Errores

HTTP	Código	Cuándo
401	missing_api_key	Falta o es inválida la cabecera X-API-Key.

curl -X GET https://api.ciflow.net/api/v1/partner-api/webhooks \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "webhooks": [
    {
      "id": "wh-aa11-...",
      "url": "https://tu-crm.example.com/hooks/ciflow",
      "events": ["simulation.completed"],
      "status": "active",
      "last_delivery_at": "2026-05-18T09:30:00Z"
    }
  ]
}

DELETE/webhooks/{id}

Eliminar un webhook

Elimina un webhook. ciflow deja de enviar entregas a esa URL.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del webhook.

Errores

HTTP	Código	Cuándo
404	webhook_not_found	No existe o no pertenece a tu tenant.

curl -X DELETE https://api.ciflow.net/api/v1/partner-api/webhooks/{id} \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{ "deleted": true }

GET/webhooks/{id}/deliveries

Historial de entregas

Devuelve las últimas 50 entregas de un webhook con código de respuesta, número de intentos y estado.

Parámetros de ruta

Campo	Tipo	Descripción
id*	uuid	Identificador del webhook.

Errores

HTTP	Código	Cuándo
404	webhook_not_found	No existe o no pertenece a tu tenant.

curl -X GET https://api.ciflow.net/api/v1/partner-api/webhooks/{id}/deliveries \
  -H "X-API-Key: cf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta de ejemplo

{
  "deliveries": [
    {
      "id": "del-99-...",
      "event": "simulation.completed",
      "status_code": 200,
      "delivered": true,
      "attempts": 1,
      "last_attempt_at": "2026-05-18T09:30:01Z"
    }
  ]
}

SDKs

Los SDKs oficiales están en desarrollo. Mientras tanto, cualquier cliente HTTP estándar funciona: la API es REST sobre JSON con autenticación por cabecera. Los ejemplos de esta página cubren cURL, Python (requests) y Node (fetch).

Changelog

Versión	Fecha	Cambios
v1.5	2026-05-12	Telemetría de equipos: ingesta individual y por lotes, insights y detección de anomalías.
v1.4	2026-04-03	Informe acumulado por cliente (catastro + consumo + telemetría + simulaciones).
v1.3	2026-03-06	Webhooks con entregas firmadas (HMAC SHA-256) y reintentos.
v1.2	2026-02-10	Recomendaciones de catálogo con feedback comercial.
v1.1	2026-01-15	Presets del simulador y comparación de escenarios.
v1.0	2025-12-09	Versión inicial: propiedades, consulta rápida y simulaciones.

Esquemas

Objetos reutilizados a lo largo de la API.

Property

Inmueble dado de alta en ciflow y sus datos enriquecidos.

Campo	Tipo	Descripción
property_id	uuid	Identificador único del inmueble.
cadastral_reference	string	Referencia catastral (14 o 20 caracteres).
address	string \| null	Dirección postal.
municipality	string \| null	Municipio.
province	string \| null	Provincia.
ccaa	string \| null	Comunidad autónoma.
postcode	string \| null	Código postal.
year_built	integer \| null	Año de construcción.
surface_m2_built	number \| null	Superficie construida (m²).
surface_m2_useful	number \| null	Superficie útil (m²).
n_rooms	integer \| null	Número de estancias.
climate_zone	string \| null	Zona climática CTE (p.ej. D3).
energy_certificate	object \| null	Certificado energético (ver Schema).
ite_fetch_status	string \| null	Estado de la consulta ITE (ok, not_found, error).
ite_data	object \| null	Datos de inspección técnica del edificio.

EnergyCertificate

Certificado de eficiencia energética, real o estimado.

Campo	Tipo	Descripción
rating	string	Letra de calificación (A–G).
primary_energy_kwh_m2_year	number \| null	Energía primaria no renovable.
co2_kg_m2_year	number \| null	Emisiones de CO₂.
source	string	registry (oficial) o estimated (estimación por año/zona).
registry	string \| null	Registro autonómico de origen, si aplica.

Simulation

Resultado de un escenario de mejora energética.

Campo	Tipo	Descripción
id	uuid	Identificador de la simulación.
scenario_type	string	heat_pump \| insulation \| pv \| full.
status	string	pending \| completed \| failed.
inputs	object	Parámetros de entrada usados.
outputs	object \| null	annual_saving_eur, investment_eur, payback_years, co2_reduction_kg_year.
subsidies_applicable	object \| null	Subvenciones consideradas.

Recommendation

Ranking de soluciones del catálogo para un inmueble.

Campo	Tipo	Descripción
category	string	Escenario recomendado (heat_pump, insulation, pv, hybrid).
ranked_items	array	Lista ordenada de { catalog_item_id, sku, name, category, score 0-1, reason, manufacturer_boost }.
manufacturer_boost_applied	boolean	Si se aplicó el boost de fabricante preferente del tenant.
summary_text	string	Resumen en lenguaje natural de la recomendación (IA, con fallback determinista).
recommended_economics	object	Economía recalculada con el coste real del producto mejor valorado: { investment_eur, annual_savings_eur, payback_years, irr_pct, sku, name, generic_investment_eur }. Null si no se vincula simulación.

Device

Equipo instalado y registrado por el partner.

Campo	Tipo	Descripción
device_id	uuid	Identificador interno de ciflow.
external_id	string	Identificador del equipo en tus sistemas.
device_type	string	heat_pump \| pv_inverter \| meter \| sensor.
model	string \| null	Modelo del equipo.
serial_number	string \| null	Número de serie.
property_id	uuid \| null	Inmueble donde está instalado.
status	string	active \| inactive \| maintenance \| decommissioned.
last_telemetry_at	datetime \| null	Última telemetría recibida.
metadata	object	Datos libres opacos para ciflow.

TelemetryRecord

Una medida puntual enviada por un equipo.

Campo	Tipo	Descripción
ts	datetime	Marca temporal de la medida (ISO 8601).
metric	string	Nombre de la métrica (p.ej. cop, power, temp_in).
value_numeric	number \| null	Valor numérico.
value_string	string \| null	Valor textual (para métricas no numéricas).
unit	string \| null	Unidad (p.ej. kW, ratio, °C).

Report

Informe energético generado (PDF proxied por la API).

Campo	Tipo	Descripción
report_id	uuid	Identificador del informe.
status	string	processing \| completed \| failed.
scope	string	property \| client (informe acumulado).
file_size_bytes	integer \| null	Tamaño del PDF.
period_start	date \| null	Inicio del periodo (informes acumulados).
period_end	date \| null	Fin del periodo (informes acumulados).
generated_at	datetime	Fecha de generación.

Lead

Oportunidad comercial, posiblemente priorizada automáticamente.

Campo	Tipo	Descripción
lead_id	uuid	Identificador del lead.
property_id	uuid \| null	Inmueble asociado.
status	string	new \| contacted \| won \| lost.
value_estimate_eur	number \| null	Valor estimado de la oportunidad.
notes	array	Notas de seguimiento.
next_action_at	datetime \| null	Próxima acción programada.

Webhook

Suscripción a eventos con entregas firmadas.

Campo	Tipo	Descripción
id	uuid	Identificador del webhook.
url	string	URL HTTPS de destino.
events	string[]	Eventos suscritos (vacío = todos).
status	string	active \| disabled.
last_delivery_at	datetime \| null	Última entrega.

¿Listo para integrar? Solicita tu API key como partner aprobado.

Solicitar acceso partner