Developers
Criar chave de APIEntrar na plataforma

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.

Equipe Astrify FlowsTutorial · · 7 min de leitura

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:write e funis: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.

Terminal window
# Funis da empresa
curl https://api2.astrify.com.br/v1/funis \
-H "Authorization: Bearer $ASTRIFY_API_KEY"
# Etapas de um funil
curl 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:

Terminal window
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.

Terminal window
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.

lead-do-formulario.js
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

  1. Confira na referência interativa todos os campos de POST /v1/leads, incluindo campos_customizados, valor_estimado e responsavel_id.

  2. Leia o checklist para colocar a integração em produção.

Digite para pesquisar em toda a documentação.