Skip to main content

​
Ciclo de vida de um lead

pending → in_progress → converted
                     ↘ lost
StatusDescrição
pendingLead criado, ainda não atendido
in_progressEm atendimento ativo pela IA ou por um consultor
convertedNegócio fechado / objetivo atingido
lostLead 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"
  }'
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"}'

​
Padrões de integração

  1. Quando um contato é criado no CRM → POST /leads
  2. Quando o status muda no CRM → PATCH /leads/:id
  3. 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.
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.`);
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)))
);