Quick Reference

Referencia Rápida

The CRM Relay module enables providers to submit leads (individual or batch), which are processed asynchronously and forwarded to clients via signed webhooks. Clients can update lead status, triggering automatic notifications to providers.

El módulo CRM Relay permite a los proveedores enviar leads (individuales o en lote), que se procesan de forma asíncrona y se reenvían a los clientes mediante webhooks firmados. Los clientes pueden actualizar el estado del lead, activando notificaciones automáticas a los proveedores.

✨ Key Features

✨ Características Principales

• 202 Accepted — Immediate responses without blocking
• Strong Idempotency — Unique proveedor_lead_id prevents duplicates
• State Normalization — Auto-converts aliases ("Aprovado" → "APROBADO")
• HMAC SHA256 — Cryptographically signed webhooks
• Exponential Backoff — Automatic retries: 1m, 5m, 15m, 1h, 6h
• Role-Based Access — Stateless JWT authentication

• 202 Accepted — Respuestas inmediatas sin bloqueo
• Idempotencia Fuerte — proveedor_lead_id único previene duplicados
• Normalización de Estados — Convierte automáticamente aliases ("Aprovado" → "APROBADO")
• HMAC SHA256 — Webhooks firmados criptográficamente
• Backoff Exponencial — Reintentos automáticos: 1m, 5m, 15m, 1h, 6h
• Acceso por Roles — Autenticación JWT sin estado

Quickstart Guide

Guía de Inicio Rápido

Get started with the CRM Relay API in 5 simple steps:

Comienza con la API CRM Relay en 5 pasos simples:

1. Authenticate — Obtain JWT via POST /api/auth/login
2. Extract Token — Use response.data.token (nested inside data)
3. Set Header — Add Authorization: Bearer <token> to all requests
4. Submit Leads — Send to POST /api/crm/leads with required fields
5. Process Async — System responds 202 and queues for background processing

1. Autenticar — Obtén JWT via POST /api/auth/login
2. Extraer Token — Usa response.data.token (anidado dentro de data)
3. Configurar Header — Agrega Authorization: Bearer <token> a todas las peticiones
4. Enviar Leads — Envía a POST /api/crm/leads con campos requeridos
5. Procesamiento Async — El sistema responde 202 y encola para procesamiento en segundo plano

Example: Create Lead

Ejemplo: Crear Lead

curl -X POST "http://localhost/paqueteriacz/api/crm/leads" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"lead":{"proveedor_lead_id":"PR-001","nombre":"Juan Pérez","telefono":"+50512345678","fecha_hora":"2025-01-15 10:00:00"}}'

Response (202 Accepted)

Respuesta (202 Accepted)

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

Authentication

Autenticación

All CRM endpoints require JWT authentication. Use the token from POST /api/auth/login.

Todos los endpoints CRM requieren autenticación JWT. Usa el token de POST /api/auth/login.

Required Header

Encabezado Requerido

Roles & Permissions

Roles y Permisos

Role	Permissions
Proveedor	Create leads, view own leads
Cliente	Update lead status (ownership required), view assigned leads
Administrador	Full access + system metrics

Rol	Permisos
Proveedor	Crear leads, ver propios leads
Cliente	Actualizar estado de lead (requiere propiedad), ver leads asignados
Administrador	Acceso completo + métricas del sistema

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

Field	Type	Required	Description
proveedor_lead_id	string(120)	✅ Yes	Unique lead ID (per provider)
fecha_hora	datetime	✅ Yes	Lead timestamp (YYYY-MM-DD HH:MM:SS)
nombre	string(255)	No	Prospect name
telefono	string(30)	No	Phone number
producto	string(255)	No	Product of interest
precio	decimal(10,2)	No	Product price
cliente_id	integer	No	Client ID (auto-forward if has webhook)

Campo	Tipo	Requerido	Descripción
proveedor_lead_id	string(120)	✅ Sí	ID único de lead (por proveedor)
fecha_hora	datetime	✅ Sí	Fecha y hora del lead (YYYY-MM-DD HH:MM:SS)
nombre	string(255)	No	Nombre del prospecto
telefono	string(30)	No	Número de teléfono
producto	string(255)	No	Producto de interés
precio	decimal(10,2)	No	Precio del producto
cliente_id	integer	No	ID del cliente (auto-reenvío si tiene webhook)

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
}

Update Lead Status

Actualizar Estado de Lead

Update lead state with automatic normalization and transition validation.

Actualiza el estado del lead con normalización automática y validación de transiciones.

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

Canonical State	Accepted Aliases
EN_ESPERA	ESPERA, PENDING, WAITING
APROBADO	APROVADO, APPROVED
CONFIRMADO	CONFIRMAR, CONFIRMED
EN_TRANSITO	EN TRANSITO, TRANSITO, TRANSIT
EN_BODEGA	EN BODEGA, BODEGA, WAREHOUSE
CANCELADO	CANCELAR, CANCELLED, CANCELED

Estado Canónico	Alias Aceptados
EN_ESPERA	ESPERA, PENDING, WAITING
APROBADO	APROVADO, APPROVED
CONFIRMADO	CONFIRMAR, CONFIRMED
EN_TRANSITO	EN TRANSITO, TRANSITO, TRANSIT
EN_BODEGA	EN BODEGA, BODEGA, WAREHOUSE
CANCELADO	CANCELAR, CANCELLED, CANCELED

State Transition Matrix

Matriz de Transición de Estados

EN_ESPERA    ✓ APROBADO, CANCELADO
APROBADO     ✓ CONFIRMADO, CANCELADO
CONFIRMADO   ✓ EN_TRANSITO, CANCELADO
EN_TRANSITO  ✓ EN_BODEGA, CANCELADO
EN_BODEGA    ✓ CANCELADO
CANCELADO    ✗ (final state / estado final)

Response — Success 200

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

Response — Invalid Transition 400

{
    "success": false,
    "message": "Transición no permitida de EN_ESPERA a EN_TRANSITO"
}

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

Query Parameters

Parámetros de Consulta

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	50	Items per page (max 100)
estado	string	-	Filter by state
fecha_desde	date	-	From date (YYYY-MM-DD)
fecha_hasta	date	-	To date (YYYY-MM-DD)

Parámetro	Tipo	Por Defecto	Descripción
page	integer	1	Número de página
limit	integer	50	Items por página (máx 100)
estado	string	-	Filtrar por estado
fecha_desde	date	-	Desde fecha (YYYY-MM-DD)
fecha_hasta	date	-	Hasta fecha (YYYY-MM-DD)

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

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>"

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.

Commands

Comandos

# 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

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;

HTTP Status Codes

Códigos de Estado HTTP

Code	Meaning	When
200	OK	Successful query, update, or idempotent retry
202	Accepted	Lead queued for async processing
400	Bad Request	Validation error, invalid transition
401	Unauthorized	Missing/invalid JWT token
403	Forbidden	Insufficient permissions or ownership
404	Not Found	Lead ID doesn't exist

Código	Significado	Cuándo
200	OK	Consulta exitosa, actualización o reintento idempotente
202	Aceptado	Lead encolado para procesamiento asíncrono
400	Solicitud Incorrecta	Error de validación, transición inválida
401	No Autorizado	Token JWT faltante/inválido
403	Prohibido	Permisos insuficientes o falta de propiedad
404	No Encontrado	ID de lead no existe