Gerenciar Leads

Ciclo de vida de um lead

pending → in_progress → converted
                     ↘ lost

Status	Descrição
`pending`	Lead criado, ainda não atendido
`in_progress`	Em atendimento ativo pela IA ou por um consultor
`converted`	Negócio fechado / objetivo atingido
`lost`	Lead perdido ou desqualificado

Quando um lead envia a primeira mensagem via WhatsApp, ele é criado automaticamente com status pending. Você pode alterar o status via API para manter sincronismo com o seu sistema.

Criar lead

curl -X POST https://api.cordialy.ai/integrations/v1/leads \
  -H "X-API-Key: SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "5511999998888",
    "name": "Maria Souza",
    "status": "in_progress"
  }'

const lead = await fetch('https://api.cordialy.ai/integrations/v1/leads', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.CORDIALY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    customer_phone: '5511999998888',
    name: 'Maria Souza',
    status: 'in_progress',
  }),
}).then(r => r.json());

lead = requests.post(
    'https://api.cordialy.ai/integrations/v1/leads',
    headers={'X-API-Key': 'SUA_KEY'},
    json={'customer_phone': '5511999998888', 'name': 'Maria Souza', 'status': 'in_progress'}
).json()

Se já existir um lead com o mesmo telefone, a API retorna o existente sem criar duplicata. Ideal para integrações de sincronização que podem rodar múltiplas vezes.

Listar e filtrar leads

# Todos os leads pendentes
curl "https://api.cordialy.ai/integrations/v1/leads?status=pending" \
  -H "X-API-Key: SUA_KEY"

# Leads atualizados nas últimas 24h
curl "https://api.cordialy.ai/integrations/v1/leads?since=2026-06-19T00:00:00Z" \
  -H "X-API-Key: SUA_KEY"

# Paginação
curl "https://api.cordialy.ai/integrations/v1/leads?page=2&limit=100" \
  -H "X-API-Key: SUA_KEY"

A resposta inclui total, page e limit para controle de paginação:

{
  "data": [...],
  "total": 1240,
  "page": 2,
  "limit": 100
}

Atualizar status

Quando um lead converte no seu sistema externo (ERP, e-commerce), atualize na Cordialy para manter consistência:

curl -X PATCH https://api.cordialy.ai/integrations/v1/leads/LEAD_ID \
  -H "X-API-Key: SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "converted"}'

await fetch(`https://api.cordialy.ai/integrations/v1/leads/${leadId}`, {
  method: 'PATCH',
  headers: { 'X-API-Key': process.env.CORDIALY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'converted' }),
});

Padrões de integração

Sincronização com CRM (bidirecional)

Quando um contato é criado no CRM → POST /leads
Quando o status muda no CRM → PATCH /leads/:id
Configure um webhook na Cordialy para receber lead.status_changed e atualizar o CRM no sentido inverso

Use o campo since para sincronizações incrementais — processe apenas o que mudou desde a última execução.

Importação de leads de e-commerce

Ao finalizar uma compra, crie o lead e já envie uma mensagem de confirmação:

// Evento: pedido confirmado
const lead = await criarLead({ phone: order.phone, name: order.name });
await enviarMensagem(lead.id, `Pedido #${order.id} confirmado! Entrega em 3 dias.`);

Importação em lote

Para importar muitos leads de uma vez, envie as requisições em paralelo com controle de concorrência para respeitar o rate limit:

import pLimit from 'p-limit';
const limit = pLimit(10); // 10 requisições simultâneas

await Promise.all(
  leads.map(lead => limit(() => criarLead(lead)))
);

Início

Guias

Exemplos

Ciclo de vida de um lead

Criar lead

Listar e filtrar leads

Atualizar status

Padrões de integração

​Ciclo de vida de um lead

​Criar lead

​Listar e filtrar leads

​Atualizar status

​Padrões de integração

Ciclo de vida de um lead

Criar lead

Listar e filtrar leads

Atualizar status

Padrões de integração