# CONFIGURACIÓN DE WEBHOOKS - AgendaPro → Siigo
# =================================================

## 📌 URLs Disponibles

### **Modo Producción** (Crea clientes en Siigo)
```
https://knelaspa.mch.com.co/webhook.php
```

### **Modo Prueba** (Solo registra, NO crea clientes)
```
https://knelaspa.mch.com.co/webhook_test.php
```

### **Monitor de Webhooks** (Ver datos recibidos)
```
https://knelaspa.mch.com.co/monitor_webhooks.php
```

---

## 🧪 PRIMERO: Confirmar que AgendaPro envía datos

### Paso 1: Configurar webhook en MODO PRUEBA
1. Inicia sesión en AgendaPro
2. Ve a **Configuración** → **Integraciones** → **Webhooks**
3. Click en **"Agregar Webhook"**
4. **URL del Endpoint**: `https://knelaspa.mch.com.co/webhook_test.php`  ⚠️ Nota: `webhook_TEST.php`
5. **Eventos**: 
   - ✅ `client.created`
   - ✅ `client.updated`
6. **Método**: POST
7. **Content-Type**: application/json
8. Guarda la configuración

### Paso 2: Crear cliente de prueba en AgendaPro
1. Ve a **Clientes** → **Nuevo Cliente**
2. Llena los datos:
   - Nombre: `TEST WEBHOOK`
   - Apellido: `PRUEBA`
   - Cédula: `9999999999`
   - Email: `test@webhook.com`
   - Teléfono: `3001234567`
3. **Guarda el cliente**

### Paso 3: Verificar que llegó el webhook
Abre el monitor: **https://knelaspa.mch.com.co/monitor_webhooks.php**

Deberías ver:
- ✅ Webhook recibido con estado "test_mode"
- 📋 Datos del cliente (nombre, email, teléfono, cédula)
- ⏱️ Tiempo de respuesta
- 🔍 JSON completo enviado por AgendaPro

**¿No aparece nada?** → Verifica la configuración del webhook en AgendaPro

---

## ✅ DESPUÉS: Activar modo producción

Una vez confirmado que AgendaPro envía datos correctamente:

### Paso 1: Cambiar a webhook de producción
1. Ve a AgendaPro → **Configuración** → **Integraciones** → **Webhooks**
2. Edita el webhook existente
3. Cambia la URL a: `https://knelaspa.mch.com.co/webhook.php`  ⚠️ Sin el `_test`
4. Guarda

### Paso 2: Probar con cliente real
1. Crea un cliente REAL en AgendaPro
2. Verifica en Siigo que se creó automáticamente (Terceros → Clientes)
3. Verifica en monitor_webhooks.php que aparece como "ÉXITO"

---

## 🔧 Referencia Técnica

### Estructura del Webhook AgendaPro

```json
{
  "event": "client.created",
  "data": {
    "id": 12345,
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "identification_number": "1234567890",
    "address": "Calle 123 #45-67"
  }
}
```

---

## 🧪 Prueba Manual con PowerShell

Para simular un webhook sin usar AgendaPro:

```powershell
# Probar MODO TEST (no crea cliente en Siigo)
$body = @{
    event = "client.created"
    data = @{
        id = 99999
        first_name = "Juan"
        last_name = "Pérez"
        email = "juan.perez@test.com"
        identification_number = "1234567890"
        phone = "+573001234567"
        address = "Calle 123 #45-67"
    }
} | ConvertTo-Json

Invoke-WebRequest -Uri "https://knelaspa.mch.com.co/webhook_test.php" `
    -Method POST `
    -Body $body `
    -ContentType "application/json"
```

**Respuesta esperada (modo test):**
```json
{
  "status": "test_mode",
  "message": "Webhook received successfully (TEST MODE - no client created in Siigo)",
  "event_type": "client.created",
  "received_data": {
    "agendapro_id": 99999,
    "name": "Juan Pérez",
    "email": "juan.perez@test.com",
    "phone": "+573001234567",
    "identification": "1234567890"
  }
}
```

---

## 🔍 Verificación y Monitoreo

### Ver webhooks recibidos en tiempo real
**https://knelaspa.mch.com.co/monitor_webhooks.php**

Esta página muestra:
- ✅ Últimos 50 webhooks recibidos
- 📊 Estadísticas del día (total, exitosos, errores)
- ⏱️ Tiempo promedio de respuesta
- 🔍 Datos completos enviados por AgendaPro
- 🔄 Auto-refresh cada 10 segundos

### Consultas SQL (alternativa)

```sql
-- Ver último webhook recibido
SELECT * FROM http_logs 
WHERE target = 'agendapro_webhook' 
ORDER BY created_at DESC 
LIMIT 1;

-- Ver cliente sincronizado
SELECT 
    cm.agendapro_client_id,
    cm.siigo_customer_id,
    cm.last_sync
FROM clients_map cm
ORDER BY last_sync DESC
LIMIT 5;

-- Ver uso de API por webhooks hoy
SELECT 
    service_name,
    execution_mode,
    call_count
FROM api_quota_tracking
WHERE call_date = CURDATE()
  AND execution_mode = 'webhook';
```

---

## 🚨 Solución de Problemas

### Webhook no se ejecuta
1. Verifica que la URL esté correcta en AgendaPro
2. Revisa logs en AgendaPro (sección Webhooks → Ver logs)
3. Verifica que eventos `client.created` y `client.updated` estén habilitados
4. Abre https://knelaspa.mch.com.co/monitor_webhooks.php para ver si llegan

### Cliente no se crea en Siigo
1. Revisa `http_logs` para ver el error:
   ```sql
   SELECT error, res_body_json 
   FROM http_logs 
   WHERE target = 'siigo' AND status_code >= 400
   ORDER BY created_at DESC LIMIT 1;
   ```

2. Verifica que cliente tenga **cédula** (campo obligatorio en Siigo)

3. Revisa Partner-Id en `.env`:
   ```
   SIIGO_PARTNER_ID=kanelaspa
   ```

### Webhook recibido pero cliente ya existe
El webhook detecta duplicados automáticamente:
```json
{
  "status": "skipped",
  "message": "Client already exists in Siigo",
  "siigo_id": "existing-id"
}
```
✅ Esto es **normal** y evita duplicados

---

## ⚡ Ventajas de Webhooks

✅ **Sincronización instantánea** (segundos después de crear en AgendaPro)  
✅ **Sin polling** (no gasta cuota haciendo consultas periódicas)  
✅ **Bajo uso de API** (solo cuando hay cambios reales)  
✅ **Trackeable** (todos los webhooks se registran en http_logs)  
✅ **Modo prueba** (webhook_test.php para verificar sin crear clientes reales)

---

## 📝 Notas Importantes

1. **No excede cuota**: Los webhooks usan `execution_mode='webhook'` separado de live_today/backfill
2. **Sin duplicados**: Verifica `clients_map` antes de crear
3. **Seguro**: Todos los webhooks se loguean para auditoría
4. **Fallback**: Si webhook falla, la sincronización programada lo captura después

---

## 🔗 Enlaces Rápidos

| Propósito | URL |
|-----------|-----|
| 🧪 **Webhook TEST** (no crea clientes) | https://knelaspa.mch.com.co/webhook_test.php |
| ✅ **Webhook PRODUCCIÓN** (crea clientes) | https://knelaspa.mch.com.co/webhook.php |
| 📊 **Monitor de Webhooks** (ver datos) | https://knelaspa.mch.com.co/monitor_webhooks.php |
| 📈 **Monitor de API** (uso general) | https://knelaspa.mch.com.co/monitor_api.php |
| 🔄 **Test de Sincronización** (manual) | https://knelaspa.mch.com.co/web_test_sync.php |

---

## 🎯 Resumen del Flujo

```
1. Cliente creado en AgendaPro
   ↓
2. AgendaPro envía webhook POST
   ↓
3. webhook_test.php recibe y registra (MODO PRUEBA)
   O
   webhook.php recibe y crea en Siigo (MODO PRODUCCIÓN)
   ↓
4. Se guarda en clients_map
   ↓
5. Visible en monitor_webhooks.php
```

**Siempre empieza con `webhook_test.php` para confirmar que funciona!**