@rodny/etecsa-core

Cliente no oficial para la API de ETECSA (https://www.tienda.etecsa.cu).
Esto elimina completamente las abstracciones y encriptados de los endpoints del servidor principal, siendo esta la única librería para este propósito.

Permite autenticación, consulta de servicios móviles, gestión de perfil, nomencladores y más.

• ¿Para qué es esto?
• ¿Cómo funciona?

Características

• Autenticación – Inicio de sesión, manejo de cookies y recuperación de contraseña.
• Perfil de usuario – Obtener datos, editar perfil, cerrar sesión.
• Servicios móviles – Consultar saldo, paquetes, estado de línea (prepago/postpago/SIM datos).
• Nomencladores – Provincias, municipios, interrupciones de Nauta y STB.
• Páginas públicas – Obtener paquetes, planes, ofertas, preguntas frecuentes.
• Manejo robusto de errores – Errores tipados con códigos específicos.
• TypeScript – Tipos completos incluidos tanto de las solicitudes como de las respuestas.
• Múltiples instancias – Soporta múltiples clientes independientes con sus propias sesiones.

[!important] Las consultas de saldo de los planes son independientes de un teléfono móvil, esto quiere decir que no utiliza codigos USSD, todo es directamente consumiendo la API

[!warning] Por favor no abusar del servicio! Esto es un método no oficial y el uso excesivo (por ejemplo, más de 30 solicitudes por segundo) puede traer el baneo temporal de la cuenta por detección de spam (se desconoce los métodos de detección de bots que se utiliza, mejor precaver).

🚀 Uso rápido

import { EtecsaClient } from '@rodny/etecsa-core';

// 1. Crear instancia del cliente
const etecsa = new EtecsaClient();

// 2. Inicializar el cliente (solo una vez por instancia)
await etecsa.init();

// 3. Iniciar sesión
await etecsa.auth.login({
  user: '+53 5555555',
  pass: 'tu_contraseña',
});

// 4. Obtener datos del perfil
const perfil = await etecsa.profile.me();
console.log(perfil.usuario.nombre);

// 5. Consultar estado de un servicio móvil
const estadoMovil = await etecsa.mobile.status();
console.log(`Saldo: ${estadoMovil.balance}`);

// 6. Cerrar sesión
await etecsa.auth.logout();

📚 API Principal

new EtecsaClient()

Crea una nueva instancia del cliente. Cada instancia mantiene su propia sesión y cookies independientes.

const etecsa = new EtecsaClient();

etecsa.init()

Debe llamarse una sola vez por instancia antes de cualquier otra operación.
Carga el entorno virtual y prepara los métodos de comunicación.

await etecsa.init();

🔐 etecsa.auth – Autenticación

| Método | Descripción | | ------------------------------ | ------------------------------------------------------- | | login({ user, pass }) | Inicia sesión y devuelve cookies de sesión. | | logout() | Cierra la sesión actual. | | sendCode(user) | Envía código de verificación para recuperar contraseña. | | verifyCode(user, code) | Verifica el código enviado. | | resetPassword(user, newPass) | Restablece la contraseña. | | save() | Guarda las cookies actuales (serializables a JSON). | | load(cookiesJson) | Restaura cookies desde JSON. | | clear() | Limpia todas las cookies. |

Ejemplo completo de recuperación:

await etecsa.auth.sendCode('+53 55555555');

// chequear el código de confirmación recibido
await etecsa.auth.verifyCode('+53 55555555', '123456');
await etecsa.auth.resetPassword('+53 55555555', 'nuevaPass123');

👤 etecsa.profile – Perfil de usuario

| Método | Descripción | | --------------------------------- | --------------------------------------------- | | me() | Obtiene datos completos del perfil. | | edit(data) | Edita nombre, apellidos, dirección, etc. | | mobileServices() | Lista de servicios móviles asociados. | | landlineServices() | Servicios de telefonía fija. | | nautaHogar() | Datos de Nauta Hogar. | | cashiersIds() | IDs de cajeros disponibles. | | ownCard() | Tarjeta propia asociada. | | verifyUser(id, tipo, usuario) | Verifica si un número/correo está disponible. | | generateCode(tipo, usuario) | Genera código para añadir servicio. | | verifyCode(usuario, code, tipo) | Verifica código para añadir servicio. |

📱 etecsa.mobile – Servicios móviles

| Método | Descripción | | ------------------ | ------------------------------------------- | | status(request?) | Obtiene estado (saldo, paquetes, voz, SMS). |

Uso: Si no pasas parámetros, usa el primer servicio móvil del perfil.
Puedes pasar { service, ci, typeci, sendSms } para consultar una línea específica.

// Usar el primer servicio del perfil
const estado = await etecsa.mobile.status();

// Consultar línea específica
const estado2 = await etecsa.mobile.status({
  service: '+53 55555555',
  sendSms: false,
});

🗺️ etecsa.nom – Nomencladores

| Método | Descripción | | ---------------------------- | ---------------------------------- | | provinces() | Lista de provincias. | | municipalities(provinceId) | Municipios de una provincia. | | nautaInterruptions() | Interrupciones del servicio Nauta. | | stbInterruptions() | Interrupciones de STB. |

🌐 etecsa.page – Datos públicos

| Método | Descripción | | ------------------- | ------------------------------------------------------------- | | home() | Datos de la página principal (banners, productos destacados). | | packages() | Paquetes de datos disponibles. | | plans() | Planes de telefonía. | | bags() | Bolsas de datos. | | bag() | Detalles de una bolsa específica. | | specialPlans() | Planes especiales. | | additionalPlans() | Planes adicionales. | | offers() | Ofertas y promociones. | | faq() | Preguntas frecuentes. |

Manejo de errores

Todos los errores de API lanzan una instancia de EtecsaApiError:

import { EtecsaClient, EtecsaApiError } from 'etecsa-client';

const etecsa = new EtecsaClient();
await etecsa.init();

try {
  await etecsa.auth.login({ user: 'invalido', pass: 'xxx' });
} catch (error) {
  if (error instanceof EtecsaApiError) {
    console.error(`Error ${error.status}: ${error.message}`);
    console.error('Detalles:', error.details);
  }
}

Códigos de error comunes:

• 203 – Usuario o contraseña incorrectos
• 226 – Límite de intentos excedido o ya registrado
• 403 – Sesión expirada
• 204 – Usuario no encontrado
• 423 – Servicio no disponible

Persistencia de sesión

Puedes guardar las cookies después de login() y restaurarlas en otra instancia:

const etecsa = new EtecsaClient();
await etecsa.init();
await etecsa.auth.login({ user: 'x', pass: 'y' });

// Guardar después de login
const cookiesGuardadas = etecsa.auth.save();

// En otra ejecución
const newEtecsa = new EtecsaClient();
await newEtecsa.init();
await newEtecsa.auth.load(cookiesGuardadas);
// Ahora la sesión sigue activa

Múltiples instancias

Puedes crear múltiples clientes independientes para manejar diferentes cuentas:

const client1 = new EtecsaClient();
const client2 = new EtecsaClient();

await Promise.all([client1.init(), client2.init()]);

await client1.auth.login({ user: '[email protected]', pass: '***' });
await client2.auth.login({ user: '[email protected]', pass: '***' });

// Cada cliente tiene su propia sesión
const perfil1 = await client1.profile.me();
const perfil2 = await client2.profile.me();