Formulários, integrações e API

Ligue o formulário do seu site ou outra ferramenta e cada envio vira lead no funil, com a origem do anúncio. Tudo fica em Ajustes › Integrações. Só quem tem acesso aos ajustes da empresa abre essa tela.

Há três caminhos, do mais simples ao mais técnico:

Caminho	Para quem	Como
Formulário pronto	Bio do Instagram, Linktree, WhatsApp, anúncio, site em WordPress, Wix, Lovable	Link direto ou uma linha para colar
Endereço de envio	Elementor (Webhook), Webflow, um <form> próprio	O seu formulário manda os campos por POST
Chave de API	Zapier, Make, n8n, a sua agência	Servidor para servidor, com a chave

Se o que você quer é uma página inteira, com texto e fotos, veja Páginas.

Como criar um formulário

Em Ajustes › Integrações, toque em Novo formulário e preencha:

• Básico: Nome do formulário (só você vê, ex.: "Site", "Bio do Instagram"), Canal em que o lead entra, Entra como (Lead ou Qualificado) e, se quiser, o Responsável, que já fica como SDR (quem faz o primeiro contato) do lead novo.
• Perguntas: nome, WhatsApp e e-mail já vêm no formulário. Acrescente até 20 perguntas de Texto curto, Texto longo, Uma escolha ou Várias escolhas, cada uma podendo ser Obrigatória.
• Qualificação automática: escolha uma pergunta de escolha e marque as respostas que qualificam. Quem der uma delas já entra como qualificado.
• Depois do envio: Mostrar mensagem, Levar para uma página (endereço com https://) ou Abrir meu WhatsApp (com uma mensagem pronta, se quiser).
• Privacidade e segurança: veja abaixo.

Entra como decide o tipo da etapa, não a etapa: o lead entra na primeira etapa ativa daquele tipo no seu funil. O app mostra qual é ("Entra na etapa…"). Se nenhuma etapa ativa for desse tipo, o lead entra em Lead.

Depois de salvar, aparece Ligar no seu site, com o que você precisa copiar.

Como pôr o formulário no ar

Formulário pronto (com anti-robô)

Com a Verificação anti-robô ligada (vem ligada no formulário novo e é a recomendada), você tem:

• Formulário pronto para colar: uma linha para pôr num bloco de HTML do seu site (WordPress, Wix, Lovable, Elementor). O formulário aparece ali, já guardando a origem do anúncio da sua página.
• Link direto: uma página só com o formulário. É o link para a bio do Instagram, o Linktree, o WhatsApp ou o botão do anúncio.

Com o anti-robô ligado, o formulário só funciona por esses dois caminhos.

Endereço de envio (sem anti-robô)

Para mandar de outra ferramenta (Elementor por webhook, Webflow, Zapier), desligue a verificação anti-robô. Aí aparecem:

• Endereço de envio: mande os campos por POST para ele.
• Formulário HTML pronto: um formulário comum para colar no site, que funciona sem JavaScript.
• Ver receitas (Elementor, Zapier, Make): o passo a passo de cada ferramenta.

Typeform, Tally e RD Station precisam do Zapier ou do Make no meio.

Enviar teste, pausar e reativar

• Enviar teste cria um lead marcado Teste no funil, sem passar pelo seu site. Para conferir o site, envie por lá e veja em Recebidos.
• Pausar faz o formulário recusar os envios até você tocar em Reativar.

O formulário de uma Página aparece na lista também, mas só se edita pela Página.

Privacidade e segurança

• Exigir consentimento: o envio só entra com a caixa de consentimento marcada. O Texto de consentimento vem pronto com o nome da sua empresa e você pode trocar. O texto aceito fica guardado no lead.
• Sites permitidos (opcional): até 10 sites (ex.: meusite.com.br). Vazio aceita qualquer site. Isso impede alguém de copiar o seu formulário para outro site; envio que vem de servidor (Zapier, webhook) não é afetado.
• Verificação anti-robô: veja acima.

Chaves de API

Para Zapier, Make, n8n ou a sua agência. Em Ajustes › Integrações › Chaves de API, toque em Nova chave, dê um Nome da chave (onde ela vai ser usada) e escolha o Canal em que o lead entra. Para criar uma chave, a empresa precisa de um canal ativo.

Copie a chave na hora

Esta é a única vez que a chave aparece. Se perder, revogue e crie outra. Junto vêm o Endereço da API e o Cabeçalho de toda chamada, prontos para copiar. Testar agora confere se a chave funciona e diz em que canal os leads vão entrar.

• A lista mostra quando cada chave foi usada pela última vez.
• Revogar faz a chave parar na hora. Quem estiver usando precisa de uma chave nova.
• A empresa pode ter até 20 chaves ativas.
• Nunca ponha a chave numa página da internet: ela é para servidor. O formulário de site usa o endereço de envio, que não é segredo.

Para quem vai integrar

Documentação completa, com exemplos: appvibeboard.com/api.

Endereços

Chamada	Endereço
Enviar um formulário	POST https://api.appvibeboard.com/v1/forms/{chave-pública}
Criar ou atualizar lead	POST https://api.appvibeboard.com/v1/leads
Testar a chave	GET https://api.appvibeboard.com/v1/me
Canais ativos	GET https://api.appvibeboard.com/v1/channels
Etapas ativas	GET https://api.appvibeboard.com/v1/stages

O endereço do formulário (o Endereço de envio do app) aceita JSON ou formulário comum e não pede chave. As chamadas da API pedem Authorization: Bearer <sua chave> e não funcionam direto do navegador.

Campos aceitos

• Nome: nome ou name (obrigatório).
• Telefone: whatsapp, telefone, celular ou phone. E-mail: email ou e-mail. É preciso mandar pelo menos um dos dois. Telefone brasileiro com DDD (10 ou 11 dígitos) ganha o +55; de outro país, mande com +.
• Instagram: instagram.
• Perguntas do formulário: pelo id que o app mostra em cada pergunta ("Campo no envio: …").
• Origem do anúncio: utm_source, utm_medium, utm_campaign, utm_content, utm_term, fbclid, gclid, referrer e landing_url.
• Consentimento: consent (true) e, pela API, consent_text.
• Os nomes são tolerantes a maiúscula, acento e espaço ("WhatsApp (com DDD)" vale). Campo que não é nenhum desses entra como resposta, com o nome original.

Só na API (POST /v1/leads):

• channel_id: um canal de GET /v1/channels. Sem ele, vale o canal da chave.
• stage_id: lead ou mql (qualificado). Sem ele, lead.
• external_id: o id do lead no seu sistema. Mandar o mesmo de novo atualiza o mesmo lead, em qualquer data.
• Cabeçalho Idempotency-Key: repetir a mesma chamada em até 24 horas devolve a mesma resposta sem gravar de novo.

A API responde 201 para lead novo e 200 para lead que já existia, com lead_id e duplicate.

Erros e limites

Situação	Resposta
Faltou nome ou contato, ou campo inválido	400, com a lista em fields
Chave errada ou revogada	401
Formulário pausado	409
Site fora dos permitidos ou falhou o anti-robô	403
Assinatura da empresa inativa	403
Muitos envios	429, com Retry-After

• Por formulário: até 5 envios por minuto e 30 por dia vindos do mesmo lugar (mesmo IP).
• Por chave de API: até 120 chamadas por minuto.
• Por empresa: até 1000 envios aceitos por dia (leads novos e repetidos), somando formulários e API. O envio de teste não conta.
• Um envio pode ter até 16 KB.

Como o lead chega ao funil

1. O envio é conferido: limites, site permitido, formulário ativo, anti-robô, assinatura e campos obrigatórios.
2. Se a pessoa é nova, nasce um lead no canal do formulário (ou da chave), na etapa de entrada, com o responsável escolhido. As respostas ficam em Respostas do formulário e o Sobre do lead mostra Veio de: Formulário ou Veio de: Integração, com a campanha (utm_campaign), se houver.
3. Se a pessoa já é lead, não nasce outro: o envio entra na linha do tempo do lead existente, e só os contatos que estavam vazios são preenchidos. Conta como repetido o mesmo telefone ou e-mail de um lead criado nos últimos 30 dias, exceto lead perdido há mais de 7 dias, que volta como lead novo: é a pessoa voltando, e o funil precisa ver isso.

A pessoa que preencheu recebe a mesma resposta nos dois casos, de propósito: assim ninguém de fora descobre que um telefone já está na sua base.

Envio que parece robô

Envio com o campo escondido preenchido ou feito rápido demais recebe "ok", mas não cria lead. Ele aparece em Recebidos como "Parecia robô".

Recebidos

O quadro Recebidos mostra os últimos envios, guardados por 30 dias: Lead novo, Já era lead ou Recusado, com o motivo:

• Muitos envios do mesmo lugar em pouco tempo
• Site fora da lista de permitidos
• Faltou nome, contato ou uma resposta obrigatória
• Não passou na verificação anti-robô
• O formulário estava pausado
• A assinatura não estava ativa
• Limite de envios do dia atingido
• Parecia robô
• Chave de API revogada ainda em uso

Os envios recusados não guardam nome, telefone nem e-mail.