Formulários e captura de leads

Este guia explica como criar um formulário de captura, incorporá-lo em um site e consultar os cadastros recebidos.

Antes de começar

Use a URL base https://mailleader.com.br/api/v1 e autentique as rotas privadas com x-api-key ou Authorization: Bearer <token>. Mantenha a chave no servidor; não a coloque no HTML ou JavaScript público do site.

As rotas públicas do formulário usam um token de incorporação próprio. Ele identifica o formulário, mas não substitui validação de origem, consentimento ou proteção contra abuso.

Criar um formulário

POST /leads cria um formulário. A lista é opcional; se informada, os contatos elegíveis podem ser incluídos nela conforme o consentimento e as regras de supressão da conta.

Tipos de campo aceitos: text, email, cpf, cnpj, cep, currency, phone, date, number, select, textarea e consent. Campos select podem receber options. Use step para distribuir campos entre etapas e showWhen para exibir um campo dependendo de uma resposta anterior.

Um campo condicional usa fieldKey e um comparador equals, not_equals ou filled:

{
  "key": "company_size",
  "label": "Tamanho da empresa",
  "type": "select",
  "required": false,
  "options": ["1–10", "11–50", "Mais de 50"],
  "showWhen": {"fieldKey":"company","operator":"filled"}
}

O formulário aceita de 1 a 40 campos e até 10 etapas. O redirecionamento após o cadastro deve usar HTTPS. Campos de CPF, CNPJ, CEP, data e moeda são validados e normalizados no servidor; isso valida o formato, não consulta cadastros externos.

Incorporar no site

Depois de criar o formulário, consulte GET /leads/{id}/embed. A resposta contém o token, a URL pública e o snippet do iframe. Exemplo:

O script de incorporação ajusta a altura do iframe conforme o conteúdo. Para uma página hospedada pelo MailLeader ou para testar, abra diretamente a URL retornada.

Consultar e receber cadastros

O formulário incorporado consulta sua configuração em GET /api/v1/public/leads/{token} e envia cadastros com POST /api/v1/public/leads/{token}. Exemplo simplificado de envio:

{
  "data": {
    "name": "Ana Silva",
    "email": "ana@example.com",
    "company": "Exemplo Ltda"
  },
  "attribution": {
    "sourceOrigin": "https://empresa.example",
    "referrerOrigin": "https://busca.example",
    "markers": {"utm_source":"newsletter","utm_campaign":"guia"}
  }
}

O token público identifica o formulário. O servidor valida campos, estado ativo, limites e origem da requisição. O formulário hospedado é público; não envie uma chave de API do MailLeader no navegador.

Rotas privadas úteis:

Rota	Uso
`GET /leads`	Listar formulários; aceita `page`, `size` e busca `q`.
`GET /leads/{id}`	Consultar detalhes e resumo do formulário.
`PATCH /leads/{id}`	Atualizar campos, aparência, integrações, segurança ou pausar/ativar.
`DELETE /leads/{id}`	Remover o formulário.
`GET /leads/{id}/submissions`	Consultar inscrições paginadas.
`GET /leads/{id}/submissions/export`	Exportar inscrições e filtros disponíveis.
`GET /leads/{id}/analytics`	Consultar totais e atribuição.
`GET /leads/{id}/deliveries`	Consultar notificações do formulário.
`POST /leads/{id}/deliveries/{deliveryId}/retry`	Reenviar uma entrega com falha.

As consultas de inscrições e analytics aceitam filtros como from, to, domain, utmSource e utmCampaign, conforme a rota. O período de analytics é limitado a 366 dias.

Integrações e notificações

Em integrations, notifyOwner envia a notificação ao e-mail do titular. webhookUrl configura um destino específico para este formulário. Esse webhook inclui os campos do lead e a atribuição habilitada; seu segredo é gerenciado pelo próprio formulário.

Também é possível assinar lead.created na área Desenvolvedor > Webhooks. Esse evento geral inclui leadId, campaignId, listId, consented e lead.data. Veja o formato, a assinatura e as tentativas em Webhooks. Ativar os dois destinos envia duas notificações separadas.

Atribuição de origem

Com attributionSettings.enabled, o formulário pode registrar a origem (sourceOrigin, referrerOrigin) e os marcadores permitidos. customMarkers lista nomes adicionais que o titular deseja capturar; adCookies controla a captura dos marcadores de cookies de publicidade disponíveis.

O MailLeader guarda origens, não URLs completas com caminho, consulta ou fragmento. Marcadores não habilitados são descartados. Os dados recebidos dependem de o site enviar os marcadores no cadastro.

Segurança de origem e CORS

security.enableCors e security.allowedCorsOrigins controlam quais origens de navegador podem chamar a API pública. Informe origens exatas, por exemplo https://www.empresa.com.br, sem caminho, curinga, query ou fragmento. CORS é uma regra aplicada pelo navegador; não autentica chamadas servidor a servidor nem impede bots de fazer requisições diretas.

O modelo também possui restrictEmbedding e allowedEmbedOrigins. Por enquanto, esses campos ainda não bloqueiam a exibição do formulário em outros sites. Não os trate como controle de acesso. O limite de CORS é aplicado às chamadas públicas feitas por navegadores.

Páginas relacionadas

Pixels e eventos de sites

Webhooks

Campanhas de e-mail

Formulários e captura de leads

Antes de começar#

Criar um formulário#

Incorporar no site#

Consultar e receber cadastros#

Integrações e notificações#

Atribuição de origem#

Segurança de origem e CORS#

Páginas relacionadas#