API pública do X32 CRM

Começando

A API está disponível nos planos Padrão e Completo. Cada empresa tem seu próprio endereço:

https://SUA-EMPRESA.crm.x32.com.br/api/x32

Gere o token em Configurações → API pública dentro do CRM (até 3 tokens por empresa). Envie em todas as chamadas um destes cabeçalhos:

token: SEU_TOKEN
Authorization: Bearer SEU_TOKEN

O token pode ser leitura e escrita ou só leitura (apenas GET). Use o token só no servidor, nunca em JavaScript de página.

Limite: 60 chamadas por minuto por token. Acima disso, a resposta é 429 com o cabeçalho Retry-After (segundos para tentar de novo).

Envie e receba JSON (Content-Type: application/json). Datas no formato ISO 8601 (2026-11-01T10:00:00-03:00) ou 2026-11-01 10:00.

Exemplo

curl -X POST https://SUA-EMPRESA.crm.x32.com.br/api/x32/leads \
  -H "token: SEU_TOKEN" -H "Content-Type: application/json" \
  -d '{"nome":"Maria Silva","email":"maria@exemplo.com","celular":"62999990000","mensagem":"Quero uma proposta"}'

Respostas e erros

Toda resposta tem status (true ou false). Erros trazem mensagem; erros de validação trazem também errors por campo.

Listas

As listas são paginadas: ?pagina=1&por_pagina=50 (máximo 100). A resposta traz dados, pagina, por_pagina, total e paginas. Para sincronizar, use o filtro atualizado_desde.

Leads

Campos do POST /leads

Obrigatório: nome ou razao. Opcionais: email, telefone, celular, cargo, cpf, nascimento, sexo, razao, fantasia, cnpj, cnae, fundacao, endereco, bairro, cidade, uf, cep, titulo, mensagem, valor, origem (nome da origem), utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid, landing_page, referrer.

{"status": true, "lead_id": 120, "pessoa_id": 88, "organizacao_id": 31}

Contatos

Campos: nome, email ou emails (lista), telefone, celular ou telefones (lista), cargo, cpf, nascimento (AAAA-MM-DD), sexo (Masculino, Feminino, Outro, Prefere não informar; aceita também M/F), organizacao_id, responsavel_id.

Organizações

Campos: nome, cnpj, fantasia, cnae, site, fundacao (AAAA-MM-DD), endereco, bairro, cidade, uf, cep, responsavel_id.

Atividades

tipo: call (ligação), meeting (reunião), lunch (almoço) ou note (nota). Ligação, reunião e almoço precisam de titulo e inicio; nota precisa de descricao.

Produtos

Campos: nome, sku, ean, descricao, preco, quantidade, origem (ex.: woocommerce) e externo_id (código do produto no seu sistema).

Pedidos

O cliente vai em pessoa_id ou no objeto cliente (nome, email, telefone, celular, razao, cnpj, endereco, cidade, uf, cep), que é procurado ou criado como contato. Pedido novo e mudança de status ficam registrados no histórico do contato.

status: pendente, aguardando_pagamento, pago, processando, enviado, concluido, cancelado, reembolsado, falhou. Sem total, o CRM calcula: soma dos itens − desconto + frete.

{
  "origem": "woocommerce", "externo_id": "1532", "numero": "1532", "status": "pago",
  "data_pedido": "2026-11-01T10:00:00-03:00", "forma_pagamento": "Pix", "frete": 15.90,
  "cliente": {"nome": "Maria Silva", "email": "maria@exemplo.com", "celular": "62999990000"},
  "itens": [{"externo_id": "88", "sku": "CAM-P", "nome": "Camiseta P", "quantidade": 2, "preco": 49.90}]
}

Vendas (ERP)

Para integrar o ERP: cada venda vai num só envio, com o cliente, os itens e os produtos. O CRM procura ou cadastra o cliente e os produtos, grava a venda em Pedidos e, quando ela está paga ou concluída, cria um lead ganho com os produtos (entra no dashboard, em "produtos mais vendidos", e nos relatórios).

Corpo

* obrigatório.

Exemplo: pessoa jurídica

{
  "erp": "meu-erp",
  "venda": {
    "id": "V-10293", "numero": "10293", "data": "2026-11-01T10:00:00-03:00", "status": "concluido",
    "forma_pagamento": "Boleto 30 dias", "desconto": 10.00, "frete": 25.00,
    "vendedor_email": "vendedor@suaempresa.com.br"
  },
  "cliente": {
    "tipo": "juridica", "razao_social": "Mercado Bom Preço Ltda", "nome_fantasia": "Bom Preço",
    "cnpj": "12.345.678/0001-90", "fundacao": "2015-03-10", "email": "compras@bompreco.com.br",
    "endereco": {"logradouro": "Rua Duque de Caxias", "numero": "317", "bairro": "Jardim Salvador",
                 "cidade": "Trindade", "uf": "GO", "cep": "75380-000"},
    "contato": {"nome": "João Souza", "celular": "62999990000", "cargo": "Comprador"}
  },
  "itens": [
    {"quantidade": 10, "preco_unitario": 12.50,
     "produto": {"id": "P-88", "sku": "ARZ-5KG", "ean": "7891234567890", "nome": "Arroz 5 kg"}},
    {"quantidade": 4, "preco_unitario": 39.90,
     "produto": {"id": "P-91", "nome": "Óleo de soja cx 12"}}
  ]
}

Exemplo: pessoa física

{
  "erp": "meu-erp",
  "venda": {"id": "V-10294", "status": "pago", "total": 89.90},
  "cliente": {"tipo": "fisica", "nome": "Maria Silva", "cpf": "123.456.789-09", "nascimento": "1990-05-10",
              "sexo": "F", "email": "maria@exemplo.com", "celular": "62988887777"},
  "itens": [{"quantidade": 1, "preco_unitario": 89.90, "produto": {"id": "P-12", "nome": "Cafeteira"}}]
}

Resposta

{"status": true, "atualizado": false, "pedido_id": 57, "lead_id": 310, "pessoa_id": 88, "organizacao_id": 31,
 "produtos": [{"externo_id": "P-88", "produto_id": 14}, {"externo_id": "P-91", "produto_id": 15}],
 "pedido": { ... }}

Código 201 na primeira vez e 200 quando atualiza. A venda também dispara os webhooks pedido.criado / pedido.atualizado e fica registrada como nota no histórico do cliente.

Funis, origens e usuários

Para saber os ids usados nos filtros e nas alterações:

Consultas

Consultas só de leitura, com o mesmo token e limite. A resposta traz os dados em dados.

Webhooks

Cadastre em Configurações → API pública → Webhooks um endereço https:// do seu sistema. O CRM envia um POST em JSON a cada evento escolhido:

{
  "evento": "lead.etapa_alterada",
  "empresa": "sua-empresa",
  "ocorrido_em": "2026-11-01T10:00:00-03:00",
  "dados": { "id": 120, "titulo": "...", "situacao": "ganho", "etapa_anterior_id": 3, ... }
}

Confira a origem pelo cabeçalho X-X32-Assinatura: sha256= + HMAC-SHA256 do corpo recebido, com o segredo do webhook. Em PHP:

$corpo = file_get_contents('php://input');
$ok = hash_equals('sha256=' . hash_hmac('sha256', $corpo, $segredo), $_SERVER['HTTP_X_X32_ASSINATURA'] ?? '');

Responda com um código 2xx em até 10 segundos. Se falhar, o CRM tenta de novo em 1, 5, 30, 120 e 720 minutos. O cabeçalho X-X32-Envio identifica o envio, para você ignorar repetições.

MCP (assistentes de IA)

No plano Completo, o CRM também é um servidor MCP: conecte o Claude, o ChatGPT, o n8n ou outro assistente que aceite MCP e peça em português, por exemplo "quais leads entraram esta semana?" ou "agende uma ligação amanhã às 10h com a Maria".

https://SUA-EMPRESA.crm.x32.com.br/api/x32/mcp

Transporte HTTP (Streamable HTTP, JSON-RPC 2.0), com o mesmo token, a mesma permissão e o mesmo limite de 60 chamadas por minuto da API. Com token só leitura, o assistente só vê as ferramentas de consulta.

Claude.ai e ChatGPT

Adicione um conector personalizado com o endereço acima (no Claude: Configurações → Conectores → Adicionar conector personalizado; no ChatGPT: Configurações → Conectores, no modo desenvolvedor). O assistente abre a tela de login do seu CRM: entre com seu usuário e clique em Autorizar. O que ele gravar fica no seu nome, e a conexão pode ser revogada em Configurações → API pública. O login segue o OAuth 2.1 com PKCE e cadastro automático do assistente, como pede a especificação do MCP.

Claude Code

claude mcp add --transport http x32crm https://SUA-EMPRESA.crm.x32.com.br/api/x32/mcp --header "token: SEU_TOKEN"

Claude Desktop

No arquivo claude_desktop_config.json (precisa do Node.js instalado):

{
  "mcpServers": {
    "x32crm": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://SUA-EMPRESA.crm.x32.com.br/api/x32/mcp", "--header", "token:SEU_TOKEN"]
    }
  }
}

Ferramentas