Tutorial: como receber leads de site externo na Viniun

Dá para receber leads de site externo na Viniun sem copiar nada à mão: o formulário do seu site em WordPress com Elementor, as conversões do RD Station, o Typeform, uma automação no Zapier ou no Make, um sistema próprio ou até a caixa de e-mail que recebe os avisos. Cada contato entra no funil, passa pelo rodízio e o corretor é avisado. Neste tutorial você cria a chave, copia o endereço de recebimento, liga cada ferramenta e confere onde o lead aparece. Leva de 10 a 20 minutos por ferramenta.

Quem pode fazer: quem tem permissão de editar o item API & Webhooks (em geral o dono ou o administrador). A parte do e-mail fica em Integrações. As telas são da conta de demonstração da Viniun, com dados fictícios.

A visão geral está no guia API, webhooks e integrações para imobiliária. Aqui é o passo a passo.

O que você precisa antes de começar

• O item API & Webhooks no menu Integrações.
• Acesso de edição ao formulário (Elementor, RD Station, Typeform) ou à automação (Zapier, Make).
• Um campo de telefone (ou de e-mail) no formulário. Sem nenhum dos dois, o lead não entra.
• O rodízio de leads configurado, para o contato já cair com um corretor.

Passo 1: crie uma chave com a permissão Criar leads

Em Integrações › API & Webhooks, na aba Chaves de API, clique em Nova chave. Dê um nome que diga de onde vêm os leads e marque só Criar leads. Deixe os domínios em branco: a chave vai ser usada pelo servidor da ferramenta, não pelo navegador. Uma chave por ferramenta ajuda a saber de onde veio cada lead e a revogar só uma, se precisar.

1. Nome — por exemplo "Formulário do site (Elementor)". O nome da chave fica guardado em cada lead que ela trouxer.
2. Criar leads — a única permissão necessária.
3. Domínios em branco — a chave só funciona por servidor, o mais seguro.
4. Criar — gera a chave. Ela aparece uma única vez, junto com o endereço pronto para colar nas ferramentas. Copie e guarde.

Passo 2: copie o endereço para receber leads de site externo

Abra a aba Receber leads. O endereço de recebimento é o mesmo para todas as ferramentas: a Viniun reconhece sozinha o formato do Elementor, do RD Station e do Typeform. A chave vai no cabeçalho Authorization: Bearer SUA_CHAVE ou, nas ferramentas que só deixam colar um endereço, no fim dele: ?chave=SUA_CHAVE.

1. Receber leads — a aba com o endereço e os exemplos.
2. Endereço de recebimento — para onde a ferramenta manda o contato, por POST, em JSON ou formulário.
3. Copiar — copia o endereço.
4. Campos reconhecidos — nome, telefone (ou phone, whatsapp, celular), e-mail, mensagem, código do imóvel e UTMs. Os outros campos também ficam guardados na ficha do lead.

O endereço com ?chave= leva a chave junto: trate-o como senha e não publique em lugar aberto.

Passo 3: ligue o Elementor, o RD Station ou o Typeform

As três ferramentas só pedem para colar um endereço. Use o endereço com ?chave=SUA_CHAVE no fim.

1. Elementor (WordPress) — no formulário, em Ações após o envio, adicione Webhook, cole o endereço e ligue "Dados avançados". Dê ao campo de telefone o ID telefone (ou whatsapp).
2. RD Station Marketing — em Conta › Integrações › Webhooks, crie um webhook com o gatilho Conversão e cole o endereço com &fonte=rdstation no fim. O mesmo telefone não duplica.
3. Typeform — em Connect › Webhooks, adicione um webhook com o endereço. Na pergunta do telefone, preencha a "ref" com telefone.

Os menus do Elementor, do RD Station e do Typeform podem mudar de nome com o tempo. Se não achar, procure por "webhook" nas configurações do formulário.

Passo 4: use Zapier ou Make para as outras ferramentas

Para formulários que não têm webhook (Google Forms, Facebook, planilhas), use uma automação. No Zapier, a ação Webhooks by Zapier › POST; no Make, o módulo HTTP › Make a request com POST e JSON. Coloque o endereço, o cabeçalho Authorization com Bearer SUA_CHAVE e ligue os campos nome, telefone, e-mail e mensagem. Para testar a conexão, peça GET …/entrada/ping: ele responde o nome da imobiliária e da chave.

1. Zapier e Make — o passo a passo das duas ferramentas.
2. Resposta — quantos leads entraram e o número de cada um. Em "erros" vem o motivo de algum que não entrou.
3. reaproveitado — o telefone já era um lead em andamento: o contato virou uma nova atividade nele, sem lead repetido.

Passo 5: mande do seu site ou sistema próprio

Se o seu site ou sistema tem programação própria, envie do servidor, com a chave secreta. O exemplo abaixo é o da tela. Se o seu sistema tem um número do lead, mande em id_externo: um reenvio com o mesmo número não duplica.

curl -X POST https://novo.viniun.com.br/api/v1/entrada/leads \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"nome": "Cliente Exemplo", "telefone": "(13) 99999-0000",
       "mensagem": "Quero visitar", "imovel_codigo": "AP0123",
       "utm_source": "google", "id_externo": "form-123"}'

1. Exemplo — o envio completo, com o código do imóvel e as UTMs.
2. id_externo — o número do lead no seu sistema, para não duplicar em reenvios.

Site novo, feito com a API do site da Viniun (inclusive por IA)? Aí o formulário vai para /site-api/leads com a chave pública, direto do navegador. Veja o Tutorial: API do site da Viniun.

Passo 6: receba os leads que chegam por e-mail

Se o formulário antigo só manda e-mail, ou se você quer ler os avisos dos portais, use a caixa de leads. Vá em Integrações, no cartão de e-mail, aba Receber leads por e-mail. Crie uma caixa só para leads, encaminhe os avisos para ela e preencha os dados de acesso (IMAP). A Viniun lê a caixa a cada 5 minutos.

1. Ligada — marque só depois de testar e conferir o histórico.
2. Como fazer — os quatro passos: caixa só para leads, encaminhamento, IMAP com Testar conexão e Ler agora, e conferência.
3. Origem — aviso de portal entra como Portal de anúncios; formulário do site e outros e-mails entram como E-mail. E-mail com anexo acima de 3 MB é ignorado.
4. Servidor IMAP — os dados da caixa. Gmail e Outlook pedem uma "senha de app".

Passo 7: confira onde o lead aparece

Faça um envio de teste com um nome fictício e abra CRM › Leads. O lead que veio pelo endereço de recebimento aparece com a origem API; o da API do site, como Site (ou a origem do formulário). O corretor do rodízio é avisado e o contato também está no funil de vendas. Na ficha ficam a ferramenta, o nome da chave, o formulário e as respostas extras.

1. Todas as origens — filtre por origem para ver só os leads que vieram de fora.
2. Origem — de onde o lead veio.
3. Responsável — o corretor que o rodízio escolheu.
4. Status — a etapa do lead no funil.

Quais são as dicas e os erros mais comuns?

• "Sem telefone nem e-mail": o campo de telefone não foi reconhecido. Renomeie para telefone, phone, whatsapp ou celular.
• Telefone da equipe não vira lead: teste com um número que não seja de ninguém da imobiliária.
• Erro 401 ou 403: 401 é chave errada ou revogada; 403 é chave sem a permissão "Criar leads".
• Limite: 120 envios por minuto por chave. Para importar uma lista antiga, use a importação por planilha.
• Quer avisar outro sistema quando o lead entra? Isso é o caminho contrário: use um webhook lead.criado.

Próximos passos

• Tutorial: webhooks da Viniun
• Tutorial: API do site da Viniun
• Tutorial: configurar o rodízio de leads
• Tutorial: formulários públicos e comunicados
• Guias: API, webhooks e integrações e importar imóveis e leads por planilha