ZavyCRM API Gateway

Como Começar

{
  "email": "seu@email.com",
  "password": "sua_senha"
}

curl -H "X-API-Key: sk_abc123..." \
     https://api.zavycrm.com/api/v1/leads

Autenticação

Dois modos de credencial: API Key (X-API-Key) para integrações servidor-a-servidor, e JWT do Supabase (Authorization: Bearer) para clientes de navegador (PWA). Cada chave tem permissions (read/write) e a conta vem sempre da credencial.

⏱️ A chave gerada vale 60 minutos. Depois disso a API responde 401 API_KEY_EXPIRED — gere outra com o mesmo login. Automações devem renovar sozinhas quando a chave vencer.

Como renovar a chave

Não existe refresh token: a automação guarda login e senha e gera uma chave nova quando precisar.

• Quando renovar: a resposta do login traz expires_in (3600 segundos) e expires_at. Renove ~1 min antes de vencer — ou reaja ao erro 401 API_KEY_EXPIRED.
• Onde guardar: na memória do próprio workflow (no n8n, static data), nunca em texto fixo no nó.

Exemplo (n8n, Code node) — garante a chave antes de usar:

const dados = $getWorkflowStaticData('global');
const agora = Date.now();

if (!dados.zavyKey || agora > dados.zavyExp - 60000) {
  const r = await this.helpers.httpRequest({
    method: 'POST',
    url: 'https://api.zavycrm.com/api/v1/auth/token',
    body: { email: 'SEU_EMAIL', password: 'SUA_SENHA', name: 'n8n' },
    json: true,
  });
  dados.zavyKey = r.data.api_key;
  dados.zavyExp = agora + r.data.expires_in * 1000;
}

return [{ json: { apiKey: dados.zavyKey } }];

💡 Chaves criadas antes de 25/09/2026 não têm prazo (continuam válidas). O prazo de 60 minutos vale para as chaves geradas a partir dessa data.

Gerar API Key

Listar Chaves

Listar todas as suas API Keys ativas

Revogar Chave

Revogar uma API Key

Leads

Listar Leads

Criar Lead

{
  "nome": "João Silva",
  "email": "joao@empresa.com",
  "telefone": "+5511999999999",
  "estagio": "Contato inicial",
  "valor": 5000,
  "origem": "website"
}

Atualizar Lead

Mover Lead

{
  "estagio": "qualificado"
}

Estatísticas

Retorna total de leads, por estágio e valor total

Deletar Lead

Contatos

Listar Contatos

Criar Contato

Upsert Contato

Criar ou atualizar - útil quando o contato pode já existir

Atualizar Contato

Deletar Contato

Campos Personalizados do Contato

Valores de campos personalizados do contato (as definições vêm de GET /api/v1/campos). O valor é validado pelo tipo do campo: texto · numero · boolean (true/false) · data (normalizada para AAAA-MM-DD).

Contas

Retorna somente a sua conta (a vinculada à API Key). Não há listagem de outras contas nem criação/exclusão de conta pela API.

Minha Conta

Atualizar Minha Conta

:id deve ser o conta_id da sua API Key. Só o campo email é editável.

Conversas (WhatsApp)

Listar Conversas

Mensagens

Atualizar Status

Atribuir

Enviar Mensagem (WhatsApp)

Envie mensagens de texto via WhatsApp informando o nome da instância (visível no painel). A API Key da instância é resolvida internamente e nunca é exposta.

{
  "instanceName": "MinhaConexao-ABCDEF",
  "telefone": "+5511999999999",
  "texto": "Olá! Como posso ajudar?"
}

MCP Server (Model Context Protocol)

Servidor MCP read-only que expõe a API REST como ferramentas para agentes de IA. Exige o header X-API-Key e retorna somente os dados da conta da chave.

Ferramentas Disponíveis

Configuração no Claude Code

{
  "mcpServers": {
    "zavycrm": {
      "url": "https://mcp.zavycrm.com/mcp",
      "headers": { "X-API-Key": "sk_sua_chave_aqui" }
    }
  }
}

Agentes IA

Listar Agentes

Buscar Agente

Ativar/Desativar

Catálogos

Listas auxiliares da conta (a conta vem sempre da credencial).

Usuários (atendentes)

Setores

Etiquetas

Etiquetas do contato

Conexões WhatsApp

Campos personalizados

Definições (nome, tipo) dos campos personalizados da conta. Os valores ficam no contato: /api/v1/contatos/:id/campos.

Kanban (quadros, etapas e cards)

Um card é o mesmo registro que a API expõe como lead. Os IDs são numéricos (string).

Quadros e etapas

Cards

Criar card — nome, etapa_id e contato_id são obrigatórios (quadro_id é opcional; o quadro é deduzido da etapa):

{ "nome": "João Silva", "etapa_id": "312", "contato_id": "1466" }

Mover card — apenas a etapa de destino:

{ "etapa_id": "313" }

⚠️ Os campos são snake_case (etapa_id, contato_id, quadro_id). Em camelCase a API devolve 400 VALIDATION_ERROR. Não existe DELETE /cards — para remover, use DELETE /api/v1/leads/:id.

Exemplos de Uso

cURL

# Gerar API Key
curl -X POST https://api.zavycrm.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@empresa.com", "password": "123456"}'

# Criar lead
curl -X POST https://api.zavycrm.com/api/v1/leads \
  -H "X-API-Key: sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Santos",
    "telefone": "+5511888888888"
  }'

# Listar leads
curl https://api.zavycrm.com/api/v1/leads?estagio=Contato%20inicial \
  -H "X-API-Key: sk_abc123..."

Python

import requests

# Gerar API Key
response = requests.post(
    "https://api.zavycrm.com/api/v1/auth/token",
    json={"email": "admin@empresa.com", "password": "123456"}
)
api_key = response.json()["data"]["api_key"]

# Usar a API
headers = {"X-API-Key": api_key}
leads = requests.get("https://api.zavycrm.com/api/v1/leads", headers=headers)
print(leads.json()["data"])

JavaScript

// Gerar API Key
const loginRes = await fetch("https://api.zavycrm.com/api/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "admin@empresa.com", password: "123456" })
});
const { api_key } = (await loginRes.json()).data;

// Usar a API
const leadsRes = await fetch("https://api.zavycrm.com/api/v1/leads", {
  headers: { "X-API-Key": api_key }
});
const leads = (await leadsRes.json()).data;

n8n

// Nó HTTP Request
{
  "method": "POST",
  "url": "https://api.zavycrm.com/api/v1/leads",
  "headers": {
    "X-API-Key": "sua_api_key",
    "Content-Type": "application/json"
  },
  "body": {
    "nome": "={{$json.nome}}",
    "telefone": "={{$json.telefone}}"
  }
}

Códigos de Erro

Limites

Headers de Resposta

Toda requisição retorna headers informativos:

x-ratelimit-limit: 7
x-ratelimit-remaining: 5
x-ratelimit-reset: 1

Quando Exceder

Se você fizer mais de 7 req/s, receberá:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisições excedido. Máximo: 7 req/s.",
    "details": {
      "retry_after": 1
    }
  }
}

Boas Práticas

// ❌ Ruim: polling a cada 100ms
setInterval(() => fetch('/api/v1/leads'), 100);

// ✅ Bom: polling a cada 5 segundos
setInterval(() => fetch('/api/v1/leads'), 5000);

🤖 Para Agentes de IA

Se você é um agente de IA lendo esta documentação, acomplete está disponível em formato otimizado:

URL completa: https://docs.zavycrm.com/llms.txt

Este arquivo contém todos os endpoints, exemplos e schema em texto puro, otimizado para processamento por LLMs.

✅ Status do Serviço