PyLibSuitETECSA 1.0.0b1

Una API que interactúa con los servicios web de ETECSA.

PyLibSuitETECSA

Una librería escrita en Python para SuitETECSA

PyLibSuitETECSA es una API que interactúa con los servicios ofrecidos por ETECSA, para facilitar el desarrollo de aplicaciones Python dedicadas a la gestión de estos mediante los portales de usuario y cautivo de nauta, ahorrándoles tiempo, esfuerzos y código a los desarrolladores.

Hasta el momento PyLibSuitETECSA implementa funciones para:

• En el caso del portal de usuario de nauta:
  • Iniciar sesión.
  • Obtener información de la cuenta logueada.
  • Recargar la cuenta logueada.
  • Transferir saldo a otra cuenta nauta.
  • Transferir saldo para pago de cuota (solo para cuentas Nauta Hogar).
  • Cambiar la contraseña de la cuenta de acceso.
  • Cambiar la contraseña de la cuenta de correo asociada.
  • Obtener las conexiones realizadas en el periódo año-mes especificado.
  • Obtener las recargas realizadas en el periódo año-mes especificado.
  • Obtener las transferencias realizadas en el periódo año-mes especificado.
  • Obtener los pagos de cuotas realizados en el periódo año-mes especificado (solo para cuentas Nauta Hogar).
  • Obtener las útimas (la cantidad puede ser definida por el desarrollador que use la librería; por defecto es 5) operaciones (las antes mencionadas).
• En el caso del portal cautivo de nauta:
  • Inicia sesión.
  • Cierra sesión.
  • Obtiene el tiempo disponible en la cuenta.
  • Obtiene el saldo de la cuenta.

Interactuar con el portal de usuario de nauta

Para interactuar con el portal de usuario de nauta PyLibSuitETECSA proporciona dos clases; la más sencilla de usar es UserPortalClient ubicada en PyLibSuitETECSA.api y es la que se recomienda para la mayoria de apps. Igualmente PyLibSuitETECSA proporciona la clase UserPortal ubicada en PyLibSuitETECSA.core.protocol, un protocolo que permite a los desarrolladores tener "más control" a la hora de interactuar con el portal.

Usando UserPortalClient

Ejercicio donde:

• Iniciamos sesión en el portal.
• Tratamos de recargar la cuenta.
• Tratamos de transferir saldo a otra cuenta.
• Obtenemos las últimas 5 connexiones de la cuenta y las imprimimos en pantalla.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from PyLibSuitETECSA.api import UserPortalClient
from PyLibSuitETECSA.core.exception import RechargeException,\
    TransferException
from PyLibSuitETECSA.utils import Action

user_portal_cli = UserPortalClient(
    "[e-mail]",   # Cambiar por una cuenta real
    "password"                  # Cambiar por la contraseña de la cuenta
)

# Crea una sesión que se almacena en la variable
# user_portal_cli.session
user_portal_cli.init_session()

# Obtiene la imagen captcha del portal y la guarda
# en un archivo llamado 'captcha.png'
with open('captcha.png', 'wb') as fp:
    fp.write(
        user_portal_cli.captcha_as_bytes
    )

# Loguea la cuenta en el portal
user_portal_cli.login(
    input('captcha code: ')
)

# Trata de recargar la cuenta y en caso de error
# lo imprime en pantalla
try:
    user_portal_cli.recharge(
        "1234567890123456"
    )
except RechargeException as ex:
    print(f'Error al recargar :: {ex.args[0]}')

# Trata de transferir saldo a otra cuenta y en caso
# de errores los inprime en pantalla
try:
    user_portal_cli.transfer(
        250.25,
        "[e-mail]"
    )
except TransferException as ex:
    print(f'Error al transferir :: {ex.args[0]}')

# Obtiene las últimas 5 conexiones realizadas por la cuenta
# y las imprime en pantalla en formato json
connections = user_portal_cli.get_lasts(
    Action.GET_CONNECTIONS
)
for connection in connections:
    print(connection.__dict__)

Salida:

captcha code: DCYTHZ
Error al recargar :: El código de recarga es incorrecto.
Error al transferir :: ['El campo saldo a transferir debe ser menor o igual que 14761']
{'start_session': datetime.datetime(2023, 1, 22, 22, 19, 11), 'end_session': datetime.datetime(2023, 1, 22, 22, 24, 8), 'duration': 297, 'uploaded': 275456, 'downloaded': 1782579, 'import_': 0.99}
{'start_session': datetime.datetime(2023, 1, 22, 11, 26, 8), 'end_session': datetime.datetime(2023, 1, 22, 14, 28, 13), 'duration': 10925, 'uploaded': 17637048, 'downloaded': 244454522, 'import_': 36.42}
{'start_session': datetime.datetime(2023, 1, 21, 16, 53, 29), 'end_session': datetime.datetime(2023, 1, 22, 1, 36, 8), 'duration': 31359, 'uploaded': 152746065, 'downloaded': 2168958484, 'import_': 104.53}
{'start_session': datetime.datetime(2023, 1, 20, 18, 19, 56), 'end_session': datetime.datetime(2023, 1, 20, 18, 25, 16), 'duration': 320, 'uploaded': 447488, 'downloaded': 8409579, 'import_': 1.07}
{'start_session': datetime.datetime(2023, 1, 20, 17, 29, 40), 'end_session': datetime.datetime(2023, 1, 20, 18, 12, 5), 'duration': 2545, 'uploaded': 7140802, 'downloaded': 113592238, 'import_': 8.49}

Métodos y propiedades de UserPortalClient

Métodos

Nauta

Método	Función
init_session	Crea la sesión donde se guardan las cookies y datos
login	Loguea al usuario en el portal y carga la información de la cuenta
recharge	Recarga la cuenta logueada
transfer	Transfiere saldo a otra cuenta nauta
change_password	Cambia la contraseña de la cuenta logueada
change_email_password	Cambia la contraseña de la cuenta de correo asociada a la cuenta logueada
get_lasts	Devuelve las últimas large action realizadas, donde large es la cantidad Ex: 5 y action las operaciones realizadas Ex: UserPortal.ACTION_CONNECTIONS (las action disponibles son: UserPortal.ACTION_CONNECTIONS, UserPortal.ACTION_RECHARGES, UserPortal.ACTION_TRANSFER y UserPortal.ACTION_QUOTE_FUNDS, esta última solo para nauta hogar)
get_connections	Devuelve las conexiones realizadas en el mes especificado incluyendo el año (año-mes: 2022-03)
get_recharges	Devuelve las recargas realizadas en el mes especificado incluyendo el año (año-mes: 2022-03)
get_transfers	Devuelve las transferencias realizadas en el mes especificado incluyendo el año (año-mes: 2022-03)

Nauta Hogar

Método	Función
pay_nauta_home	Transfiere saldo a la cuota de nauta hogar.
get_quotes_fund	Devuelve los fondos de cuota realizados en el mes especificado incluyendo el año (año-mes: 2022-03)

Propiedades

Nauta

Propiedad	Dato devuelto
captcha_as_bytes	Imagen captcha en bytes.
blocking_date	Fecha de bloqueo.
date_of_elimination	Fecha de eliminación.
account_type	Tipo de cuenta.
service_type	Tipo de servicio.
credit	Saldo.
time	Tiempo disponible.
mail_account	Cuenta de correo asociada.

Nauta Hogar

Propiedad	Dato devuelto
offer	Oferta
monthly_fee	Cuota mensual
download_speeds	Velocidad de bajada
upload_speeds	Velocidad de subida
phone	Teléfono
link_identifiers	Identificador del enlace
link_status	Estado del enlace
activation_date	Fecha de activación
blocking_date_home	Fecha de bloqueo
date_of_elimination_home	Fecha de eliminación
quota_fund	Fondo de cuota
voucher	Bono
debt	Deuda

Nota: Los métodos y propiedades disponibles para Nauta también lo están para Nauta Hogar.

Usando UserPortal

Mismo ejercicio que con la clase UserPortalClient

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from PyLibSuitETECSA.core.protocol import UserPortal
from PyLibSuitETECSA.core.exception import RechargeException,\
    TransferException
from PyLibSuitETECSA.utils import Action

# Crea una sesión que se almacena en la variable
# session
session = UserPortal.create_session()

# Obtiene la imagen captcha del portal y la guarda
# en un archivo llamado 'captcha.png'
with open('captcha.png', 'wb') as fp:
    fp.write(
        UserPortal.get_captcha(session)
    )

# Loguea la cuenta en el portal
UserPortal.login(
    session=session,
    username="[e-mail]",
    password="password",
    captcha_code=input('captcha code: ')
)

# Trata de recargar la cuenta y en caso de error
# lo imprime en pantalla
try:
    UserPortal.recharge(
        session=session,
        recharge_code="1234567890123456"
    )
except RechargeException as ex:
    print(f'Error al recargar :: {ex.args[0]}')

# Trata de transferir saldo a otra cuenta y en caso
# de errores los inprime en pantalla
try:
    UserPortal.transfer(
        session=session,
        mount_to_transfer=250.25,
        account_to_transfer="[e-mail]"
    )
except TransferException as ex:
    print(f'Error al transferir :: {ex.args[0]}')

# Obtiene las últimas 5 conexiones realizadas por la cuenta
# y las imprime en pantalla en formato json
connections = UserPortal.get_lasts(
    session=session,
    action=Action.GET_CONNECTIONS
)
for connection in connections:
    print(connection.__dict__)

Salida:

captcha code: 2GH9SV
Error al recargar :: El código de recarga es incorrecto.
Error al transferir :: ['El campo saldo a transferir debe ser menor o igual que 14761']
{'start_session': datetime.datetime(2023, 1, 22, 22, 19, 11), 'end_session': datetime.datetime(2023, 1, 22, 22, 24, 8), 'duration': 297, 'uploaded': 275456, 'downloaded': 1782579, 'import_': 0.99}
{'start_session': datetime.datetime(2023, 1, 22, 11, 26, 8), 'end_session': datetime.datetime(2023, 1, 22, 14, 28, 13), 'duration': 10925, 'uploaded': 17637048, 'downloaded': 244454522, 'import_': 36.42}
{'start_session': datetime.datetime(2023, 1, 21, 16, 53, 29), 'end_session': datetime.datetime(2023, 1, 22, 1, 36, 8), 'duration': 31359, 'uploaded': 152746065, 'downloaded': 2168958484, 'import_': 104.53}
{'start_session': datetime.datetime(2023, 1, 20, 18, 19, 56), 'end_session': datetime.datetime(2023, 1, 20, 18, 25, 16), 'duration': 320, 'uploaded': 447488, 'downloaded': 8409579, 'import_': 1.07}
{'start_session': datetime.datetime(2023, 1, 20, 17, 29, 40), 'end_session': datetime.datetime(2023, 1, 20, 18, 12, 5), 'duration': 2545, 'uploaded': 7140802, 'downloaded': 113592238, 'import_': 8.49}

Usando NautaClient

import time

from PyLibSuitETECSA.api import NautaClient  # se importa el cliente para el portal cautivo de nauta

nauta_ci = NautaClient(  # se instancia el cliente
    "[e-mail]",
    "Contraseña"
)

nauta_ci.init_session()  # se inicia la session donde se guardan las cookies y datos

with nauta_ci.login():  # se inicia sesión en el portal y se mantiene abierta durante un minuto
    print(nauta_ci.remaining_time)
    time.sleep(60)

Funciones y propiedades de UserPortalClient

Funciones

• init_session: Crea la session donde se guardan las cookies y datos
• login: Loguea al usuario en el portal
• logout: Cierra la sesión abierta
• load_last_session: Carga la última session creada

Propiedades

• is_logged_in: Si se está loagueado en el portal
• user_credit: Saldo de la cuenta
• remaining_time: Tiempo restante

Contribuir

IMPORTANTE: PyLibSuitETESA necesita compatibilidad con nauta hogar.

Todas las contribuciones son bienvenidas. Puedes ayudar trabajando en uno de los issues existentes. Clona el repo, crea una rama para el issue que estés trabajando y cuando estés listo crea un Pull Request.

También puedes contribuir difundiendo esta herramienta entre tus amigos y en tus redes. Mientras más grande sea la comunidad más sólido será el proyecto.

Si te gusta el proyecto dale una estrella para que otros lo encuentren más fácilmente.

Dependencias

requests~=2.27.1
beautifulsoup4~=4.10.0
pytest~=7.1.2
setuptools~=60.2.0