# DoJa Python SDK 🚀

El **DoJa SDK** es la librería oficial de Python para conectar, automatizar y escalar bots usando la **API Cloud Oficial de WhatsApp (Meta)**. Facilita la construcción de respuestas enriquecidas, botones interactivos y catálogos en minutos sin lidiar con los complejos requerimientos de configuración nativos de Facebook.

*Nota: El uso de este SDK está protegido. Requieres una licencia oficial expedida por DoJa Consulting para interactuar con los servidores de WhatsApp mediante esta capa.*

---

## 💻 Instalación

Solo requieres Python 3.7+ y `pip`:

```bash
pip install doja-sdk
```

---

## 🛠️ Configuración Rápida (Quickstart)

Para usar la librería, necesitas tu Token de Licencia de DoJa, tu Token Temporal/Permanente de Meta y tu ID del Número de Teléfono.

```python
from doja_sdk import DojaClient, DojaAuthError

try:
    client = DojaClient(
        doja_token="DOJA-SEC-TULICENCIA-AQUI",
        whatsapp_token="EAAB123456789...", 
        phone_id="100747123456"
    )
    print("¡Conectado exitosamente!")
except DojaAuthError as e:
    print(f"Error de validación de licencia: {e}")
```

---

## 💬 Tipos de Mensajes Soportados

Todas las funciones requieren el número de teléfono del destinatario **con su código de país (sin el signo + ni espacios)**. Ejemplo para México: `"525512345678"`.

### 1. Mensaje de Texto Simple
Envía alertas o notificaciones de texto plano.
```python
client.send_text("525512345678", "¡Hola! Tu cita está confirmada para mañana a las 11:00 am.")
```

### 2. Mensaje con Documento (PDF, Excel, etc.)
Envía archivos usando un enlace directo (URL).
```python
client.send_document(
    to="525512345678", 
    url="https://mi-dominio.com/recibo.pdf", 
    caption="Aquí tienes tu recibo de pago 📄", 
    filename="Recibo_Septiembre.pdf"
)
```

### 3. Mensaje con Imagen
Envía banners, fotos o flyers.
```python
client.send_image(
    to="525512345678", 
    url="https://mi-dominio.com/promo.jpg", 
    caption="¡Aprovecha nuestro descuento del 15%!"
)
```

### 4. Ubicación Práctica (Map Pin 📍)
El mensaje ideal para indicar direcciones de locales comerciales (Abre Maps/Waze nativo).
```python
client.send_location(
    to="525512345678", 
    latitude=19.432608, 
    longitude=-99.133209, 
    name="DoJa Barbershop Matriz", 
    address="Centro Histórico, CDMX, México"
)
```

### 5. Botones Interactivos (Hasta 3 Opciones)
Envía botones rápidos donde el usuario solo necesita tocar la pantalla.
```python
botones = [
    {"id": "btn_corte", "title": "✂️ Agendar Corte"},
    {"id": "btn_precios", "title": "💰 Ver Precios"},
]

client.send_interactive_button(
    to="525512345678", 
    body_text="¡Bienvenido a la Barbería DoJa! ¿Qué deseas hacer hoy?", 
    buttons_list=botones
)
```

### 6. Menú Rápido (Lista Interactiva de más de 3 opciones)
Envía un menú desplegable cuando tengas demasiadas opciones para un botón normal (ej: Horarios o múltiples servicios).
```python
secciones = [
    {
        "title": "Nuestros Servicios",
        "rows": [
            {"id": "svc_1", "title": "Corte Clásico", "description": "30 mins"},
            {"id": "svc_2", "title": "Barba Spa", "description": "20 mins"},
            {"id": "svc_3", "title": "Corte + Barba", "description": "45 mins"}
        ]
    }
]

client.send_interactive_list(
    to="525512345678", 
    body_text="Selecciona el servicio que más te interese:", 
    button_text="Desplegar Menú", 
    sections=secciones
)
```

---
**¿Dudas o Integraciones?** | Soporte: contact@dojaconsulting.cloud
