Uso de Webhooks y la API REST

Visión general de la API

La API REST de CIFRA v1 te permite integrar tu CRM, ERP, sistema de cobranza u otras plataformas con CIFRA 360. Soporta operaciones CRUD completas sobre contactos, embudos, conversaciones y campañas.

Base URL de la API:

https://api.cifra.com.co/v1

Autenticación

La API usa autenticación por Bearer Token. Genera tu API Key en CIFRA 360 → Configuración → API → Generar nueva clave.

Authorization: Bearer tu_api_key_aqui
Content-Type: application/json

Endpoints principales

Los recursos más utilizados de la API:

• GET /contacts — Listar contactos con paginación y filtros
• POST /contacts — Crear un nuevo contacto
• PATCH /contacts/:id — Actualizar datos de un contacto
• POST /campaigns/send — Lanzar una campaña de mensajes
• GET /conversations/:id — Obtener historial de conversación
• POST /agents/:id/trigger — Activar un agente de IA sobre un contacto

curl -X POST https://api.cifra.com.co/v1/contacts \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez",
    "phone": "+573001234567",
    "email": "juan@empresa.com",
    "tags": ["cobranza", "mora-30"]
  }'

Configurar webhooks

Los webhooks te notifican en tiempo real cuando ocurren eventos en CIFRA. Ve a Configuración → Webhooks → Nuevo endpoint e ingresa la URL de tu servidor.

CIFRA enviará un HTTP POST con el payload del evento a tu URL cada vez que ocurra un evento registrado.

Eventos disponibles

• contact.created — Se creó un nuevo contacto
• contact.updated — Se actualizaron datos de un contacto
• message.received — El cliente envió un mensaje
• message.sent — CIFRA envió un mensaje
• agent.conversation_ended — Un agente de IA cerró una conversación
• payment.committed — El cliente se comprometió a pagar
• pipeline.stage_changed — Un contacto cambió de etapa en el embudo

Seguridad del webhook

CIFRA firma cada payload con HMAC-SHA256 usando tu Webhook Secret. Verifica la firma en tu servidor antes de procesar el evento:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

// En tu handler Express:
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-cifra-signature'];
  if (!verifyWebhook(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }
  // Procesar evento...
  res.status(200).send('OK');
});

Ejemplos de integración

Casos de uso frecuentes con la API de CIFRA:

1. Sincronizar cartera desde tu sistema de cobranza: Crea contactos y activa agentes automáticamente cuando un cliente entra en mora
2. Registrar pagos en tiempo real: Usa el webhook payment.committed para actualizar tu sistema contable
3. Dashboard personalizado: Consume la API para construir reportes en tu BI tool favorita

Límites de uso

• Rate limit: 1.000 requests por minuto por API Key
• Payload máximo: 10 MB por request
• Retención de logs: 90 días en el panel de CIFRA
• Webhooks: Máximo 10 endpoints por workspace