Create Leads

Crear Leads

Submit individual leads or batches. Returns 202 Accepted immediately.

Envía leads individuales o en lote. Retorna 202 Accepted inmediatamente.

Endpoint

Endpoint

Allowed Roles

Roles Permitidos

Proveedor, Administrador

Request — Individual Lead

Request — Lead Individual

{
    "lead": {
        "proveedor_lead_id": "PR-12345",
        "nombre": "Juan Pérez",
        "telefono": "+50512345678",
        "producto": "Laptop Dell",
        "precio": 500.00,
        "fecha_hora": "2025-01-15 10:30:00",
        "cliente_id": 5
    }
}

Request — Batch

Request — Lote

{
    "leads": [
        {"proveedor_lead_id":"PR-001","nombre":"Lead 1","telefono":"+50511111111","fecha_hora":"2025-01-15 10:00:00"},
        {"proveedor_lead_id":"PR-002","nombre":"Lead 2","telefono":"+50522222222","fecha_hora":"2025-01-15 10:05:00"}
    ]
}

Field Reference

Referencia de Campos

Response — Success 202

{
    "success": true,
    "message": "Lead(s) aceptado(s) para procesamiento",
    "accepted": 1,
    "inbox_id": 123
}

Response — Duplicate (Idempotent) 200

{
    "success": true,
    "message": "Lead(s) ya procesado(s) previamente",
    "accepted": 1,
    "duplicated": true
}

Assign Client to Leads

Asignar Cliente a Leads

Assign one or multiple leads to a specific client. Providers can only assign their own leads.

Asigna uno o múltiples leads a un cliente específico. Los proveedores solo pueden asignar sus propios leads.

Endpoint

Endpoint

Allowed Roles

Roles Permitidos

Proveedor (own leads only), Administrador

Proveedor (solo sus propios leads), Administrador

Request Body

Cuerpo de la Petición

{
    "cliente_id": 5,
    "lead_ids": [101, 102, 103],
    "observaciones": "Asignación manual"
}

Response — Success 200

{
    "success": true,
    "message": "Operación completada. 3 asignados a 'Cliente Juan'.",
    "updated": 3,
    "failed": 0,
    "total_processed": 3
}

Response — Partial Failure 200

{
    "success": true,
    "message": "Operación completada. 2 asignados a 'Cliente Juan'. (1 fallos)",
    "updated": 2,
    "failed": 1,
    "total_processed": 3,
    "failed_details": [
        {"lead_id": 103, "error": "No tienes permiso (No eres el proveedor creador)"}
    ]
}

Provider Metrics

Métricas de Proveedor

Retrieve specific lead metrics for the authenticated provider (or admin view of provider data).

Recupera métricas específicas de leads para el proveedor autenticado (o vista de admin de datos de proveedor).

Endpoint

Endpoint

Allowed Roles

Roles Permitidos

Proveedor, Administrador

Response — Success 200

Respuesta — Éxito 200

{
    "success": true,
    "data": {
        "total": 150,
        "procesados": 120,
        "en_espera": 30,
        "porcentaje_procesado": 80.0,
        "por_estado": [
            {"estado": "EN_ESPERA", "cantidad": 30},
            {"estado": "APROBADO", "cantidad": 100},
            {"estado": "CANCELADO", "cantidad": 20}
        ]
    }
}

Update Lead Status

Actualizar Estado de Lead

Update lead state with automatic normalization. Clients have full flexibility to change to any valid state.

Actualiza el estado del lead con normalización automática. Clientes tienen total flexibilidad para cambiar a cualquier estado válido.

Endpoint

Endpoint

Allowed Roles

Roles Permitidos

Cliente (owner only), Administrador

Cliente (solo propietario), Administrador

Request Body

Cuerpo de la Petición

{
    "estado": "Aprovado",
    "observaciones": "Cliente confirmó recepción"
}

Valid States & Aliases

Estados Válidos y Alias

Response — Success 200

{
    "success": true,
    "message": "Estado actualizado a APROBADO",
    "estado_anterior": "EN_ESPERA",
    "estado_nuevo": "APROBADO"
}

Response — Invalid State 400

{
    "success": false,
    "message": "Estado inválido: INVALID_STATE",
    "estados_validos": ["EN_ESPERA", "APROBADO", "CONFIRMADO", "EN_TRANSITO", "EN_BODEGA", "CANCELADO"]
}

Bulk Status Update

Actualización Masiva de Estado

Update the status of multiple leads simultaneously. Clients can only update leads they own (cliente_id), while admins can update any leads.

Actualiza el estado de múltiples leads simultáneamente. Los clientes solo pueden actualizar leads que les pertenecen (cliente_id), mientras que los admins pueden actualizar cualquier lead.

Endpoint

Endpoint

Allowed Roles

Roles Permitidos

Cliente (own leads only), Administrador

Cliente (solo sus propios leads), Administrador

Request Body

Cuerpo de la Petición

{
    "lead_ids": [123, 124, 125],
    "estado": "contactado",
    "observaciones": "Contactados vía campaña SMS"
}

Request Fields

Campos de la Petición

• lead_ids: Array of internal lead IDs.
• estado: New status (valid state or alias).
• observaciones (optional): Text note.

• lead_ids: Arreglo de IDs internos de leads.
• estado: Nuevo estado (válido o alias).
• observaciones (opcional): Nota de texto.

Example cURL

Ejemplo cURL

curl -X POST "http://localhost/paqueteriacz/api/crm/leads/bulk-status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{ "lead_ids": [123, 124, 125], "estado": "aprobado", "observaciones": "Procesados el 2026-01-02" }'

Response — All Success 200

Respuesta — Todo Exitoso 200

{
    "success": true,
    "message": "3 de 3 leads actualizados exitosamente",
    "updated": 3,
    "failed": 0,
    "total": 3,
    "estado_nuevo": "APROBADO",
    "results": [
        { "lead_id": 123, "success": true, "estado_anterior": "EN_ESPERA", "estado_nuevo": "APROBADO" },
        { "lead_id": 124, "success": true, "estado_anterior": "EN_PROCESO", "estado_nuevo": "APROBADO" },
        { "lead_id": 125, "success": true, "estado_anterior": "EN_ESPERA", "estado_nuevo": "APROBADO" }
    ]
}

Response — Mixed Results 207 Multi-Status

Respuesta — Resultados Mixtos 207 Multi-Status

{
    "success": true,
    "message": "2 de 3 leads actualizados exitosamente",
    "updated": 2,
    "failed": 1,
    "total": 3,
    "estado_nuevo": "APROBADO",
    "results": [
        { "lead_id": 123, "success": true, "estado_anterior": "EN_ESPERA", "estado_nuevo": "APROBADO" },
        { "lead_id": 124, "success": false, "message": "No tienes permiso para este lead" },
        { "lead_id": 125, "success": true, "estado_anterior": "EN_ESPERA", "estado_nuevo": "APROBADO" }
    ]
}

Response — Limit Exceeded 400

Respuesta — Límite Excedido 400

{
    "success": false,
    "message": "Límite máximo de 100 leads por request",
    "received": 150
}

Response — All Failed 400

Respuesta — Todos Fallaron 400

{
    "success": false,
    "message": "0 de 3 leads actualizados exitosamente",
    "updated": 0,
    "failed": 3,
    "total": 3,
    "estado_nuevo": "APROBADO",
    "results": [
        { "lead_id": 999, "success": false, "message": "Lead no encontrado" },
        { "lead_id": 888, "success": false, "message": "No tienes permiso para este lead" },
        { "lead_id": 777, "success": false, "message": "Lead no encontrado" }
    ]
}

Bulk Status Update (Async) 🚀

Actualización Masiva de Estado (Asíncrona) 🚀

For processing large datasets (>100 leads). Accepts leads, creates a background job, and returns immediately.

Para procesar grandes conjuntos de datos (>100 leads). Acepta leads, crea un trabajo en segundo plano y retorna inmediatamente.

Endpoint

Endpoint

Allowed Roles

Roles Permitidos

Cliente (own leads only), Administrador

Cliente (solo sus propios leads), Administrador

Request Body

Cuerpo de la Petición

{
    "lead_ids": [1001, 1002, ..., 5000],
    "estado": "CANCELADO",
    "observaciones": "Limpieza mensual automática"
}

Response — Job Created 202

Respuesta — Job Creado 202

{
    "success": true,
    "message": "Proceso de actualización masiva iniciado. Job ID: bulk_6958b3ea2e5ad_1767420906",
    "job_id": "bulk_6958b3ea2e5ad_1767420906",
    "status_url": "http://localhost/paqueteriacz/api/crm/jobs/bulk_6958b3ea2e5ad_1767420906"
}

Check Job Status

Consultar Estado de Job

Poll this endpoint to track the progress of an async bulk update.

Consulta este endpoint para rastrear el progreso de una actualización masiva asíncrona.

Endpoint

Endpoint

Response — In Progress 200

Respuesta — En Progreso 200

{
    "success": true,
    "job_id": "bulk_6958b3ea2e5ad_1767420906",
    "status": "processing",
    "total_leads": 5000,
    "processed_leads": 2350,
    "progress_percent": 47,
    "created_at": "2026-01-03 00:15:06"
}

Response — Completed 200

Respuesta — Completado 200

{
    "success": true,
    "job_id": "bulk_6958b3ea2e5ad_1767420906",
    "status": "completed",
    "total_leads": 191,
    "processed_leads": 191,
    "successful_leads": 3,
    "failed_leads": 188,
    "estado": "CANCELADO",
    "created_at": "2026-01-03 00:15:06",
    "started_at": "2026-01-03 00:15:06",
    "completed_at": "2026-01-03 00:15:08",
    "progress_percent": 100,
    "successful_details": [
        {"lead_id": 1, "estado_anterior": "EN_ESPERA", "estado_nuevo": "CANCELADO"},
        {"lead_id": 5, "estado_anterior": "EN_PROCESO", "estado_nuevo": "CANCELADO"},
        {"lead_id": 12, "estado_anterior": "APROBADO", "estado_nuevo": "CANCELADO"}
    ],
    "failed_details": [
        {"lead_id": 2, "error": "No encontrado"},
        {"lead_id": 3, "error": "Sin permiso"}
    ]
}

List Leads

Listar Leads

Retrieve leads with filtering and pagination. Automatic role-based scoping applies.

Recupera leads con filtrado y paginación. Se aplica alcance automático basado en roles.

Endpoint

Endpoint

Allowed Roles

Roles Permitidos

Cliente (own leads only), Administrador

Cliente (solo sus propios leads), Administrador

Query Parameters

Parámetros de Consulta

Example cURL

Ejemplo cURL

curl "http://localhost/paqueteriacz/api/crm/leads?page=1&limit=10&estado=APROBADO" \
  -H "Authorization: Bearer <TOKEN>"

View Lead Detail & Timeline

Ver Detalle de Lead y Cronología

Access full lead details or status change history.

Accede a los detalles completos del lead o historial de cambios de estado.

Endpoints

Endpoints

Allowed Roles

Roles Permitidos

Cliente (own lead only), Administrador

Cliente (solo su propio lead), Administrador

Example cURL

Ejemplo cURL

# View detail
curl "http://localhost/paqueteriacz/api/crm/leads/1" \
  -H "Authorization: Bearer <TOKEN>"

# View timeline
curl "http://localhost/paqueteriacz/api/crm/leads/1/timeline" \
  -H "Authorization: Bearer <TOKEN>"

# Ver detalle
curl "http://localhost/paqueteriacz/api/crm/leads/1" \
  -H "Authorization: Bearer <TOKEN>"

# Ver cronología
curl "http://localhost/paqueteriacz/api/crm/leads/1/timeline" \
  -H "Authorization: Bearer <TOKEN>"

Notifications

Notificaciones

Manage user notifications. Notifications are generated on key events like lead assignment or status changes.

Gestiona las notificaciones del usuario. Las notificaciones se generan en eventos clave como asignación de leads o cambios de estado.

Endpoints

Endpoints

Allowed Roles

Roles Permitidos

Proveedor, Cliente, Administrador

Response — List Notifications

Respuesta — Listar Notificaciones

{
    "success": true,
    "data": [
        {
            "id": 15,
            "tipo": "nuevo_lead",
            "mensaje": "Nuevo lead asignado: Juan Pérez",
            "leido": 0,
            "fecha_creacion": "2025-01-15 10:30:00",
            "data_adicional": {"lead_id": 123}
        }
    ],
    "unread_count": 1
}

System Metrics

Métricas del Sistema

Monitor CRM health and performance (admin-only).

Monitorea la salud y rendimiento del CRM (solo administrador).

Endpoint

Endpoint

Allowed Roles

Roles Permitidos

Administrador only

Solo Administrador

Example cURL

Ejemplo cURL

curl "http://localhost/paqueteriacz/api/crm/metrics" \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

Webhooks (HMAC Signed)

Webhooks (Firmados con HMAC)

Receive real-time notifications via cryptographically signed webhooks.

Recibe notificaciones en tiempo real vía webhooks firmados criptográficamente.

Events

Eventos

• SEND_TO_CLIENT — Lead forwarded to client
• SEND_TO_PROVIDER — Status updated by client

• SEND_TO_CLIENT — Lead reenviado al cliente
• SEND_TO_PROVIDER — Estado actualizado por el cliente

Signature Verification (PHP)

Verificación de Firma (PHP)

$payload = file_get_contents("php://input");
$signature = $_SERVER['HTTP_X_SIGNATURE'];
$secret = 'your_shared_secret';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    $data = json_decode($payload, true);
    // Process webhook / Procesar webhook
} else {
    http_response_code(401);
    exit;
}

Configuration

Configuración

INSERT INTO crm_integrations (user_id, kind, webhook_url, secret, is_active)
VALUES (5, 'cliente', 'https://app.com/webhook', 'secret_123', 1);

Worker CLI

Worker CLI

Background worker for async processing with 3-second polling interval.

Worker en segundo plano para procesamiento asíncrono con intervalo de sondeo de 3 segundos.

1. General Worker (Webhooks & Retries)

1. Worker General (Webhooks y Reintentos)

# One-time execution (cron)
php cli/crm_worker.php --once

# Daemon mode (systemd)
php cli/crm_worker.php --loop

# Ejecución única (cron)
php cli/crm_worker.php --once

# Modo daemon (systemd)
php cli/crm_worker.php --loop

2. Bulk Update Worker 🚀

2. Worker de Actualización Masiva 🚀

Processes asynchronous bulk update jobs from POST /bulk-status-async.

Procesa jobs de actualización masiva asíncrona de POST /bulk-status-async.

# Start worker (runs continuously)
php cli/crm_bulk_worker.php

3. Maintenance & Cleanup 🧹

3. Mantenimiento y Limpieza 🧹

Removes old jobs and monitors stuck processes. Run daily via Cron/Task Scheduler.

Elimina jobs antiguos y monitorea procesos atascados. Ejecutar diariamente vía Cron/Task Scheduler.

# Run cleanup
php cli/crm_jobs_cleanup.php

Systemd Service

Servicio Systemd

[Unit]
Description=CRM Relay Worker
After=mariadb.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/xampp/htdocs/paqueteriacz
ExecStart=/usr/bin/php cli/crm_worker.php --loop
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl enable crm-worker
sudo systemctl start crm-worker
sudo journalctl -u crm-worker -f

Troubleshooting

Solución de Problemas

• Duplicate lead detection — First: 202, Retry: 200 + "duplicated":true
• Invalid transition — Check state matrix (can't jump EN_ESPERA → EN_TRANSITO)
• Worker not running — Verify: ps aux | grep crm_worker
• Webhook failures — Check crm_outbox.last_error column
• Queue backup — Monitor: SELECT COUNT(*) FROM crm_inbox WHERE status='pending'

• Detección de duplicados — Primero: 202, Reintento: 200 + "duplicated":true
• Transición inválida — Verifica matriz de estados (no puede saltar EN_ESPERA → EN_TRANSITO)
• Worker no ejecutándose — Verifica: ps aux | grep crm_worker
• Fallos de webhook — Revisa columna crm_outbox.last_error
• Respaldo de cola — Monitorea: SELECT COUNT(*) FROM crm_inbox WHERE status='pending'

Monitoring Queries

Consultas de Monitoreo

-- Pending inbox count
SELECT COUNT(*) FROM crm_inbox WHERE status='pending';

-- Failed webhooks
SELECT id, event_type, attempts, last_error 
FROM crm_outbox 
WHERE status='failed' 
LIMIT 10;

-- Recent leads
SELECT id, proveedor_lead_id, estado_actual, created_at 
FROM crm_leads 
ORDER BY created_at DESC 
LIMIT 20;

-- Conteo de inbox pendientes
SELECT COUNT(*) FROM crm_inbox WHERE status='pending';

-- Webhooks fallidos
SELECT id, event_type, attempts, last_error 
FROM crm_outbox 
WHERE status='failed' 
LIMIT 10;

-- Leads recientes
SELECT id, proveedor_lead_id, estado_actual, created_at 
FROM crm_leads 
ORDER BY created_at DESC 
LIMIT 20;