API REST

Todo lo que ves en la app se puede leer y escribir por API: contactos, empresas, negocios, conversaciones, WhatsApp, cotizaciones, facturas, formularios, proyectos y más. La referencia completa se genera desde el mismo código que corre en producción.

Qué incluye

Más de 40 módulos y 200 operaciones

Cada endpoint documentado con parámetros, cuerpo, respuestas y ejemplos validados. El conteo exacto está en la referencia de abajo.

Tokens por permiso

Cada token lleva solo los permisos que le des; nada de llaves maestras en tus integraciones.

Mismo motor que la app

Crear un negocio por API dispara las mismas automatizaciones y reglas que crearlo a mano.

¿Prefieres que una IA use el CRM en vez de programar contra él? Mira la página de MCP: los mismos módulos expuestos como herramientas para Claude, ChatGPT o Cursor.

Nota

La API y el MCP son parte del módulo API del plan. Si tu plan no lo incluye, cualquier llamada responde 403 con el código PLAN_MODULE_REQUIRED. Puedes activarlo desde Configuración → Plan.

Autenticación y tokens

La API se autentica con tokens de API, que crea el propietario de la organización en Configuración → Desarrollador → API:

1. Pulsa Crear nuevo token y ponle un nombre que diga para qué es (ej. integracion-n8n).
2. Elige la expiración: 30 días, 90 días, 1 año o sin expiración.
3. Marca los permisos. Hay presets (Solo lectura, Ventas, Acceso completo) o puedes marcarlos uno por uno.
4. Copia el token: solo se muestra una vez. Desde la misma pantalla puedes revocarlo cuando quieras.

Envíalo en cualquiera de los dos headers (basta uno):

Authorization: Bearer <token>

X-API-Key: <token>

Primer paso: verifica a qué organización apunta el token

curl "https://api.fusioncol.com/api/me" \
  -H "Authorization: Bearer <token>"

GET /me no exige ningún permiso y devuelve la organización, el usuario que emitió el token, sus permisos, su vencimiento (expiresAt) y el plan. Úsalo siempre que manejes tokens de varias organizaciones.

Ejemplo: listar contactos

curl "https://api.fusioncol.com/api/contacts?page=1&limit=50" \
  -H "Authorization: Bearer <token>"

Ejemplo: crear un contacto (si ya existe por email o celular, responde 200 con el existente)

curl -X POST "https://api.fusioncol.com/api/contacts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ana",
    "lastName": "Ejemplo",
    "email": "ana@example.com",
    "mobile": "+57 300 000 0000",
    "source": "website"
  }'

Importante

Un token es una credencial: no lo pongas en código del navegador ni en repositorios. Si se filtra, revócalo en la misma pantalla donde lo creaste y genera otro.

Permisos

Cada operación exige un permiso concreto; la referencia lo indica en x-required-permissions. Un token sin el permiso recibe 403 con el permiso que le falta.

Permiso	Da acceso a
contacts:read · contacts:write · contacts:delete	Contactos y listas de contactos
companies:read · companies:write · companies:delete	Empresas
deals:read · deals:write · deals:delete	Negocios
forms:read · forms:write	Formularios, sus respuestas y el envío server-to-server
conversations:read · conversations:write · conversations:delete	Conversaciones, mensajes, pipelines y etapas
whatsapp:send · whatsapp:read	Enviar mensajes y plantillas; listar plantillas
quotations:read · quotations:write · quotations:delete	Cotizaciones
products:read · products:write	Productos
invoices:read · invoices:write	Facturas (requiere el módulo de facturación)
shipments:read · shipments:write	Envíos: read lista, consulta y cotiza (no cobra); write genera guías (cobra saldo de Envia), rastrea y cancela. Requiere el módulo Envíos
projects:read · projects:write · tasks:read · tasks:write	Proyectos y tareas
fragments:read · fragments:write · fragments:delete	Respuestas rápidas
library:read · library:write	Biblioteca (solo metadatos; la subida vive en la app)
rag:read · rag:write · rag:delete	Base de conocimiento
agents:read · agents:write	Agentes IA y prueba de prompts (gasta créditos de OpenAI)
*	Acceso completo

URL base y convenciones

https://api.fusioncol.com/api

• JSON en UTF-8 de ida y vuelta; fechas en ISO 8601.
• Listados paginados con page y limit (máximo 1000); la respuesta trae pagination con total y pages.
• search es una coincidencia parcial literal, sin distinguir mayúsculas.
• Los identificadores son ObjectId de 24 caracteres hexadecimales; uno mal formado responde 400.
• Todo está acotado a la organización del token: un id de otra organización responde 404.
• Cambios aditivos: nunca se renombran ni se quitan campos de una respuesta publicada; lo que sobra se marca deprecated.

Módulos principales (la lista completa está en la referencia)

/catalogs	Catálogos DANE: municipios y departamentos (cityCode)	cualquier token
/contacts	Contactos	contacts:*
/companies	Empresas (B2B)	companies:*
/deals	Negocios	deals:*
/forms	Formularios web y sus envíos	forms:*
/conversations	Conversaciones, pipelines y etapas	conversations:*
/whatsapp	Envío de WhatsApp y plantillas	whatsapp:send / whatsapp:read
/quotations	Cotizaciones y su PDF	quotations:*
/products	Productos y variantes	products:*
/invoices	Facturación electrónica (DIAN)	invoices:*
/shipments	Envíos con Envia.com (módulo Envíos)	shipments:read / shipments:write
/projects	Proyectos	projects:*
/tasks	Tareas	tasks:*
/lists	Listas de contactos	contacts:*
/fragments	Respuestas rápidas	fragments:*
/library	Biblioteca de archivos	library:*
/rag	Base de conocimiento (RAG)	rag:*
/agents	Agentes IA	agents:*
/agent-context	Contexto de cliente para agentes	conversations:read / agents:write

Consejo

Dos guías aparte para módulos con reglas propias: Ciudades (catálogo DANE), que explica cityCode y el 422 CITY_UNRESOLVED de contactos y empresas, y Envíos, con la idempotencia de POST /shipments (generar una guía cobra saldo).

Referencia de endpoints

La referencia se genera en cada despliegue desde el spec OpenAPI 3.1 del backend, así que siempre coincide con lo que hay en producción. Puedes verla aquí, abrirla completa en api.fusioncol.com/api/docs o descargar el spec en openapi.json para importarlo en Postman, Insomnia o generar un cliente.

Cargando la referencia de la API…

Webhooks salientes

FusionCRM avisa a tu sistema de dos maneras. Los cuerpos exactos, con ejemplos, están en la sección Webhooks de la referencia de arriba.

Webhook de etapa — conversation.stage.entered

En Configuración → Conversaciones, cada columna del pipeline puede llevar una URL. Cuando una conversación entra a esa etapa (desde la app, la API, el MCP o una automatización) FusionCRM hace un POST con el contacto, la etapa anterior y la nueva, el pipeline y quién la movió. Headers X-Fusioncrm-Event y X-Fusioncrm-Organization; 10 segundos de espera, sin reintentos ni firma: protege la URL con un secreto en la ruta.

Petición HTTP desde una automatización

Los eventos de negocio (negocio cambió de etapa, cotización creada, factura emitida, formulario enviado, contacto o empresa nuevos, mensaje entrante, cotización vista, factura vencida, cita próxima) se envían con la acción Petición HTTP de una automatización. Tú defines URL, método, headers y cuerpo con variables como {{trigger.quotation_total}} o {{contact.email}}; la referencia documenta qué trae trigger en cada disparador. Cada evento lleva un eventId estable para que puedas deduplicar.

Consejo

Para recibir datos hacia FusionCRM no necesitas un webhook especial: usa la API (por ejemplo POST /contacts) o el envío server-to-server de un formulario web, que además deduplica y registra el origen del lead.

Errores y límites del plan

Los errores de autenticación y permisos vienen con message y code; los de validación de cada módulo con success: false y error.

HTTP	code	Cuándo
401	API_TOKEN_MISSING / API_TOKEN_INVALID / API_TOKEN_EXPIRED	Falta el token, es inválido, expiró o fue revocado.
401	API_TOKEN_NOT_ACCEPTED	Usó un token de API en /api/v1/, que es la API interna de la app web. Use /api/.
403	INSUFFICIENT_API_PERMISSIONS	El token no tiene el permiso de la operación (la respuesta lista requiredPermission).
403	ORGANIZATION_ID_MISMATCH	El header X-Organization-Id (o el query organizationId) no coincide con la organización del token. Es opcional: sin él se usa la del token.
403	PLAN_MODULE_REQUIRED	El plan de la organización no incluye el módulo API (o el de facturación, en /invoices).
403	PLAN_LIMIT_REACHED	Se alcanzó un límite del plan al crear (contactos, cotizaciones, facturas, listas, documentos RAG).
400	—	Datos inválidos: el cuerpo lleva success:false y error con el motivo.
400	INVALID_CITY_CODE	El cityCode enviado no existe en el catálogo DANE. Ver Ciudades.
422	CITY_UNRESOLVED	La ciudad (texto) es ambigua, está mal escrita o no existe; la respuesta trae candidates para reenviar con cityCode. Ver Ciudades.
404	—	El recurso no existe o pertenece a otra organización (nunca se distingue entre ambos).
409	—	Conflicto: por ejemplo un atajo de respuesta rápida repetido.
503	RAG_QUEUE_UNAVAILABLE	La cola de indexación no aceptó un documento; reintente.

Los límites que aplican son los del plan (contactos, cotizaciones, facturas, listas, documentos de conocimiento), los mismos que en la app. No hay un tope de peticiones por minuto para tokens de API; sé razonable con los listados y usa limit alto en vez de muchas páginas pequeñas.

Configuración

Ciudades: catálogo DANE