Cómo descargar recibos de CFE con una API

Sí: puedes descargar los recibos de CFE con una API, sin entrar al portal ni bajar PDFs uno por uno. Conectas tu cuenta de CFE una sola vez, y a partir de ahí una API descarga cada recibo por ti y te lo entrega en JSON —con su desglose de energía, demanda y factor de potencia— listo para usar en tu sistema. Este es el flujo que resuelve la API de Batu: en vez de capturar números a mano cada mes, tu integración pide los recibos de un contrato y recibe datos estructurados.

Esta guía explica cómo funciona ese flujo: por qué el camino manual no escala, qué te entrega exactamente una API de recibos de CFE, y cómo pedir tus recibos con un ejemplo en curl, JavaScript y Python.

Por qué bajar los recibos a mano no escala

El portal de CFE está pensado para personas, no para sistemas. Para un solo contrato es tolerable; para un portafolio, es un trabajo mensual que crece con cada uno:

1. Entrar al portal con las credenciales del contrato.
2. Navegar contrato por contrato —cada uno tiene su propio RPU—.
3. Descargar el PDF de cada recibo.
4. Capturar a mano los números que necesitas: consumo, demanda, factor de potencia, total.
5. Repetir todo el mes siguiente.

A escala, eso son días de trabajo cada mes y una fuente constante de errores de captura. Y no es un esfuerzo que se haga una vez: se repite en cada cierre de facturación, para cada RPU.

Una API invierte el flujo. Conectas la cuenta una vez y la descarga deja de ser una tarea manual: pides los recibos con una petición y los recibes ya estructurados. El trabajo tedioso —obtener el recibo de cada contrato y normalizar sus conceptos— lo hace la API por ti.

Qué es una API para descargar recibos de CFE

Una API (interfaz de programación) es una forma de que dos sistemas se hablen con un contrato definido: tu sistema hace una petición y recibe una respuesta con una estructura predecible. Aplicado a CFE, una API para descargar recibos hace tres cosas:

• Se conecta a CFE por ti. Autorizas tu cuenta una vez; la API mantiene esa conexión viva.
• Descarga y normaliza cada recibo. Cada mes baja el recibo de cada RPU y traduce sus conceptos —que en el recibo aparecen con etiquetas y formatos distintos— a un conjunto de llaves estables.
• Entrega los datos como JSON. Tu sistema consume esos datos directamente: para facturar a tus clientes, conciliar pagos, calcular ahorro o detectar anomalías.

La clave es la palabra normalizar. Un recibo de CFE no viene en un formato pensado para software: llega como PDF y, en tarifas de demanda, con un XML asociado, con conceptos que cambian de nombre y de estructura entre tarifas y divisiones. Una API se encarga de esa traducción para que tú recibas siempre la misma forma.

Qué trae un recibo de CFE (y qué te entrega la API)

Para entender qué expone la API, conviene ver primero qué hay en el recibo. Un recibo comercial o industrial de CFE tiene cuatro secciones:

1. Datos del contrato — tu RPU (número único de contrato), la tarifa asignada, la división de CFE que te suministra y el periodo de facturación.
2. Medición — los kWh consumidos y, en tarifas de demanda, los kW de demanda medida.
3. Desglose de cargos — energía, demanda (que se divide en capacidad y distribución), factor de potencia, alumbrado público (DAP) e IVA.
4. Resumen — el subtotal, el IVA (16 % sobre energía, demanda, factor de potencia y cargo fijo) y el total a pagar.

Si quieres el detalle de cada concepto, lo cubrimos en Cómo leer el recibo de CFE. Lo relevante aquí es que la tarifa determina qué conceptos trae el recibo —y, por lo tanto, qué campos entrega la API—. Estas son las tarifas comerciales e industriales más comunes:

En una tarifa horaria como la GDMTH, el recibo cobra la energía a precio distinto según la franja horaria —base, intermedia y punta—, y esos horarios varían por división y por temporada (verano y fuera de verano). Una API para recibos absorbe esa variabilidad: sin importar la tarifa o la división, te entrega los conceptos en la misma estructura.

Del PDF de CFE a JSON estructurado

Este es el corazón del asunto. El mismo recibo que en el portal es un PDF para leer con los ojos, por API llega como un objeto que tu sistema entiende directamente:

Cada concepto del recibo queda en una llave estable —kwh para el consumo, demandaMaxima para la demanda, factorPotencia para el factor de potencia— acompañada de su significado, para que no tengas que adivinar qué es cada número. Los datos del contrato (RPU, tarifa, división) viajan junto a los conceptos del recibo, así que un solo objeto te dice de qué contrato es, bajo qué tarifa y con qué cargos.

Cómo pedir los recibos: un ejemplo

En la práctica, descargar los recibos de un contrato es una petición autenticada. La API de Batu vive en app.batuenergy.com/api/v1, y te autenticas con tu API key como Bearer token en el encabezado Authorization. Para pedir los recibos de un RPU:

# Autenticación: API key como Bearer token en el encabezado Authorization
curl "https://app.batuenergy.com/api/v1/bills?rpu=TU_RPU" \
-H "Authorization: Bearer TU_API_KEY"

La respuesta trae los recibos de ese contrato, cada uno con su bloque contract y sus conceptos ya normalizados:

{
"status": "success",
"items": 1,
"total": 24,
"has_more": true,
"next_cursor": "eyJpZCI6ImJpbF8wMUpRMks…",
"data": [
  {
    "id": "bil_01JQ2K7R8MW3XZ",
    "object": "bill",
    "currency": "MXN",
    "total": "84560.00",
    "year_month": "2026-05",
    "period_start": "2026-04-01",
    "period_end": "2026-04-30",
    "tariff": "GDMTH",
    "payment_status": "paid",
    "contract": {
      "rpu": "123456789012",
      "pricing_zone": "Jalisco",
      "is_monitored": true
    },
    "concepts": {
      "kwh": "12450",
      "demandaMaxima": "48.20",
      "factorPotencia": "94.2"
    }
  }
],
"concept_meaning": {
  "kwh": { "label": "kWh Totales", "units": "kWh" },
  "demandaMaxima": { "label": "Demanda Máxima", "units": "kW" },
  "factorPotencia": { "label": "Factor de Potencia", "units": "%" }
}
}

Un par de detalles que ahorran sorpresas: los valores numéricos viajan como cadenas de texto (así conservan la precisión decimal exacta del recibo) y los identificadores llevan un prefijo (bil_ para un recibo). Cuando un contrato tiene más recibos de los que caben en una página, el campo has_more te avisa y el next_cursor te deja pedir la siguiente página, hasta recorrer todo el histórico. Los valores del ejemplo son ilustrativos; los límites de uso y el modelo de créditos dependen de tu plan de acceso.

API o scraper propio: qué te toca mantener

Es tentador resolver esto con un script que entre al portal y baje los PDFs. Funciona en la demo; el problema aparece después. El portal de CFE no es una API: no tiene contrato, ni versiones, ni garantías, y cambia sin avisar. Cuando cambia —el login, un formato, un captcha—, tu scraper se rompe justo en el cierre de facturación, que es cuando más lo necesitas.

• Mantenimiento constante. Cada cambio del lado de CFE te obliga a parchar y volver a probar; puede ser cada mes.
• Casos borde interminables. Distintas tarifas, formatos de RPU, lecturas estimadas, PDFs y XMLs que no siempre cuadran.
• Costo real oculto. El tiempo de ingeniería y las fallas en producción terminan costando más que consumir una API ya mantenida.

Con una API, ese mantenimiento es problema de quien la opera. Tú te concentras en tu producto; la conexión con CFE la mantiene la API.

Cómo lo resuelve Batu

Batu ya descarga recibos de CFE a escala, y expone esos datos por API. Conectas la cuenta de CFE una vez y los recibos, el consumo y las tarifas quedan disponibles como datos estructurados: tú tomas la batuta y construyes encima —facturación, reportes de ahorro, detección de anomalías—, mientras nosotros nos encargamos de la parte tediosa de obtener y normalizar los datos de CFE. El acceso a la API es para cuentas autenticadas; puedes solicitar acceso o ver una demo.

Si en vez de construir sobre la API lo que quieres es gestionar el consumo de tu propia empresa multi-sitio —descargar los recibos de todas tus sucursales, monitorear pagos y detectar anomalías—, eso lo cubre la plataforma de Batu directamente, sin escribir código.

• API de CFE: recibos, consumo y tarifas — la referencia de endpoints, autenticación y ejemplos.
• Cómo leer el recibo de CFE — qué significa cada concepto que entrega la API.
• Calcula el costo de implementar Batu — estima créditos y plan según tu volumen de recibos y sitios.

Fuentes

• ACUERDO CT/11.SE/8-2025 — Comisión Nacional de Energía (CNE), publicado en el DOF el 23 de enero de 2026. Estructura tarifaria de CFE (tarifas comerciales e industriales, tensiones y bloques horarios). La CNE absorbió a la Comisión Reguladora de Energía (CRE) en la reforma energética de 2025; los acuerdos previos de la CRE siguen vigentes bajo la CNE.
• Acuerdo A/158/2024 (DOF, 24 de enero de 2025) y Código de Red RES/550/2021 — factor de potencia y umbrales aplicables.
• API pública v1 de Batu — base URL, endpoints y forma de la respuesta de recibos (GET /api/v1/bills). Los valores mostrados en los ejemplos son ilustrativos.