DoJa Python SDK 🚀

El DoJa SDK es la biblioteca oficial de Python para conectar, automatizar y escalar envíos masivos o transaccionales a través de WhatsApp Cloud API (Meta) y el Gateway de Emails DoJa.

Con DoJa SDK, te olvidas de integraciones complejas. Usa la misma licencia para disparar notificaciones en ambos canales mediante un código elegante, rápido y sin dependencias pesadas.

💻 Instalación

Solo requieres Python 3.7+ y pip. El SDK no empuja dependencias pesadas ni requiere que instales las librerías oficiales de Meta o proveedores externos de Email:

pip install doja-sdk

📚 Índice

1. WhatsApp (Mensajería, Templates y Multimedia)
2. Email (Texto, HTML y Adjuntos)
3. Módulo Asíncrono (AsyncIO) ⚡
4. Manejo de Errores y Excepciones
5. Optimización y Desempeño

1. Módulo de WhatsApp 💬

Para interactuar con WhatsApp, necesitas tu Token de Licencia DoJa, tu Token de Meta y tu Phone ID.

Configuración Inicial

from doja_sdk import DojaClient, DojaAuthError

try:
    wa = DojaClient(
        doja_token="TU-LICENCIA-DOJA",   # Token de tu suscripción en DoJa
        whatsapp_token="EAAB12345...",    # Token Permanente/Temporal de Meta
        phone_id="100747123456"           # Identificador de tu número en Meta
    )
    print("¡Conexión a WhatsApp exitosa!")
except DojaAuthError as e:
    print(f"Error de licencia: {e}")

Ejemplos de Envío (WhatsApp)

(Nota: El destinatario debe incluir código de país sin el signo '+'. Ej: "525512345678")

Mensaje de Texto Simple:

wa.send_text("525512345678", "¡Hola! Hemos recibido tu pago exitosamente.")

Documentos (PDF, Facturas, Excel):

wa.send_document(
    to="525512345678", 
    url="https://ejemplo.com/factura.pdf", 
    caption="Aquí tienes tu factura del mes 📝", 
    filename="Factura_Octubre.pdf" # Opcional: Nombre con el que se descarga
)

Imágenes y Promocionales:

wa.send_image(
    to="525512345678", 
    url="https://ejemplo.com/promo.jpg", 
    caption="¡Aprovecha nuestro descuento de temporada!"
)

Ubicación Compartida (Abre interactivo en Google Maps/Waze):

wa.send_location(
    to="525512345678", 
    latitude=19.432608, 
    longitude=-99.133209, 
    name="Sucursal Centro", 
    address="Centro Histórico, CDMX, México"
)

Botones Interactivos (Máximo 3 botones):

botones = [
    {"id": "soporte", "title": "Hablar con Soporte"},
    {"id": "ventas", "title": "Cotizar Servicios"}
]

wa.send_interactive_button(
    to="525512345678", 
    body_text="¿En qué área podemos apoyarte hoy?", 
    buttons_list=botones
)

Listas Desplegables (Ideal para menús largos):

secciones = [
    {
        "title": "Áreas de Atención",
        "rows": [
            {"id": "1", "title": "Soporte", "description": "Fallas técnicas"},
            {"id": "2", "title": "Ventas", "description": "Nuevas suscripciones"}
        ]
    }
]

wa.send_interactive_list(
    to="525512345678", 
    body_text="Por favor selecciona el área deseada:", 
    button_text="Ver Opciones", 
    sections=secciones
)

Templates Aprobados por Meta: (Requerido para iniciar conversación fuera de la ventana de atención de 24 hrs)

Variables POSICIONALES ({{1}}, {{2}}, ...):

wa.send_template(
    to="525512345678",
    template_name="confirmacion_pedido",  # Nombre idéntico al de Meta
    language_code="es",
    body_variables=["Juan", "#123456", "Mañana a las 15:00 hrs"]
)

Variables NOMBRADAS ({{nombre_cliente}}, {{folio}}, ...):

wa.send_template(
    to="525512345678",
    template_name="confirmacion_pedido",
    language_code="es",
    body_variables_named={
        "nombre_cliente": "Juan",
        "folio": "#123456",
        "fecha_entrega": "Mañana a las 15:00 hrs",
    }
)

[!NOTE] body_variables y body_variables_named son mutuamente excluyentes. Una plantilla de WhatsApp usa o bien placeholders posicionales ({{1}}) o bien nombrados ({{nombre}}), nunca ambos en el mismo body. Si pasas los dos, el SDK lanza DojaValidationError.

2. Módulo de Email 📧

El Módulo de Email está diseñado para ser extremadamente intuitivo. Para autenticarte, no requieres doble token. Tu clave de licencia de DoJa funciona automáticamente como la llave para despachar los correos mediante nuestro proveedor subyacente (Resend).

Configuracion Rapida - Email

from doja_sdk import DojaEmailClient

try:
    email = DojaEmailClient(
        doja_token="TU-LICENCIA-DOJA",           # La licencia que DoJa valida
        external_id="LA_LLAVE_DE_SERVICIO",      # ID proporcionado por el integrador
        from_address="no-reply@tuempresa.com"    # Remitente verificado
    )
    print("¡Conexión de Email exitosa!")
except DojaAuthError as e:
    print(f"Error de licencia o permisos: {e}")

Ejemplos de Envío (Email)

Texto Plano Rápido:

email.send(
    to="cliente@empresa.com",
    subject="Confirmación de Registro",
    body="Gracias por registrarte en nuestra plataforma."
)

Email con HTML enriquecido:

email.send(
    to="cliente@empresa.com",
    subject="Bienvenido a tu suscripción Pro",
    body="<h1>¡Hola Juan!</h1><p>Tu cuenta ya está activa. <a href='https://app.doja.com'>Ingresa aquí</a>.</p>",
    html=True
)

Email con Archivos Adjuntos (Rutas Locales o URLs): (El SDK procesa archivos locales codificándolos en Base64 o transfiere la URL de forma directa al Gateway)

email.send(
    to="cliente@empresa.com",
    subject="Tu Factura de Marzo",
    body="Adjuntamos tu factura digitalizada correspondiente a este mes.",
    attachments=[
        "/ruta/absoluta/factura_marzo.pdf",         # Archivo local
        "https://ejemplo.com/cotizacion_final.xlsx" # Archivo por URL
    ]
)

Funciones Avanzadas (Múltiples destinatarios, CC, BCC y Reply-To):

email.send(
    to="gerente@empresa.com, asistente@empresa.com",   # Puedes separar por comas
    subject="Reporte Financiero Semanal",
    body="<h2>Reporte Generado</h2><p>Aquí tienes el archivo de esta semana.</p>",
    html=True,
    cc=["director@empresa.com"],
    bcc=["auditoria@empresa.com"],
    reply_to="soporte@empresa.com",
    attachments=["/ruta/reporte.xlsx", "/ruta/resumen.pdf"]
)

3. Módulo Asíncrono (AsyncIO) ⚡

Ideal para aplicaciones modernas como FastAPI o procesos que requieren alta concurrencia. El SDK asíncrono utiliza httpx bajo el capó para realizar operaciones no bloqueantes.

WhatsApp Asíncrono

import asyncio
from doja_sdk import AsyncDojaClient

async def main():
    wa = AsyncDojaClient(
        doja_token="TU-LICENCIA-DOJA",
        whatsapp_token="EAAB...",
        phone_id="123456789"
    )

    # Envío no bloqueante
    await wa.send_text("525512345678", "¡Hola desde Async SDK!")

asyncio.run(main())

Email Asíncrono

from doja_sdk import AsyncDojaEmailClient

async def send_welcome():
    email = AsyncDojaEmailClient(
        doja_token="TU-LICENCIA-DOJA",
        external_id="LLAVE_RESEND",
        from_address="hola@tuempresa.com"
    )

    await email.send(
        to="cliente@ejemplo.com",
        subject="Bienvenido",
        body="<h1>Registro Exitoso</h1>",
        html=True
    )

4. Manejo de Errores 🛡️

El SDK expone excepciones estandarizadas que te permiten saber exactamente qué falló (si fue un problema de saldo, de licencia o de la API destino). Las puedes importar todas desde doja_sdk:

from doja_sdk import (
    DojaClient,
    DojaAuthError,
    DojaQuotaExceeded,
    DojaAPIError
)

try:
    client = DojaClient(...)
    client.send_text(...)

except DojaAuthError as e:
    # 404 No encontrado, 422 Inválido, 409 Suspendido, o no tiene el canal (WhatsApp/Email) pagado
    print(f"Problema con la Licencia: {e}")

except DojaQuotaExceeded as e:
    # 409 La licencia es válida, pero el cliente se acabó su bolsa de mensajes
    print(f"Saldo Agotado: {e}")

except DojaAPIError as e:
    # Ocurre si Meta o Resend rechazan la petición (Ej: plantilla mal armada, mal teléfono, adjunto pesado)
    print(f"Problema con el Proveedor Destino: {e}")

5. Optimización y Desempeño 🚀

Esta versión del SDK incluye mejoras críticas:

• Caché de Licencia: La validación de licencia se cachea localmente durante 5 minutos para evitar picos de latencia en cada mensaje enviado.
• Logging: Hemos reemplazado los print por el módulo logging. Puedes configurar el nivel de detalle:

  import logging
  logging.getLogger("doja_sdk").setLevel(logging.DEBUG)
  

• Consumo Robusto: Las llamadas de consumo de créditos se ejecutan con manejadores de errores internos para asegurar que un fallo en el servidor de licencias no interrumpa tu proceso principal.

¿Dudas adicionales o soporte técnico?
Comunícate directamente a: contact@dojaconsulting.cloud