Configure formulários de pré-redirecionamento pela API

Depois de ler esta página você cria ou altera um link ou QR Code dinâmico com Formulário de pré-redirecionamento a partir do seu código, de uma importação ou de uma plataforma de automação, e sabe o erro exato que cada engano produz. Toda requisição e resposta abaixo foi executada contra a API de produção em 2026-08-17 (domínio trocado por go.example.com).

Disponibilidade

Plano: Business ou superior. Ligar preRedirection a partir de um plano inferior devolve 403 forbidden — You can only use pre-redirection on a Business plan and above. Upgrade to Business to use this feature.
Endpoints: POST /links, PUT /links/{linkId}, POST /links/bulk, POST /qrcodes, PUT /qrcodes/{qrcodeId}, POST /qrcodes/bulk. Os quatro campos voltam em toda resposta de link e QR Code (GET, listagem, webhooks).
Autenticação: token Bearer criado em Configurações → Chaves de API. URL base https://api.codeqr.io.
Não disponível: o servidor MCP (create_link, update_link, create_qrcode, update_qrcode não expõem nenhum desses campos) e os módulos do Zapier, do Make e da Pluga (sem campo de formulário). Páginas e respostas de formulário não fazem parte da API pública.

Os quatro campos

botão Formulário de pré-redirecionamento** — Campo: preRedirection · Tipo: boolean, padrão false · Significado: mostrar um formulário antes do redirecionamento
Usar formulário da plataforma → Selecionar página — Campo: pageId · Tipo: string ou null · Significado: id da Página da CodeQR com o formulário
URL da página (preenchida pelo seletor) ou campo de Usar formulário externo** — Campo: pageUrl · Tipo: string ou null · Significado: URL pública do formulário: https://<domínio da página>/<chave da página> para uma Página da CodeQR, ou a URL do formulário externo
Preenchimento obrigatório? — Campo: isFormMandatory · Tipo: boolean, padrão false · Significado: remove o botão de fechar; exige pageId

Regras que o servidor aplica:

preRedirection: true exige um pageUrl válido. O servidor nunca o deriva de pageId — envie os dois para uma Página da CodeQR. Copie a URL do card da página em Páginas (tem a forma https://go.example.com/p/NRGvqiks5e).
isFormMandatory: true exige pageId (uma Página da CodeQR). Formulários externos nunca são obrigatórios.
pageId precisa existir; pageUrl precisa ser uma URL válida.
Desligar preRedirection mantém pageId, pageUrl e isFormMandatory gravados; religar não exige outro campo.
QR Codes estáticos: a API aceita e grava os campos, mas um QR Code estático codifica o destino diretamente e nunca mostra o formulário. Use "static": false.

Criar um link com formulário de Página da CodeQR (obrigatório)

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):

{
  "id": "cmsx55jec0003ui96u4owiiyb",
  "domain": "go.example.com",
  "key": "whitepaper",
  "url": "https://example.com/whitepaper",
  "archived": false,
  "expiresAt": null,
  "expiredUrl": null,
  "password": null,
  "externalId": null,
  "trackConversion": false,
  "proxy": false,
  "title": null,
  "description": null,
  "image": null,
  "video": null,
  "utm_source": null,
  "utm_medium": null,
  "utm_campaign": null,
  "utm_term": null,
  "utm_content": null,
  "rewrite": false,
  "doIndex": false,
  "banned": false,
  "flexible": false,
  "filled": false,
  "ios": null,
  "android": null,
  "geo": null,
  "rules": null,
  "userId": "cm73yc6m70002mtesulffnrgb",
  "folderId": null,
  "projectId": "cm73y7wm100008j24i1b137wr",
  "preRedirection": true,
  "pageId": "cmsx4bmpm0001a0d0hwow7468",
  "pageUrl": "https://go.example.com/p/NRGvqiks5e",
  "isFormMandatory": true,
  "publicStats": false,
  "clicks": 0,
  "lastClicked": null,
  "leads": 0,
  "sales": 0,
  "saleAmount": 0,
  "createdAt": "2026-08-17T11:19:15.828Z",
  "updatedAt": "2026-08-17T11:19:15.828Z",
  "tagId": null,
  "comments": null,
  "notificationToken": null,
  "useAsTemplate": false,
  "tags": [],
  "shortLink": "https://go.example.com/whitepaper",
  "qrCode": "https://api.codeqr.io/qr?url=https://go.example.com/whitepaper?qr=1"
}

Criar um link com formulário externo

curl -X POST https://api.codeqr.io/links \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/catalog",
    "domain": "go.example.com",
    "key": "catalog-form",
    "preRedirection": true,
    "pageUrl": "https://docs.google.com/forms/d/e/1FAIpQLSf_prf_docs_example/viewform?embedded=true"
  }'

200 OK com "preRedirection": true, "pageId": null, "pageUrl": "https://docs.google.com/forms/…", "isFormMandatory": false.

Alterar um link existente

Trocar de uma Página da CodeQR para um formulário externo:

curl -X PUT https://api.codeqr.io/links/cmsx55jec0003ui96u4owiiyb \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "preRedirection": true, "pageId": null,
        "pageUrl": "https://form.typeform.com/to/prfDocsExample", "isFormMandatory": false }'

Desligar o formulário (os demais campos ficam gravados):

curl -X PUT https://api.codeqr.io/links/cmsx55jec0003ui96u4owiiyb \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "preRedirection": false }'

200 OK — a resposta ainda mostra "pageId": "cmsx4bmpm0001a0d0hwow7468", "pageUrl": "https://go.example.com/p/NRGvqiks5e", "isFormMandatory": true com "preRedirection": false.

QR Codes dinâmicos

Mesmos campos em POST /qrcodes e PUT /qrcodes/{qrcodeId}, qualquer tipo:

curl -X POST https://api.codeqr.io/qrcodes \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "whatsapp",
    "static": false,
    "domain": "go.example.com",
    "key": "wa-qr",
    "whatsapp": { "number": "5511999999999", "message": "Hi, I want the catalog" },
    "preRedirection": true,
    "pageId": "cmsx4bmpm0001a0d0hwow7468",
    "pageUrl": "https://go.example.com/p/NRGvqiks5e"
  }'

200 OK; depois do formulário o visitante é enviado para https://wa.me/5511999999999?text=Hi%2C%20I%20want%20the%20catalog. Para um QR Code de URL envie "type": "url", "url": "https://example.com/menu".

Erros

preRedirection: true sem pageUrl (também pageId sem pageUrl) — Status: 400 · error.code: unprocessable_entity · error.message: Pre-redirection page URL missing
pageUrl: "not a url" — Status: 400 · error.code: unprocessable_entity · error.message: Invalid pre-redirection page URL
isFormMandatory: true sem pageId — Status: 400 · error.code: unprocessable_entity · error.message: CodeQR page required for form submission
pageId desconhecido — Status: 404 · error.code: not_found · error.message: Page not found
workspace abaixo de Business ligando o recurso — Status: 403 · error.code: forbidden · error.message: You can only use pre-redirection on a Business plan and above. Upgrade to Business to use this feature.

Exemplo de corpo:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Pre-redirection page URL missing",
    "doc_url": "https://docs.codeqr.io/api-reference/errors#unprocessable_entity"
  }
}

Em massa e importação CSV

POST /links/bulk e POST /qrcodes/bulk aceitam os mesmos quatro campos por item. Os importadores CSV do app (Links e QR Codes → importar) aceitam as colunas PRE_REDIRECTION, PAGE_URL e PAGE_ID; isFormMandatory não é importável — defina depois com PUT. Veja Preencher CSV para importar QR Codes.

Webhooks e automações

Os payloads de link.created, link.updated, qrcode.created e qrcode.updated trazem os quatro campos, então uma automação a jusante consegue reagir a um formulário sendo ligado.
Um envio num formulário de Página da CodeQR gera um evento lead.created quando a página está com o Monitoramento de conversão ligado (Pro ou superior): customer (nome, e-mail, customFields com os campos do formulário rerrotulados e os valores de UTM do link curto), interaction (o clique) e o objeto link ou qrcode. Nada é emitido para formulários externos.
Zapier, Make, Pluga: para criar um link com formulário use um passo HTTP (no Make, o módulo Make an API Call do app da CodeQR) com o corpo do POST /links acima. Para receber os leads use o gatilho lead.created — com o Monitoramento de conversão ligado. Veja Para onde vão os leads.
MCP: peça ao agente para criar o link e depois defina os quatro campos com um PUT /links/{linkId} — as tools do MCP não os aceitam hoje.

Como verificar

curl -s https://api.codeqr.io/links/cmsx55jec0003ui96u4owiiyb \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" | grep -oE '"(preRedirection|pageId|pageUrl|isFormMandatory)":[^,]*'
# "preRedirection":true
# "pageId":"cmsx4bmpm0001a0d0hwow7468"
# "pageUrl":"https://go.example.com/p/NRGvqiks5e"
# "isFormMandatory":true

curl -sI -A "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X)" https://go.example.com/whitepaper | grep -i x-pathname
# x-pathname: /go.example.com/pre-redirection/whitepaper/link

Configure formulários de pré-redirecionamento pela API

Disponibilidade

Os quatro campos

Criar um link com formulário de Página da CodeQR (obrigatório)

Criar um link com formulário externo

Alterar um link existente

QR Codes dinâmicos

Erros

Em massa e importação CSV

Webhooks e automações

Como verificar

Artigos relacionados

Produto

Soluções

Recursos

Empresa

Legal