Perfex CRM

Servidor MCP oficial para Perfex CRM

Documentación

Perfex CRM REST API — Ejemplos, Colección de Postman y Fragmentos de Código

🌐 English · 简体中文 · Español · Português (BR) · Italiano · Français · Deutsch · Türkçe · Tiếng Việt · ไทย · العربية

Colección de Postman lista para usar, fragmentos de código (cURL, PHP, Python, JavaScript) y un catálogo de recursos para el módulo REST API para Perfex CRM — la forma más rápida de conectar Perfex CRM con agentes de IA y aplicaciones de terceros.

La Perfex CRM REST API te permite leer y escribir clientes, prospectos, facturas, presupuestos, proyectos, tareas y más a través de una interfaz limpia de HTTP/JSON — perfecta para integración de CRM, automatización y aplicaciones personalizadas. v3.0 añade un servidor MCP para agentes de IA, webhooks de nivel de producción, sondeo listo para Zapier / Make / n8n, operaciones por lotes y endpoints de listado más inteligentes. Este repositorio es el compañero práctico del REST API para Perfex CRM módulo de Themesic Interactive: ejemplos de copiar y pegar, una colección de Postman importable y un catálogo completo de endpoints.

🧩 Obtén el módulo: https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/
📖 Guía de API / documentación en vivo: https://perfexcrm.themesic.com/apiguide/
🧾 Especificación OpenAPI 3.0: GET https://yourdomain.com/api/openapi (copia de referencia)

🚀 Novedades en v3.0

Característica	Endpoint	Qué hace
🤖 Servidor MCP	`POST /api/mcp`	Protocolo de Contexto de Modelo (JSON-RPC 2.0) — expone 148 herramientas de CRM filtradas por permisos a Claude Desktop, ChatGPT, Cursor, n8n AI Agent y cualquier cliente MCP
🪝 Webhooks 2.0	`/api/webhooks`	124 eventos, gestión REST, entrega asíncrona con reintentos, protección SSRF, solicitudes firmadas con HMAC
🔌 Automatización (sondeo)	`/api/zapier/*`	Disparadores de sondeo listos para Zapier, Make.com, n8n y cualquier herramienta basada en sondeo
⚡ Lote	`POST /api/batch`	Hasta 50 operaciones en una sola solicitud (mismos nombres de herramientas que MCP)
📚 Base de conocimientos	`/api/knowledge_base`	CRUD de artículos + grupos
🗒️ Notas	`/api/notes`	Notas polimórficas en 12 tipos de entidades
📄 Listados más inteligentes	cualquier endpoint de listado	Opt-in `?page=&per_page=`, `?fields=`, `?sort=`, `?created_after=&created_before=`
🛡️ Escrituras seguras	cualquier `POST`	`Idempotency-Key` de reproducción, campos desconocidos ignorados en `PUT`, encabezados `X-RateLimit-*`
📐 Especificación OpenAPI 3.0	`GET /api/openapi`	Toda la superficie como un documento legible por máquina - 74 rutas, 144 operaciones - importa a Postman, Insomnia o Stoplight en segundos (copia de referencia en `openapi/`)

Todo es opt-in y compatible con versiones anteriores: las solicitudes sin los nuevos parámetros devuelven exactamente la misma respuesta que antes.

Contenidos

Carpeta	Qué contiene
`postman/`	Colección de Postman importable + entorno (`{{base_url}}`, `{{authtoken}}`) — ahora con MCP, Webhooks, Lote, Automatización, Base de conocimientos y Notas
`snippets/curl/`	Comandos `curl` de copiar y pegar para las llamadas más comunes
`snippets/php/`	Ejemplos en PHP (cURL)
`snippets/python/`	Ejemplos en Python (`requests`)
`snippets/javascript/`	Ejemplos en JavaScript / Node (`fetch`)
`docs/`	Autenticación, paginación y filtrado, webhooks, MCP, automatización, tablas personalizadas, errores y códigos de estado

Cada lenguaje de fragmentos tiene ejemplos para clientes, facturas, prospectos más las características de v3 webhooks, mcp, lote, automatización, base_de_conocimientos y notas, y un archivo list_features que muestra paginación, selección de campos y ordenamiento.

Inicio rápido

Cada solicitud a la Perfex CRM REST API se autentica con el encabezado Authtoken. Crea un token en tu administración de Perfex en API → Gestión de API (después de activar el módulo REST API), luego llama a la API en https://yourdomain.com/api/...:

curl -H "authtoken: YOUR_API_TOKEN" https://yourdomain.com/api/customers

Eso devuelve la lista de clientes como JSON. Consulta docs/authentication.md para autenticación por encabezado vs. parámetro de consulta, y snippets/ para la misma llamada en PHP, Python y JavaScript.

Usar la colección de Postman

Abre Postman → Importar → suelta postman/perfex-rest-api.postman_collection.json.
Importa el entorno postman/perfex-rest-api.postman_environment.json.
Establece base_url a https://yourdomain.com/api y authtoken a tu token.
Elige cualquier solicitud y pulsa Enviar.

Conectar un agente de IA (MCP)

Apunta cualquier cliente MCP (Claude Desktop, Cursor, ChatGPT, n8n AI Agent) a POST https://yourdomain.com/api/mcp y envía tu encabezado authtoken. El servidor anuncia herramientas filtradas por permisos para tu CRM. Consulta docs/mcp.md y snippets/curl/mcp.sh.

Catálogo de endpoints

Todos los endpoints CRUD siguen una convención RESTful: GET lista, GET /:id individual, POST crear, PUT /:id actualizar, DELETE /:id eliminar — bajo la ruta base https://yourdomain.com/api.

Recursos CRM principales

Recurso	Ruta base	Operaciones típicas
Clientes	`/api/customers`	listar, obtener, crear, actualizar, eliminar
Contactos	`/api/contacts`	listar, obtener, crear, actualizar, eliminar
Prospectos	`/api/leads`	listar, obtener, crear, actualizar, eliminar
Facturas	`/api/invoices`	listar, obtener, crear, actualizar, eliminar
Presupuestos	`/api/estimates`	listar, obtener, crear, actualizar, eliminar
Notas de crédito	`/api/credit_notes`	listar, obtener, crear, actualizar
Pagos	`/api/payments`	listar, obtener, crear
Propuestas	`/api/proposals`	listar, obtener, crear, actualizar, eliminar
Contratos	`/api/contracts`	listar, obtener, crear, actualizar, eliminar
Proyectos	`/api/projects`	listar, obtener, crear, actualizar, eliminar
Tareas	`/api/tasks`	listar, obtener, crear, actualizar, eliminar
Hitos	`/api/milestones`	listar, obtener, crear, actualizar, eliminar
Hojas de tiempo	`/api/timesheets`	listar, obtener, crear, actualizar, eliminar
Suscripciones	`/api/subscriptions`	listar, obtener, crear, actualizar
Artículos	`/api/items`	listar, obtener, crear, actualizar, eliminar
Gastos	`/api/expenses`	listar, obtener, crear, actualizar, eliminar
Personal	`/api/staffs`	listar, obtener, crear, actualizar, eliminar
Calendario	`/api/calendar`	listar, obtener, crear, actualizar, eliminar
Campos personalizados	`/api/custom_fields`	listar por tipo relacionado
Comunes (búsquedas)	`/api/common`	países, impuestos, monedas, estados …

Recursos de plataforma y adicionales de v3

Recurso	Ruta base	Operaciones típicas
Servidor MCP	`/api/mcp`	`POST` JSON-RPC 2.0: `initialize`, `tools/list`, `tools/call`
Lote	`/api/batch`	`POST` hasta 50 operaciones en una sola solicitud
Webhooks	`/api/webhooks`	listar, obtener, crear, actualizar, eliminar, `POST /:id/toggle`, `GET /events`, `GET /:id/logs`
Automatización (sondeo)	`/api/zapier`	`GET /resources`, `GET /poll/:resource`, `GET /test/:resource`
Base de conocimientos	`/api/knowledge_base`	listar, obtener, crear, actualizar, eliminar; `/groups`
Notas	`/api/notes`	listar por `:rel_type/:rel_id`, obtener, crear, actualizar, eliminar

Los campos de solicitud exactos por recurso están documentados en la guía de API oficial. Los fragmentos aquí cubren los flujos más comunes.

Endpoints de listado más inteligentes (v3)

Cada endpoint de listado acepta parámetros de consulta opcionales. Añádelos y obtienes un envoltorio { data, meta }; omítelos y obtienes exactamente el array heredado.

# Page 2, 20 per page, only id + company, newest first, created this year
curl -H "authtoken: YOUR_API_TOKEN" \
  "https://yourdomain.com/api/customers?page=2&per_page=20&fields=id,company&sort=-datecreated&created_after=2026-01-01"

Parámetro	Ejemplo	Efecto
`page`, `per_page`	`?page=2&per_page=20`	Paginación → `{ data, meta }`
`fields`	`?fields=id,company`	Devuelve solo estas columnas
`sort`	`?sort=-datecreated,company`	Ordenar (`-` = descendente)
`created_after`, `created_before`	`?created_after=2026-01-01`	Filtro de rango de fechas

per_page es el parámetro que dimensiona una página (1-100, predeterminado 25). limit se acepta como alias solo cuando page también se envía, por lo que un ?limit=5 desnudo no pagina - usa ?page=1&per_page=5.

Consulta docs/pagination-filtering.md y snippets/curl/list_features.sh.

Actualización desde 2.x

No hay cambios que rompan la compatibilidad. Cada característica de listado de v3 es opt-in:

No envíes ninguno de los parámetros anteriores y obtienes el mismo array simple que devolvía 2.x. El envoltorio { data, meta } aparece solo cuando envías page o per_page.
Ningún endpoint fue renombrado. Los clientes siempre han estado en /api/customers.
Los campos desconocidos en PUT se ignoran en lugar de devolver un error.
Las solicitudes POST aceptan un encabezado Idempotency-Key opcional; los reintentos idénticos reproducen la respuesta almacenada en lugar de crear duplicados.

Dos cosas que vale la pena saber al adoptar v3:

Las tablas personalizadas se movieron detrás de una lista de permitidos en 3.0.2 - consulta docs/custom-tables.md.
Las nuevas filas de permisos (Webhooks, Notas, Base de conocimientos) deben marcarse en los tokens existentes antes de que esos endpoints respondan, y antes de que sus herramientas MCP aparezcan en tools/list.

Integraciones populares y casos de uso

La Perfex CRM REST API se usa comúnmente para conectar Perfex CRM con agentes de IA y aplicaciones de terceros:

Asistentes de IA (MCP) — permite que Claude, ChatGPT o Cursor lean y actualicen tu CRM a través de /api/mcp.
Zapier / Make / n8n — automatización sin código mediante disparadores de sondeo listos (/api/zapier/*).
Webhooks — envía eventos de Perfex (nueva factura, nuevo prospecto, 124 eventos) a Slack, Discord o tu propio backend, firmados con HMAC.
Google Sheets / Power Automate — sincroniza clientes, facturas o pagos a hojas de cálculo y paneles.
Aplicaciones y portales personalizados — construye una aplicación móvil o un portal de clientes sobre tus datos de Perfex.
Contabilidad y comercio electrónico — sincroniza facturas y artículos con plataformas externas de facturación o tiendas.

Todo esto está impulsado por el módulo REST API para Perfex CRM.

Autenticación (resumen)

Método	Cómo
Encabezado (recomendado)	`Authtoken: YOUR_API_TOKEN`
Parámetro de consulta	`?authtoken=YOUR_API_TOKEN` (útil para pruebas rápidas / webhooks)

Los tokens se crean y se les asignan permisos (por recurso) en API → Gestión de API. Detalles completos en docs/authentication.md.

Preguntas frecuentes

¿Perfex CRM tiene una REST API? Sí. El módulo REST API para Perfex CRM añade una API RESTful completa de HTTP/JSON para clientes, prospectos, facturas, presupuestos, proyectos, tareas y más, además de un servidor MCP de v3, webhooks, lote y endpoints de automatización.

¿Puedo usar Perfex CRM con agentes de IA / ChatGPT / Claude? Sí — v3 incluye un servidor MCP en POST /api/mcp que expone herramientas de CRM filtradas por permisos a cualquier cliente del Protocolo de Contexto de Modelo. Consulta docs/mcp.md.

¿Cómo me autentico con la API de Perfex CRM? Envía tu token en el encabezado HTTP Authtoken (o como parámetro de consulta ?authtoken=). Consulta docs/authentication.md.

¿Cuál es la URL base de la API de Perfex CRM? https://yourdomain.com/api — por ejemplo https://yourdomain.com/api/customers.

¿Puedo conectar Perfex CRM a Zapier, Make o n8n? Sí — v3 tiene disparadores de sondeo listos bajo /api/zapier/*, además de webhooks. Consulta Integraciones populares y docs/automation.md. ¿Existe una colección de Postman para Perfex CRM? Sí — importa postman/perfex-rest-api.postman_collection.json y el entorno incluido, configura tu base_url y authtoken, y comienza a enviar solicitudes.

¿Cómo creo una factura mediante la API de Perfex CRM? POST https://yourdomain.com/api/invoices con los campos de la factura y un array de items[] — la v3 calcula automáticamente subtotal/total. Consulta snippets/curl/invoices.sh.

Acerca de / Soporte

Este repositorio es un complemento de ejemplos para el módulo comercial:

API REST para Perfex CRM — conecta tu Perfex CRM con aplicaciones de terceros por Themesic Interactive.

🛒 Comprar / saber más: https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/
📖 Documentación: https://perfexcrm.themesic.com/apiguide/
💬 Soporte: https://themesic.com/support

Las contribuciones de ejemplos adicionales son bienvenidas — consulta CONTRIBUTING.md.

Licencia

El código de ejemplo en este repositorio se publica bajo la Licencia MIT. "Perfex" es una marca comercial de su respectivo propietario; el módulo de API REST es un producto comercial de Themesic Interactive.