Cliente Node.js profesional para consultar transferencias SPEI en el portal CEP de Banxico.
- ✅ Validación completa de transferencias SPEI
- ✅ Descarga de comprobantes en PDF y XML
- ✅ Cliente independiente para PDF (sin conflictos)
- ✅ Datos estructurados parseados automáticamente
- ✅ Manejo robusto de errores específicos del CEP
- ✅ Soporte TypeScript completo con tipos incluidos
- ✅ Cero dependencias pesadas (solo 2 dependencias)
# Con pnpm (recomendado)
pnpm add cep-banxico
# Con npm
npm install cep-banxico
# Con yarn
yarn add cep-banxicoimport { Transferencia, configure } from 'cep-banxico';
// Configurar entorno (false = producción, true = beta)
configure(false);
// Validar transferencia (obtiene automáticamente todos los datos)
const transferencia = await Transferencia.validar(
'12-08-2025', // fecha
'TEST12345678901234567890', // clave de rastreo
'40012', // código banco emisor (BBVA MEXICO)
'90722', // código banco receptor (Mercado Pago W)
'000000001234567890', // cuenta
25000 // monto en centavos ($250.00)
);
// Datos disponibles inmediatamente
console.log(transferencia.ordenante.nombre); // "JOSE ALBERTO LOPEZ JIMENEZ"
console.log(transferencia.beneficiario.nombre); // "Jose Alberto Lopez Jimenez"
console.log(transferencia.montoPesos); // 250.00
console.log(transferencia.fechaOperacion); // Date object
// Descargar PDF (opcional - usa cliente independiente)
const pdfData = await transferencia.descargarPDF();const transferencia = await Transferencia.validar(fecha, claveRastreo, emisor, receptor, cuenta, monto);
// Todos los datos están disponibles inmediatamente
// XML incluido automáticamente, PDF opcional// El XML ya está incluido
const xmlData = transferencia.getXmlData();
// PDF requiere cliente independiente
const pdfData = await transferencia.descargarPDF();import {
Transferencia,
TransferenciaDict,
Cuenta,
TransferNotFoundError
} from 'cep-banxico';
// Tipos completamente tipados
const transferencia: Transferencia = await Transferencia.validar(
new Date('2023-12-15'),
'TEST123456789',
'40012', // BBVA MEXICO
'40072', // Banorte
'000000001234567890',
100000,
false
);
// Datos tipados automáticamente
const montoEnPesos: number = transferencia.montoPesos;
const xmlData: Buffer | null = transferencia.getXmlData();
const dict: TransferenciaDict = transferencia.toDict();
// Cuenta con tipos
const cuenta = new Cuenta('Juan Pérez', 'Cheques', 'BBVA', '123456789', 'RFC123456789');import {
TransferNotFoundError,
MaxRequestError,
CepNotAvailableError,
CepError
} from 'cep-banxico';
try {
const transferencia = await Transferencia.validar(/* parámetros */);
} catch (error) {
if (error instanceof TransferNotFoundError) {
console.log('Transferencia no encontrada');
} else if (error instanceof MaxRequestError) {
console.log('Límite de consultas excedido');
} else if (error instanceof CepNotAvailableError) {
console.log('CEP no disponible');
} else if (error instanceof CepError) {
console.log('Error del sistema CEP:', error.message);
}
}Método principal para validar y obtener datos de transferencias SPEI.
static async validar(fecha, claveRastreo, emisor, receptor, cuenta, monto, pagoABanco = false)Parámetros:
-
fecha(string): Fecha en formato DD-MM-YYYY -
claveRastreo(string): Clave de rastreo de la transferencia -
emisor(string): Código del banco emisor (ej: '40012' para BBVA) -
receptor(string): Código del banco receptor (ej: '90722' para Mercado Pago) -
cuenta(string): Número de cuenta del beneficiario -
monto(number): Monto en centavos (ej: 25000 = $250.00) -
pagoABanco(boolean, opcional): Si es pago a banco
Retorna: Promise<Transferencia> - Instancia con todos los datos parseados
Lanza: TransferNotFoundError, MaxRequestError, CepNotAvailableError, CepError
Descarga el comprobante PDF usando cliente independiente.
async descargarPDF()Retorna: Promise<Buffer> - Datos del archivo PDF
transferencia.fechaOperacion // Date - Fecha de la operación
transferencia.fechaAbono // Date - Fecha y hora del abono
transferencia.ordenante // Cuenta - Cuenta ordenante
transferencia.beneficiario // Cuenta - Cuenta beneficiario
transferencia.monto // number - Monto en centavos
transferencia.montoPesos // number - Monto en pesos (getter)
transferencia.iva // number - IVA
transferencia.concepto // string - Concepto
transferencia.claveRastreo // string - Clave de rastreo
transferencia.emisor // string - Banco emisor
transferencia.receptor // string - Banco receptor
transferencia.sello // string - Sello digital
transferencia.tipoPago // number - Tipo de pagocuenta.nombre // string - Nombre del titular
cuenta.banco // string - Nombre del banco
cuenta.numero // string - Número de cuenta
cuenta.rfc // string - RFC del titular
cuenta.tipoCuenta // string - Tipo de cuentaimport { BANKS, isValidBankCode, getBankName } from 'cep-banxico';
// Validar código de banco
isValidBankCode('40012') // true
// Obtener nombre por código
getBankName('40012') // 'BBVA MEXICO'
// Ver todos los bancos SPEI
console.log(BANKS);- Consultas por día: Banxico limita el número de consultas diarias
- Rate limiting: Evita hacer consultas masivas consecutivas
- Datos reales: Solo funciona con transferencias SPEI reales
- XML automático: Siempre se descarga y parsea automáticamente
- PDF independiente: Usa cliente separado para evitar conflictos
- Datos inmediatos: Todos los datos estructurados disponibles tras validar
- PDF: Comprobante visual para impresión
- XML: Datos estructurados originales del CEP
- ZIP: Archivo comprimido con múltiples formatos
# Clonar repositorio
git clone https://github.com:AlbertoJALJ/cep-nodejs.git
cd cep-nodejs
# Instalar dependencias
pnpm install
# Ejecutar ejemplo
pnpm startcep-nodejs/
├── src/
│ ├── transferencia.js # Clase principal
│ ├── client.js # Cliente HTTP
│ ├── cuenta.js # Modelo de cuenta
│ ├── exceptions.js # Errores específicos
│ └── banks.js # Catálogo SPEI
├── examples/
│ └── ejemplo-completo.js # Ejemplo funcional
├── index.js # Punto de entrada
├── package.json
├── README.md
└── LICENSE
Las contribuciones son bienvenidas. Para cambios importantes:
- Fork el proyecto
- Crea una rama feature (
git checkout -b feature/AmazingFeature) - Commit tus cambios (
git commit -m 'Add AmazingFeature') - Push a la rama (
git push origin feature/AmazingFeature) - Abre un Pull Request
Este proyecto está bajo la Licencia MIT - ver el archivo LICENSE para detalles.
- Inspirado en el paquete Python
cep-python - Portal CEP de Banxico por la funcionalidad oficial
- Comunidad Node.js por las herramientas de desarrollo
