Adicione um formulário de leads a um QR Code ou link curto

Ao final deste guia você terá um QR Code dinâmico ou link curto que mostra o seu próprio formulário (nome, e-mail, o que você pedir) antes de mandar o visitante ao destino. Toda resposta fica salva em Respostas.

Isso é diferente de um "QR Code de e-mail", um código mailto: que abre o aplicativo de e-mail do visitante e não coleta nenhum dado. Também é diferente de um QR Code que aponta para um Google Forms, em que o visitante termina na página "resposta registrada" do Google. Para exibir um Google Forms, Typeform ou Tally antes do redirecionamento, veja Use um Google Forms ou Typeform antes do redirecionamento.

Disponibilidade

• Plano: Business ou superior (preços). Em planos inferiores o botão fica desabilitado e mostra o selo Business. No Pro, veja abaixo "Use a página do formulário direto no plano Pro" para uma configuração parecida.
• Onde: na seção Formulário de pré-redirecionamento do editor de QR Code, para QR Codes dinâmicos de qualquer tipo, e do construtor de links. QR Codes estáticos não podem usar.

Antes de começar

Você precisa de uma Página da CodeQR publicada e com formulário. Qualquer tipo de página com campos serve; Newsletter e Formulário de Contato são as escolhas comuns. Se já tem uma, pule para a próxima seção.

1. Abra Páginas, clique em Criar nova página e depois em Novo formulário.
2. Escolha o tipo, por exemplo Newsletter, informe o Nome da página e clique em Criar página.
3. Em Conteúdo do Formulário, defina o Título e a Descrição que o visitante lê e o Texto do botão. O texto padrão do botão é genérico, então escreva o que o visitante ganha, por exemplo Quero o e-book.
4. Em Campos do Formulário, mantenha os campos de que precisa e marque os obrigatórios. Menos campos convertem melhor, e um campo de telefone custa conversão mesmo quando é opcional.
5. Em Consentimento, mantenha o texto padrão ou escreva o seu e cole a URL da política de privacidade. Exigir caixa de consentimento vem ligado, então o visitante precisa marcar a caixa para o botão ficar ativo. Desligue para mostrar o texto e o link da política como aviso junto ao botão. Páginas Pesquisa/Questionário começam com ele desligado.
6. Ligue Receber novos leads por e-mail para receber um e-mail por resposta e Monitoramento de conversão se quiser cada lead em Eventos e nos seus webhooks (Pro ou superior; veja Para onde vão os leads).
7. Salve as alterações (Conteúdo do Formulário e Campos do Formulário têm cada um o seu Salvar) e ligue o botão ao lado do nome da página, no topo do editor, para publicá-la. Enquanto ela não estiver publicada, o visitante pula o formulário e vai direto ao destino, e nenhum lead é registrado.

Adicione o formulário a um QR Code

1. Abra QR Codes e clique em Criar QR Code. Para alterar um código existente, abra o menu ⋮, escolha Editar e vá para o passo 4.
2. Em Selecione o formato do QR Code, clique em Dinâmico e depois em Continuar. A janela abre com Estático selecionado, e códigos estáticos não conseguem mostrar formulário.
3. Em Selecione o tipo do QR, escolha o tipo, por exemplo URL, e preencha o destino: para onde o visitante vai depois do formulário, por exemplo https://example.com/ebook.
4. Ative Formulário de pré-redirecionamento.
5. Mantenha Usar formulário da plataforma selecionado e clique em Selecionar página.
6. Pesquise ou role até a sua página e clique em Selecionar (no celular, toque na página). A URL da página, por exemplo https://go.example.com/p/NRGvqiks5e, preenche o campo. O seletor lista todas as páginas do workspace e marca as não publicadas com Rascunho, então escolha uma página publicada que tenha formulário.
7. Deixe Preenchimento obrigatório? desmarcado se o visitante puder pular o formulário, ou marque para remover o botão de fechar. Veja Torne o formulário obrigatório ou deixe o visitante pular. Mesmo marcado, não conte com o formulário para proteger conteúdo privado, porque o destino carrega por trás dele.
8. Clique em Criar QR Code e baixe o código em Exportar. Ao editar um código existente, o botão é Salvar QR Code, e um código já impresso continua funcionando.

Adicione o formulário a um link curto

1. Abra Links e clique em Adicionar Link. Para alterar um link existente, abra o menu ⋮ e escolha Editar.
2. Informe a URL de destino.
3. Na lista de recursos opcionais, ative Formulário de pré-redirecionamento e siga os passos 5 a 7 da seção de QR Code.
4. Clique em Criar link (ou Salvar link).

Use a página do formulário direto no plano Pro

O Formulário de pré-redirecionamento exige o Business. No Pro ou superior, a própria página faz o redirecionamento: o QR Code abre o formulário e a página manda o visitante ao seu link depois do envio.

1. Na sua página, abra Após o Envio, escolha a aba Redirecionamento, cole o destino em URL de redirecionamento e salve.
2. Publique a página e copie a URL pública no card da página em Páginas, por exemplo https://go.example.com/p/NRGvqiks5e.
3. Use essa URL como destino de um QR Code dinâmico ou link curto e deixe o Formulário de pré-redirecionamento desligado.

Nessa configuração não há botão de fechar, então o visitante precisa enviar o formulário para chegar ao destino. O redirecionamento substitui a mensagem de agradecimento, e o visitante não a vê.

O mesmo pela API

POST https://api.codeqr.io/links com os quatro campos do formulário. pageUrl é a URL pública da página; copie do card da página em Páginas, porque o servidor não a deriva de pageId.

Requisição:

curl -X POST https://api.codeqr.io/links \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/whitepaper",
    "domain": "go.example.com",
    "key": "whitepaper",
    "preRedirection": true,
    "pageId": "cmsx4bmpm0001a0d0hwow7468",
    "pageUrl": "https://go.example.com/p/NRGvqiks5e",
    "isFormMandatory": true
  }'

Resposta (200 OK, resumida aos campos relevantes):

{
  "id": "cmsx55jec0003ui96u4owiiyb",
  "domain": "go.example.com",
  "key": "whitepaper",
  "url": "https://example.com/whitepaper",
  "preRedirection": true,
  "pageId": "cmsx4bmpm0001a0d0hwow7468",
  "pageUrl": "https://go.example.com/p/NRGvqiks5e",
  "isFormMandatory": true,
  "shortLink": "https://go.example.com/whitepaper",
  "qrCode": "https://api.codeqr.io/qr?url=https://go.example.com/whitepaper?qr=1"
}

Os mesmos campos funcionam em PUT /links/{linkId}, POST /qrcodes (com "static": false) e PUT /qrcodes/{qrcodeId}. Payloads completos, todos os erros de validação e as notas de automação estão em Configure formulários de pré-redirecionamento pela API. O servidor MCP não define esses campos hoje.

Como verificar

1. Abra o link curto numa janela anônima, ou escaneie o QR Code com um celular que não o abriu na última hora. O formulário aparece sobre uma prévia desfocada do destino.
2. Preencha, marque Li e concordo se a caixa estiver ligada e toque no botão. Você cai no destino.
3. Abra o link de novo na mesma janela. Você vai direto ao destino, porque o formulário é pulado por uma hora em cada navegador. Use outra janela anônima para ver o formulário de novo.
4. Em Páginas, abra sua página e depois Respostas. A linha está lá, e Exportar CSV baixa a resposta com uma coluna por campo.

Sem navegador, os cabeçalhos da resposta mostram a mesma coisa:

curl -sI -A "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X)" https://go.example.com/whitepaper | grep -iE "^HTTP|x-pathname|set-cookie"
# HTTP/2 200
# set-cookie: cq_id=…; Path=/whitepaper; Max-Age=3600
# x-pathname: /go.example.com/pre-redirection/whitepaper/link

curl -sI -b "skipForm=FORM_FILLED" https://go.example.com/whitepaper | grep -iE "^HTTP|location"
# HTTP/2 302
# location: https://example.com/whitepaper

O 200 é a página do formulário. Com o cookie skipForm, o link se comporta como qualquer outro link curto.

Solução de problemas

A API responde "You can only use pre-redirection on a Business plan and above"

O workspace está no plano Free, Starter ou Pro, e uma requisição tentou ligar o formulário. A API responde 403. No editor o botão fica desabilitado nesses planos, então essa mensagem só aparece pela API. Faça upgrade para Business ou envie preRedirection: false. No Pro, você pode usar a página do formulário direto, como explicado acima.

O link vai direto ao destino e o formulário não aparece

A página não está publicada. O visitante pula o formulário, mesmo com Preenchimento obrigatório? marcado, e nenhum lead é registrado. Abra a página e ligue o botão ao lado do nome dela.

O formulário apareceu uma vez e agora o link vai direto ao destino

A CodeQR grava um cookie skipForm por uma hora naquele link depois de um envio ou de um pulo. Abra uma janela anônima ou outro navegador, ou espere uma hora. Robôs e prévias de link também nunca veem o formulário.

A área atrás do formulário está em branco

Alguns sites não permitem ser exibidos dentro de outras páginas, e a prévia atrás do formulário fica vazia. O formulário funciona normalmente, e o visitante chega ao destino depois dele.

O botão continua cinza

Exigir caixa de consentimento está ligado e o visitante não marcou Li e concordo. Para remover a caixa, desligue essa opção na seção Consentimento da página.

A página que eu quero não está no seletor

O seletor lista só as páginas do workspace atual. Crie a página neste workspace ou selecione o workspace certo antes.

O botão Formulário de pré-redirecionamento está desabilitado

Passe o mouse sobre o botão para ver o motivo. Abaixo do Business, a seção mostra o selo Business e a dica diz "Você só pode ativar o formulário de pré-redirecionamento nos planos Business e superiores". O mesmo vale no construtor de links. Faça upgrade para Business ou, no Pro, use a página do formulário direto, como explicado acima.

Se a dica disser "O formulário de pré-redirecionamento só está disponível em QR Codes dinâmicos", o QR Code é Estático. Crie um QR Code Dinâmico; códigos estáticos codificam o destino diretamente e não conseguem mostrar formulário.

Artigos relacionados

• Capture leads com um formulário antes do redirecionamento
• Torne o formulário obrigatório ou deixe o visitante pular
• Para onde vão os leads: Respostas, Clientes, CSV e CRM
• O formulário não apareceu ou o lead não chegou