CRM con API: tu agente de IA y tus herramientas hacen el seguimiento desde los mismos registros de clientes

Customermates es un CRM con API: una API REST abierta en todos los planes, desde Starter a 12 € por usuario al mes, y en la edición autoalojada gratuita. Te autenticas con una clave de API en la cabecera x-api-key, el esquema completo es un documento OpenAPI 3.1 en /api/v1/openapi y, en los planes de pago y en el autoalojado, 16 eventos de webhook avisan a tus sistemas cuando algo cambia. No hay un plan de desarrollador aparte ni un complemento de pago para la API.

Customermates es un CRM de código abierto y nativo de IA, desarrollado en Alemania para pequeños equipos que trabajan de cara al cliente. La API importa a dos tipos de lectores: un desarrollador que quiere sincronizar el CRM con otro sistema y un equipo que quiere que un cliente de IA como Claude o ChatGPT actualice registros. El primero usa REST y webhooks. El segundo usa el endpoint MCP, que se apoya en los mismos permisos.

Por qué importa para el seguimiento. Una respuesta a un cliente se descuida cuando los datos que necesita están en otro sistema. Mediante MCP, tu propio cliente de IA, como Claude o ChatGPT, lee el registro de un cliente y, en Customermates Cloud desde Pro, las conversaciones con él, y puede guardar un borrador de respuesta para que lo revises y lo envíes. Mediante REST y webhooks, tus otras herramientas reciben los mismos registros y se enteran cuando uno cambia.

Qué cubre la API REST

La API REST funciona en todas las listas del CRM. Un espacio de trabajo nuevo empieza sin listas: creas las que necesitas (contactos, organizaciones, oportunidades o las tuyas) en Modelo de datos, mediante la API o MCP, o dejas que la configuración con IA las cree en la nube. Cada ruta de registros es un POST a una acción con nombre y un cuerpo JSON, así que el mismo código sirve para oportunidades, contactos o una lista que añadiste la semana pasada.

Un registro se direcciona con una referencia, { "typeId": "...", "recordId": "..." }, no con su URL. La URL base es la dirección desde la que abres Customermates, tanto en la nube como en tu propio servidor. Otras rutas cubren usuarios (/api/v1/users/me, /api/v1/users/search), webhooks y la bandeja de entrada: hilos, borradores, envío de correo y de mensajes de chat, actividades y calendarios de solo lectura.

Unos detalles te ahorran tiempo el primer día:

• Los campos tienen ID estables. /model/read devuelve el fieldId de cada campo, los ID de opción de un campo de selección única como la Etapa de la oportunidad y la revision del esquema. Los ID no cambian cuando alguien renombra una lista o un campo. Los valores son tipados, por ejemplo { "kind": "text", "value": "Acme" }.
• Las consultas usan un cuerpo JSON. /records/query acepta typeId, filters, sort, page y pageSize (hasta 500). Los filtros usan la sintaxis de filtros que comparten la app y MCP.
• Las escrituras están protegidas. Una mutación lleva expectedRevision (la revisión del esquema), una idempotencyKey y la propia mutation; las actualizaciones y eliminaciones llevan además el expectedVersion del registro. Enviar de nuevo la misma solicitud con la misma clave no la aplica dos veces.
• Los vínculos son una acción aparte. link y unlink reciben un relationId, una referencia de registro source y otra target. Una actualización nunca elimina vínculos que no mencionaste.
• Las escrituras masivas admiten hasta 100 registros. updateMany aplica un cambio a hasta 100 registros de forma atómica y deleteMany mueve hasta 100 a la Papelera, así que una limpieza de 2000 contactos se divide en 20 solicitudes.

Webhooks: deja que el CRM te llame

Un webhook envía un POST JSON a tu URL cuando ocurre un evento suscrito. Los administradores, y los miembros cuyo rol tiene Acceso de lectura Todos y Crear en API y webhooks, añaden uno en Ajustes → Webhooks: URL, eventos, la lista en Registros de con filtros opcionales, un secreto opcional, cabeceras personalizadas opcionales y una plantilla del cuerpo opcional. La referencia de webhooks enumera todos los eventos y cargas útiles.

• Eventos: 5 eventos de registro (record.created, record.updated, record.deleted cuando un registro pasa a la Papelera, record.restored y record.deletedPermanently) para cualquier lista que elijas, incluidas las tuyas, más 11 eventos de la bandeja de entrada y del calendario.
• Cambios incluidos: una carga útil record.updated lleva la referencia del registro y enumera cada campo que cambió con su valor before y after. Una escritura que no cambia nada no envía ningún evento.
• Firmas: con un secreto configurado, cada entrega se firma con HMAC-SHA256 sobre el cuerpo sin procesar.
• Reintentos: un tiempo de espera agotado, un error de red, un 5xx, 408, 425 o 429 se reintenta automáticamente, hasta 10 intentos en total. Las demás respuestas 4xx no se reintentan, porque una repetición fallaría igual. Cada entrega tiene un tiempo de espera de 5 segundos.
• Registro de entregas: Ajustes → Registro de webhooks muestra el código de estado y el mensaje de respuesta de cada entrega, con un botón para reenviarla.
• Plantillas del cuerpo: una plantilla sustituye al envelope estándar, así que una herramienta de chat o un endpoint de automatización que espera su propia forma de JSON puede recibir entregas sin intermediarios.

Las entregas no tienen un orden estricto. Dos actualizaciones del mismo contacto con pocos milisegundos de diferencia pueden llegar invertidas, así que deduplica por el id del evento, indexa tu manejador por typeId y recordId, y usa el timestamp de la carga útil y la versión del registro.

Cómo hacer tu primera llamada a la API

1. Crea una clave

   Abre Ajustes → Claves de API y conectores, pulsa Añadir, elige Clave de API estándar, ponle un nombre como ERP sync, production y copia la clave. Se muestra una sola vez. La guía de claves de API trata la caducidad y la rotación.

2. Lee el esquema

   Descarga /api/v1/openapi desde la dirección de tu espacio de trabajo e impórtalo en Postman, Insomnia o un generador de clientes. Después envía POST /api/v1/model/discover con {"search":"deal"} para obtener el typeId de tus oportunidades, y POST /api/v1/model/read con {"typeIds":["<deal-type-id>"]} para ver sus campos, las opciones de etapa y la revision del esquema.

3. Consulta

   Envía POST /api/v1/records/query con la cabecera x-api-key y un cuerpo como {"typeId":"<deal-type-id>","filters":[{"fieldId":"system:updatedAt","operator":"inLastDays","value":{"kind":"decimal","value":"7","currency":null}}],"page":1,"pageSize":25} para listar las oportunidades modificadas en la última semana.

4. Escribe

   Mueve una oportunidad a otra etapa con POST /api/v1/records/mutate y {"expectedRevision":<revision>,"idempotencyKey":"move-acme-to-demo","mutation":{"action":"update","ref":{"typeId":"<deal-type-id>","recordId":"<deal-id>"},"expectedVersion":<version>,"fields":[{"fieldId":"<stage-field-id>","value":{"kind":"select","value":"<option-id>"}}]}}. Si tu usuario puede hacerlo en la app, la clave puede hacerlo por la API.

5. Suscríbete

   Añade un webhook para Registro actualizado en la lista Oportunidades con un secreto, apúntalo a tu endpoint y comprueba la primera entrega en Registro de webhooks.

Una clave incorrecta, caducada o eliminada recibe HTTP 401. Una clave cuyo propietario se puso en Inactivo recibe 403.

Claves de API y permisos

Las claves pertenecen al usuario que las creó y actúan con el rol actual de ese usuario. No hay usuarios de API aparte ni ámbitos por clave, así que una clave no se puede limitar a solo lectura. Si una integración solo debe leer oportunidades, crea su clave con un miembro cuyo rol permita solo eso. En Customermates Cloud ese miembro es una plaza de pago como cualquier otra.

Crear claves exige Acceso de lectura Todos y Crear en la fila API y webhooks de un rol. Un rol personalizado nuevo empieza sin ello, así que de entrada solo los administradores crean claves. El mismo permiso abre también todos los webhooks del espacio de trabajo, algo que conviene saber antes de concederlo. Para detener todas las claves de alguien que se va, pon al miembro en Inactivo. Quitar a su rol Acceso de lectura Todos en API y webhooks también detiene sus claves.

MCP: la API para clientes de IA

El endpoint MCP en /api/v1/mcp da a un cliente de IA externo 59 herramientas sobre los mismos registros, la bandeja de entrada y los webhooks. Claude y ChatGPT se conectan mediante OAuth como conector personalizado; Claude Code, Codex, Cursor y Gemini usan una clave de API. El cliente, su modelo y su suscripción siguen siendo tuyos. La búsqueda semántica puede seguir contando para el uso de Mate en Customermates Cloud. La guía de MCP enumera todas las herramientas.

Mate, el asistente dentro de Customermates Cloud, es una función aparte. Funciona con créditos de IA alojada y no necesita clave de API. Las instalaciones autoalojadas tienen MCP pero no Mate.

Lo que la API no hace

• Sin PUT ni PATCH en registros. Todo cambio de un registro es un POST a /api/v1/records/mutate.
• Sin OR entre reglas de filtro. Las reglas de filtro se combinan con AND. Para un OR, ejecuta dos consultas o usa el operador in en un campo.
• Sin cuota de solicitudes publicada. Un espacio de trabajo muy cargado responde 429 con una cabecera Retry-After. Divide los trabajos masivos en lotes de 100.
• Sin endpoint de exportación a CSV ni exportación de toda la cuenta. La app importa archivos Excel, CSV y JSON y exporta XLSX y JSON, una lista cada vez. Cualquier cosa mayor pasa por tu propio script de API.
• Sin bandeja de entrada ni Mate en el autoalojado. Las rutas REST de registros, los webhooks y MCP funcionan allí; las rutas de mensajería necesitan Customermates Cloud en Pro o superior.

No se promete ningún periodo de retrocompatibilidad más allá de la ruta /api/v1, así que trata el documento OpenAPI actual como el contrato y haz las pruebas contra él.

Cómo miden otros CRM el acceso a la API

Customermates publica esta página. Las cifras de abajo proceden de la documentación de cada proveedor, comprobadas el 8 de octubre de 2026; cambian, así que sigue los enlaces antes de planificar a partir de ellas.

Elige HubSpot o Zoho CRM si quieres un plan gratuito alojado con acceso a la API y tu integración cabe dentro de sus límites de llamadas publicados. Elige Pipedrive si te conviene un presupuesto diario que crece con el plan y las plazas. Elige EspoCRM si quieres un CRM de código abierto autoalojado con usuarios de API separados y roles propios. Customermates encaja con un equipo pequeño que quiere la API de registros, los webhooks y un endpoint MCP para clientes de IA al precio del propio CRM, con un núcleo AGPL que puede alojar por su cuenta. No encaja si necesitas ámbitos por clave o, en Customermates Cloud, un usuario de API que no ocupe una plaza de pago.

Cuánto cuesta

El acceso a la API no tiene recargo. Un equipo de tres personas en Starter paga 36 € al mes y obtiene REST, webhooks y MCP. El mismo equipo en Pro paga 87 € y añade la bandeja de entrada unificada y sus rutas de mensajería. Autoalojar la edición de código abierto no cuesta nada en licencias; el servidor lo ejecutas tú. La facturación es mensual, consulta los precios. Si montas flujos en n8n, n8n es un producto aparte con sus propios planes; la guía de n8n muestra la configuración de la solicitud HTTP.