Perfex CRM

Servidor MCP Oficial para Perfex CRM

Documentação

Perfex CRM REST API — Exemplos, Coleção Postman e Trechos de Código

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

Coleção Postman pronta para uso, trechos de código (cURL, PHP, Python, JavaScript) e um catálogo de recursos para o módulo REST API para Perfex CRM — a maneira mais rápida de conectar o Perfex CRM a agentes de IA e aplicativos de terceiros.

A Perfex CRM REST API permite ler e gravar clientes, leads, faturas, orçamentos, projetos, tarefas e muito mais por meio de uma interface HTTP/JSON limpa — perfeita para integração de CRM, automação e aplicativos personalizados. A v3.0 adiciona um servidor MCP para agentes de IA, webhooks de nível de produção, polling pronto para Zapier / Make / n8n, operações em lote e endpoints de listagem mais inteligentes. Este repositório é o companheiro prático do módulo REST API para Perfex CRM da Themesic Interactive: exemplos prontos para copiar e colar, uma coleção Postman importável e um catálogo completo de endpoints.

🧩 Obtenha o módulo: https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/
📖 Guia da API / documentação ao vivo: https://perfexcrm.themesic.com/apiguide/
🧾 Especificação OpenAPI 3.0: GET https://yourdomain.com/api/openapi (cópia de referência)

🚀 Novidades na v3.0

Recurso	Endpoint	O que faz
🤖 Servidor MCP	`POST /api/mcp`	Model Context Protocol (JSON-RPC 2.0) — expõe 148 ferramentas de CRM filtradas por permissão para Claude Desktop, ChatGPT, Cursor, n8n AI Agent e qualquer cliente MCP
🪝 Webhooks 2.0	`/api/webhooks`	124 eventos, gerenciamento REST, entrega assíncrona com novas tentativas, proteção SSRF, solicitações assinadas com HMAC
🔌 Automação (polling)	`/api/zapier/*`	Gatilhos de polling prontos para Zapier, Make.com, n8n e qualquer ferramenta baseada em polling
⚡ Lote	`POST /api/batch`	Até 50 operações em uma única solicitação (mesmos nomes de ferramentas do MCP)
📚 Base de Conhecimento	`/api/knowledge_base`	CRUD de artigos + grupos
🗒️ Notas	`/api/notes`	Notas polimórficas em 12 tipos de entidades
📄 Listagens mais inteligentes	qualquer endpoint de listagem	Opt-in `?page=&per_page=`, `?fields=`, `?sort=`, `?created_after=&created_before=`
🛡️ Gravações seguras	qualquer `POST`	`Idempotency-Key` replay, campos desconhecidos ignorados em `PUT`, cabeçalhos `X-RateLimit-*`
📐 Especificação OpenAPI 3.0	`GET /api/openapi`	Toda a superfície como um documento legível por máquina — 74 caminhos, 144 operações — importe para Postman, Insomnia ou Stoplight em segundos (cópia de referência em `openapi/`)

Tudo é opt-in e compatível com versões anteriores: solicitações sem os novos parâmetros retornam exatamente a mesma resposta de antes.

Conteúdo

Pasta	O que contém
`postman/`	Coleção Postman importável + ambiente (`{{base_url}}`, `{{authtoken}}`) — agora com MCP, Webhooks, Lote, Automação, Base de Conhecimento e Notas
`snippets/curl/`	Comandos `curl` prontos para copiar e colar para as chamadas mais comuns
`snippets/php/`	Exemplos em PHP (cURL)
`snippets/python/`	Exemplos em Python (`requests`)
`snippets/javascript/`	Exemplos em JavaScript / Node (`fetch`)
`docs/`	Autenticação, paginação e filtragem, webhooks, MCP, automação, tabelas personalizadas, erros e códigos de status

Cada linguagem de trecho tem exemplos para clientes, faturas, leads além dos recursos da v3 webhooks, mcp, lote, automação, base_de_conhecimento e notas, e um arquivo list_features mostrando paginação, seleção de campos e ordenação.

Início rápido

Toda solicitação à Perfex CRM REST API é autenticada com o cabeçalho Authtoken. Crie um token no seu admin do Perfex em API → API Management (após ativar o módulo REST API), e então chame a API em https://yourdomain.com/api/...:

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

Isso retorna a lista de clientes como JSON. Veja docs/authentication.md para autenticação por cabeçalho vs. parâmetro de consulta, e snippets/ para a mesma chamada em PHP, Python e JavaScript.

Usar a coleção Postman

Abra o Postman → Import → arraste postman/perfex-rest-api.postman_collection.json.
Importe o ambiente postman/perfex-rest-api.postman_environment.json.
Defina base_url para https://yourdomain.com/api e authtoken para o seu token.
Escolha qualquer solicitação e clique em Send.

Conectar um agente de IA (MCP)

Aponte qualquer cliente MCP (Claude Desktop, Cursor, ChatGPT, n8n AI Agent) para POST https://yourdomain.com/api/mcp e envie seu cabeçalho authtoken. O servidor anuncia ferramentas filtradas por permissão para o seu CRM. Veja docs/mcp.md e snippets/curl/mcp.sh.

Usar com Claude, ChatGPT e outros assistentes de IA

Conecte qualquer assistente com uma única URL, https://perfex-mcp.themesic.com/mcp. Configuração passo a passo para Claude, ChatGPT, Cursor e VS Code: docs/connect-ai-assistants.md.

Um plugin Claude (conector + habilidades) para claude.ai, Cowork e Claude Code está em claude-plugin/. Ele requer o módulo REST API com uma licença válida e o servidor MCP habilitado. Veja claude-plugin/README.md para configuração, permissões e a política de privacidade.

Catálogo de endpoints

Todos os endpoints CRUD seguem uma convenção RESTful: GET lista, GET /:id único, POST criar, PUT /:id atualizar, DELETE /:id excluir — sob o caminho base https://yourdomain.com/api.

Recursos principais do CRM

Recurso	Caminho base	Operações típicas
Clientes	`/api/customers`	listar, obter, criar, atualizar, excluir
Contatos	`/api/contacts`	listar, obter, criar, atualizar, excluir
Leads	`/api/leads`	listar, obter, criar, atualizar, excluir
Faturas	`/api/invoices`	listar, obter, criar, atualizar, excluir
Orçamentos	`/api/estimates`	listar, obter, criar, atualizar, excluir
Notas de Crédito	`/api/credit_notes`	listar, obter, criar, atualizar
Pagamentos	`/api/payments`	listar, obter, criar
Propostas	`/api/proposals`	listar, obter, criar, atualizar, excluir
Contratos	`/api/contracts`	listar, obter, criar, atualizar, excluir
Projetos	`/api/projects`	listar, obter, criar, atualizar, excluir
Tarefas	`/api/tasks`	listar, obter, criar, atualizar, excluir
Marcos	`/api/milestones`	listar, obter, criar, atualizar, excluir
Quadros de horas	`/api/timesheets`	listar, obter, criar, atualizar, excluir
Assinaturas	`/api/subscriptions`	listar, obter, criar, atualizar
Itens	`/api/items`	listar, obter, criar, atualizar, excluir
Despesas	`/api/expenses`	listar, obter, criar, atualizar, excluir
Equipe	`/api/staffs`	listar, obter, criar, atualizar, excluir
Calendário	`/api/calendar`	listar, obter, criar, atualizar, excluir
Campos Personalizados	`/api/custom_fields`	listar por tipo relacionado
Comuns (consultas)	`/api/common`	países, impostos, moedas, status …

Recursos extras e de plataforma v3

Recurso	Caminho base	Operações típicas
Servidor MCP	`/api/mcp`	`POST` JSON-RPC 2.0: `initialize`, `tools/list`, `tools/call`
Lote	`/api/batch`	`POST` até 50 operações em uma única solicitação
Webhooks	`/api/webhooks`	listar, obter, criar, atualizar, excluir, `POST /:id/toggle`, `GET /events`, `GET /:id/logs`
Automação (polling)	`/api/zapier`	`GET /resources`, `GET /poll/:resource`, `GET /test/:resource`
Base de Conhecimento	`/api/knowledge_base`	listar, obter, criar, atualizar, excluir; `/groups`
Notas	`/api/notes`	listar por `:rel_type/:rel_id`, obter, criar, atualizar, excluir

Os campos exatos de solicitação por recurso estão documentados no guia oficial da API. Os trechos aqui cobrem os fluxos mais comuns.

Endpoints de listagem mais inteligentes (v3)

Todo endpoint de listagem aceita parâmetros de consulta opcionais. Adicione-os e você obtém um envelope { data, meta }; omitindo-os, você obtém exatamente o array legado.

# 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	Exemplo	Efeito
`page`, `per_page`	`?page=2&per_page=20`	Paginação → `{ data, meta }`
`fields`	`?fields=id,company`	Retornar apenas estas colunas
`sort`	`?sort=-datecreated,company`	Ordenar (`-` = decrescente)
`created_after`, `created_before`	`?created_after=2026-01-01`	Filtro por intervalo de datas

per_page é o parâmetro que define o tamanho da página (1-100, padrão 25). limit é aceito como alias somente quando page também é enviado, então um ?limit=5 isolado não pagina — use ?page=1&per_page=5.

Veja docs/pagination-filtering.md e snippets/curl/list_features.sh.

Atualizando da 2.x

Não há mudanças que quebrem compatibilidade. Todo recurso de listagem da v3 é opt-in:

Envie nenhum dos parâmetros acima e você obtém o mesmo array simples que a 2.x retornava. O envelope { data, meta } aparece somente quando você envia page ou per_page.
Nenhum endpoint foi renomeado. Clientes sempre estiveram em /api/customers.
Campos desconhecidos em PUT são ignorados em vez de retornar um erro.
Solicitações POST aceitam um cabeçalho Idempotency-Key opcional; novas tentativas idênticas reproduzem a resposta armazenada em vez de criar duplicatas.

Duas coisas que valem a pena saber ao adotar a v3:

Tabelas personalizadas foram movidas para uma lista de permissões na 3.0.2 — veja docs/custom-tables.md.
Novas linhas de permissão (Webhooks, Notas, Base de Conhecimento) devem ser marcadas nos tokens existentes antes que esses endpoints respondam, e antes que suas ferramentas MCP apareçam em tools/list.

Integrações populares e casos de uso

A Perfex CRM REST API é comumente usada para conectar o Perfex CRM a agentes de IA e aplicativos de terceiros:

Assistentes de IA (MCP) — deixe Claude, ChatGPT ou Cursor lerem e atualizarem seu CRM através de /api/mcp.
Zapier / Make / n8n — automação sem código via gatilhos de polling prontos (/api/zapier/*).
Webhooks — envie eventos do Perfex (nova fatura, novo lead, 124 eventos) para Slack, Discord ou seu próprio backend, assinados com HMAC.
Google Sheets / Power Automate — sincronize clientes, faturas ou pagamentos para planilhas e dashboards.
Aplicativos e portais personalizados — crie um aplicativo móvel ou portal do cliente sobre seus dados do Perfex.
Contabilidade e e-commerce — sincronize faturas e itens com plataformas externas de cobrança ou lojas.

Tudo isso é alimentado pelo módulo REST API para Perfex CRM.

Autenticação (resumo)

Método	Como
Cabeçalho (recomendado)	`Authtoken: YOUR_API_TOKEN`
Parâmetro de consulta	`?authtoken=YOUR_API_TOKEN` (útil para testes rápidos / webhooks)

Os tokens são criados e escopados (permissões por recurso) em API → API Management. Detalhes completos em docs/authentication.md.

FAQ

O Perfex CRM tem uma REST API? Sim. O módulo REST API para Perfex CRM adiciona uma API RESTful HTTP/JSON completa para clientes, leads, faturas, orçamentos, projetos, tarefas e mais, além de um servidor MCP na v3, webhooks, lote e endpoints de automação.

Posso usar o Perfex CRM com agentes de IA / ChatGPT / Claude? Sim — a v3 inclui um servidor MCP em POST /api/mcp que expõe ferramentas de CRM filtradas por permissão para qualquer cliente Model Context Protocol. Veja docs/mcp.md. Como faço para autenticar na API do Perfex CRM? Envie seu token no cabeçalho HTTP Authtoken (ou como parâmetro de consulta ?authtoken=). Consulte docs/authentication.md.

Qual é a URL base da API do Perfex CRM? https://yourdomain.com/api — por exemplo, https://yourdomain.com/api/customers.

Posso conectar o Perfex CRM ao Zapier, Make ou n8n? Sim — a v3 tem gatilhos de polling prontos em /api/zapier/*, além de webhooks. Consulte Integrações populares e docs/automation.md.

Existe uma coleção Postman para o Perfex CRM? Sim — importe postman/perfex-rest-api.postman_collection.json e o ambiente incluído, defina seu base_url e authtoken, e comece a enviar requisições.

Como crio uma fatura via API do Perfex CRM? POST https://yourdomain.com/api/invoices com os campos da fatura e um array items[] — a v3 calcula automaticamente subtotal/total. Consulte snippets/curl/invoices.sh.

Sobre / Suporte

Este repositório é um companheiro de exemplos para o módulo comercial:

REST API para Perfex CRM — conecte seu Perfex CRM com aplicações de terceiros por Themesic Interactive.

🛒 Comprar / saber mais: https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/
📖 Documentação: https://perfexcrm.themesic.com/apiguide/
💬 Suporte: https://themesic.com/support

Contribuições com exemplos adicionais são bem-vindas — consulte CONTRIBUTING.md.

Licença

O código de exemplo neste repositório é distribuído sob a Licença MIT. "Perfex" é uma marca registrada de seu respectivo proprietário; o módulo REST API é um produto comercial da Themesic Interactive.