Do formulário do site ao funil de vendas
Como levar cada contato do formulário do seu site direto para um funil do CRM da Astrify Flows com a API aberta, sem duplicar leads.
Um caso comum: alguém preenche o formulário de contato do seu site e o vendedor só fica sabendo horas depois, por e-mail. Com a API aberta, o próprio servidor do site cria o lead no funil certo, na etapa certa, no instante do envio. Neste artigo vamos montar essa integração em Node.js.
O que você vai precisar
- Uma chave de API criada em Configurações → API aberta com os escopos
leads:writeefunis:read. Veja Autenticação e chaves de API. - Um servidor (ou função serverless) que recebe o formulário. A chamada à API nunca sai do navegador do visitante: quem tiver a chave consegue agir nos dados da sua empresa.
1. Descubra o funil e a etapa
Para criar um lead, nome, funil_id e etapa_id são obrigatórios. Os ids são da sua empresa e não mudam, então busque uma vez e guarde na configuração da integração.
# Funis da empresacurl https://api2.astrify.com.br/v1/funis \ -H "Authorization: Bearer $ASTRIFY_API_KEY"
# Etapas de um funilcurl https://api2.astrify.com.br/v1/funis/ID_DO_FUNIL/etapas \ -H "Authorization: Bearer $ASTRIFY_API_KEY"Anote o id do funil (por exemplo, “Vendas”) e o da primeira etapa (por exemplo, “Novo contato”) e guarde nas variáveis ASTRIFY_FUNIL_ID e ASTRIFY_ETAPA_ID.
2. Evite lead duplicado
A mesma pessoa pode enviar o formulário duas vezes. Antes de criar, procure pelo e-mail com a visão de lista, que devolve leads e total:
curl "https://api2.astrify.com.br/v1/leads?view=list&search=ana%40exemplo.com&limit=1" \ -H "Authorization: Bearer $ASTRIFY_API_KEY"Se total for maior que zero, o lead já existe: você pode registrar uma observação nele (POST /v1/leads/{lead_id}/observacao) em vez de criar outro. A plataforma também lista possíveis duplicados em GET /v1/leads/duplicatas.
3. Crie o lead
Com os ids em mãos, o corpo mínimo é nome, funil_id e etapa_id. Os demais campos são opcionais; os mais úteis para formulário são email, telefone, empresa, origem, campanha, tags e observacoes.
curl -X POST https://api2.astrify.com.br/v1/leads \ -H "Authorization: Bearer $ASTRIFY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "nome": "Ana Souza", "email": "ana@exemplo.com", "telefone": "5511900000000", "funil_id": "ID_DO_FUNIL", "etapa_id": "ID_DA_ETAPA", "origem": "Site", "tags": ["formulario-contato"], "observacoes": "Quero entender os planos para 5 atendentes." }'Tudo junto em Node.js
O exemplo abaixo usa só o fetch nativo (Node.js 18 ou mais novo). Ele procura o lead pelo e-mail, cria se não existir e repete a chamada em caso de 429 ou 5xx, como explicado em Limites de uso e erros.
const BASE = 'https://api2.astrify.com.br';
async function astrify(caminho, opcoes = {}, tentativas = 4) { for (let i = 0; ; i++) { const resp = await fetch(`${BASE}${caminho}`, { ...opcoes, headers: { Authorization: `Bearer ${process.env.ASTRIFY_API_KEY}`, 'Content-Type': 'application/json', ...opcoes.headers, }, signal: AbortSignal.timeout(20000), }); const repetir = resp.status === 429 || resp.status >= 500; if (!repetir || i >= tentativas - 1) return resp; const espera = resp.status === 429 ? Number(resp.headers.get('Retry-After') || 60) : 2 ** i; await new Promise((r) => setTimeout(r, espera * 1000)); }}
export async function leadDoFormulario({ nome, email, telefone, mensagem }) { // 1. Já existe? const busca = await astrify(`/v1/leads?view=list&limit=1&search=${encodeURIComponent(email)}`); if (!busca.ok) throw new Error(`Busca falhou: ${busca.status}`); const { total } = await busca.json(); if (total > 0) return { criado: false };
// 2. Cria no funil e etapa configurados const resp = await astrify('/v1/leads', { method: 'POST', body: JSON.stringify({ nome, email, telefone, funil_id: process.env.ASTRIFY_FUNIL_ID, etapa_id: process.env.ASTRIFY_ETAPA_ID, origem: 'Site', tags: ['formulario-contato'], observacoes: mensagem, }), }); if (!resp.ok) { const erro = await resp.json().catch(() => ({})); throw new Error(`Criação falhou: ${resp.status} ${JSON.stringify(erro.detail)}`); } return { criado: true, resposta: await resp.json() };}Chame leadDoFormulario() na rota do seu servidor que recebe o formulário, depois de validar os campos.
Muitos leads de uma vez
Se você precisa subir uma planilha ou sincronizar um sistema antigo, não faça uma chamada por lead: o limite é de 120 requisições por minuto por chave. Use POST /v1/leads/importar-lote, que recebe a lista em leads e aceita disparar_automacoes (padrão true) para decidir se as automações do funil rodam para os leads importados.
Erros mais comuns
| Status | Causa provável |
|---|---|
400 |
Faltou nome, funil_id ou etapa_id, ou o id é de outra empresa |
401 |
Chave ausente, inválida, expirada ou revogada |
403 |
A chave não tem o escopo leads:write (o detail diz qual escopo falta) ou o IP não está liberado |
422 |
Campo com formato inválido: o detail lista os campos |
429 |
Passou de 120 chamadas por minuto: espere o Retry-After |
Sem escrever código
Se o formulário fica numa ferramenta como n8n, Make ou Zapier, ou se você prefere montar a lógica na plataforma, use um Workflow com o gatilho Receber webhook e o modelo pronto Receber lead por webhook. A URL do webhook substitui a chave, então ela também precisa ficar no servidor ou na ferramenta de automação. Veja Webhooks de entrada e n8n, Make e Zapier.
Próximos passos
-
Confira na referência interativa todos os campos de
POST /v1/leads, incluindocampos_customizados,valor_estimadoeresponsavel_id.