ZavyCRM API - Documentação

Como Começar

1

Gerar sua API Key

Use seu email e senha do ZavyCRM para autenticar:

POST /api/v1/auth/token

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

2

Use a API Key

Adicione o header X-API-Key em todas as requisições:

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

3

Acesse seus dados

Liste leads, contatos, conversas e muito mais!

Autenticação

Gerar API Key

POST /api/v1/auth/token

Campo	Tipo	Obrigatório	Descrição
`email`	string	Sim	Email do login ZavyCRM
`password`	string	Sim	Senha do ZavyCRM
`name`	string	Não	Nome amigável da chave

Importante: A API Key só será exibida uma vez. Guarde em local seguro!

Listar Chaves

GET /api/v1/auth/keys

Listar todas as suas API Keys ativas

Revogar Chave

POST /api/v1/auth/revoke

Revogar uma API Key

Leads

Listar Leads

GET /api/v1/leads

Parâmetro	Tipo	Descrição
`conta_id`	UUID	Filtrar por conta
`estagio`	string	Filtrar por estágio
`status`	string	Filtrar por status
`search`	string	Buscar por nome/email/empresa
`page`	number	Página (padrão: 1)
`limit`	number	Itens por página (padrão: 20, máx: 100)

Criar Lead

POST /api/v1/leads

{
  "conta_id": "uuid-conta",
  "nome": "João Silva",
  "email": "joao@empresa.com",
  "telefone": "+5511999999999",
  "estagio": "novo",
  "valor": 5000,
  "origem": "website"
}

Atualizar Lead

PATCH /api/v1/leads/:id

Mover Lead

PATCH /api/v1/leads/:id/mover

{
  "estagio": "qualificado"
}

Estatísticas

GET /api/v1/leads/estatisticas/:contaId

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

Deletar Lead

DELETE /api/v1/leads/:id

Contatos

Listar Contatos

GET /api/v1/contatos

Criar Contato

POST /api/v1/contatos

Upsert Contato

POST /api/v1/contatos/upsert

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

Atualizar Contato

PUT /api/v1/contatos/:id

Deletar Contato

DELETE /api/v1/contatos/:id

Contas

Listar Contas

GET /api/v1/contas

Criar Conta

POST /api/v1/contas

Atualizar Conta

PUT /api/v1/contas/:id

Deletar Conta

DELETE /api/v1/contas/:id

Conversas (WhatsApp)

Listar Conversas

GET /api/v1/conversas

Mensagens

GET /api/v1/conversas/:id/mensagens

Atualizar Status

PATCH /api/v1/conversas/:id/status

Atribuir

PATCH /api/v1/conversas/:id/atribuir

Agentes IA

Listar Agentes

GET /api/v1/agentes

Criar Agente

POST /api/v1/agentes

Ativar/Desativar

PATCH /api/v1/agentes/:id/toggle

Deletar Agente

DELETE /api/v1/agentes/:id

Webhooks

Receba notificações quando eventos acontecerem no CRM:

Evento	Endpoint
Lead criado	`POST /webhook/lead-criado`
Lead movido	`POST /webhook/lead-movido`
Conversa atribuída	`POST /webhook/conversa-atribuida`
Atendimento finalizado	`POST /webhook/atendimento-finalizado`

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 '{
    "conta_id": "uuid-conta",
    "nome": "Maria Santos",
    "telefone": "+5511888888888"
  }'

# Listar leads
curl https://api.zavycrm.com/api/v1/leads?estagio=novo \
  -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": {
    "conta_id": "={{$json.conta_id}}",
    "nome": "={{$json.nome}}",
    "telefone": "={{$json.telefone}}"
  }
}

Códigos de Erro

Código	HTTP	Significado
`MISSING_API_KEY`	401	Header X-API-Key não enviado
`INVALID_API_KEY`	403	API Key inválida ou revogada
`API_KEY_EXPIRED`	403	API Key expirada
`VALIDATION_ERROR`	400	Dados de entrada inválidos
`NOT_FOUND`	404	Recurso não encontrado
`RATE_LIMIT_EXCEEDED`	429	Limite de requisições atingido (7 req/s)

Limites

Rate Limit: 7 requisições por segundo (420/min) por API Key.

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);

// ✅ Melhor: usar webhooks
// Receba notificações quando algo mudar