API Externa

La API REST de FusionCRM permite integrar el CRM con cualquier sistema externo: crear contactos desde formularios web, sincronizar deals con ERPs, enviar mensajes desde aplicaciones propias y más.

Introducción a la API

La API de FusionCRM sigue las convenciones REST estándar:

GET

Leer datos

POST

Crear registros

PUT/PATCH

Actualizar

DELETE

Eliminar

Todas las respuestas son en formato JSON con codificación UTF-8. Los timestamps están en ISO 8601 (UTC).

Autenticación

Todas las peticiones deben incluir tu API Key en el header de autorización:

Header

Authorization: Bearer YOUR_API_KEY

Ejemplo con curl:

curl -X GET https://api.fusioncol.com/v1/contacts \
  -H "Authorization: Bearer sk_live_xxxxxxxxxx" \
  -H "Content-Type: application/json"

Consejo

Genera tu API Key en Configuración → API → Generar nueva clave. Guárdala en un lugar seguro; solo se muestra una vez al crearla.

URL base y versiones

URL base:

https://api.fusioncol.com/v1

La versión actual de la API es v1. Cuando se lancen versiones nuevas, la versión anterior se mantiene activa por al menos 12 meses con avisos de deprecación.

Contactos API

GET/v1/contacts

Lista todos los contactos con paginación.

Params: page, limit, search, email

GET/v1/contacts/:id

Obtiene un contacto por ID.

Params: id (requerido)

POST/v1/contacts

Crea un nuevo contacto.

Params: Body: nombre, email, telefono, empresa, campos adicionales

PUT/v1/contacts/:id

Actualiza todos los campos de un contacto.

Params: id + body completo

PATCH/v1/contacts/:id

Actualiza campos específicos.

Params: id + campos a actualizar

DELETE/v1/contacts/:id

Elimina un contacto.

Params: id (requerido)

Ejemplo: Crear contacto

POST /v1/contacts
{
  "nombre": "Juan García",
  "email": "juan@empresa.com",
  "telefono": "3001234567",
  "empresa": "Empresa S.A.",
  "cargo": "Gerente Comercial",
  "ciudad": "Bogotá"
}

Deals API

GET/v1/deals

Lista deals con filtros opcionales.

GET/v1/deals/:id

Obtiene detalle de un deal.

POST/v1/deals

Crea un nuevo deal.

PATCH/v1/deals/:id

Actualiza un deal.

DELETE/v1/deals/:id

Elimina un deal.

Conversaciones API

GET/v1/conversations

Lista conversaciones activas.

GET/v1/conversations/:id/messages

Obtiene mensajes de una conversación.

POST/v1/conversations/:id/messages

Envía un mensaje (WhatsApp/email).

POST/v1/conversations/send-template

Envía un template de WhatsApp a un contacto.

Ejemplo: Enviar template WhatsApp

POST /v1/conversations/send-template
{
  "contacto_id": "abc123",
  "template_name": "recordatorio_cita",
  "language": "es",
  "parameters": ["Juan", "15 de enero", "2:00 PM"]
}

Webhooks

Los webhooks permiten que FusionCRM notifique a tu aplicación cuando ocurren eventos. En lugar de hacer polling, tu servidor recibe notificaciones en tiempo real.

Configurar un webhook

1. Ve a Configuración → API → Webhooks
2. Agrega la URL de tu endpoint
3. Selecciona los eventos a escuchar
4. FusionCRM enviará un POST a tu URL cuando ocurra el evento

Eventos disponibles

contact.created	Nuevo contacto creado
contact.updated	Contacto actualizado
deal.created	Nuevo deal creado
deal.stage_changed	Deal cambió de etapa
deal.closed_won	Deal cerrado ganado
deal.closed_lost	Deal cerrado perdido
conversation.message_received	Nuevo mensaje entrante
invoice.issued	Factura emitida

Nota

Verifica los webhooks comprobando la firma HMAC incluida en el header X-FusionCRM-Signature para validar que la petición proviene genuinamente de FusionCRM.

Manejo de errores

Código HTTP	Significado
200 OK	Solicitud exitosa
201 Created	Recurso creado exitosamente
400 Bad Request	Datos inválidos o faltantes
401 Unauthorized	API Key inválida o faltante
403 Forbidden	Sin permisos para esa acción
404 Not Found	Recurso no encontrado
422 Unprocessable Entity	Error de validación
429 Too Many Requests	Rate limit excedido
500 Internal Server Error	Error del servidor

Rate limits

Para garantizar la disponibilidad del servicio, la API tiene los siguientes límites:

Básico

100 req/min

Pro

500 req/min

Enterprise

Personalizado

El header de respuesta X-RateLimit-Remaining indica cuántas peticiones quedan en la ventana actual.

Configuración

Integraciones