# Formulários

Um formulário que você cria no painel, publica no próprio link e incorpora onde quiser. Cada envio chega como uma notificação push no seu celular — pelo mesmo caminho de entrega de um webhook, então roteamento, níveis de prioridade e histórico de mensagens funcionam do jeito que você já conhece.

Sem caixa de e-mail no meio. Sem ficar consultando uma planilha.

## Criar um formulário

**Formulários → Criar.** O criador tem cinco abas e uma prévia ao vivo ao lado:

| Aba | O que contém |
|-----|---------------|
| Campos | Título, texto de introdução, os campos em si, texto do rodapé |
| Design | Tema, cores, fonte, tamanho, raio dos cantos, botão de envio |
| Configurações | Título da push, roteamento, prioridade, limites de respostas, mensagens |
| Compartilhar | Link público, QR code, código de incorporação |
| Prévia | A mesma prévia ao vivo, para telas estreitas |

Salve, e a aba Compartilhar entrega o link: `https://frms.click/<id>`.

## Tipos de campo

| Grupo | Tipos |
|-------|-------|
| Texto | Texto curto, texto longo, e-mail, celular, número, URL, data |
| Escolha | Lista suspensa, botões de opção, caixas de seleção, caixa única (consentimento) |
| Avaliação | Avaliação com estrelas (1–5), NPS (0–10) |
| Layout | Título, parágrafo, divisor |
| Rastreamento | Campo oculto |

Até **30 campos** por formulário, e até 50 opções em um campo de escolha. Campos de e-mail, celular, número e URL são validados no navegador e de novo no servidor — a verificação do cliente é uma conveniência, não a proteção.

Campos de layout são decorativos: nunca aparecem na mensagem. Envio de arquivos e pagamentos não são suportados.

### Campos ocultos

Um campo oculto leva um valor do link para a mensagem. Dê a ele um nome de parâmetro, e `?utm_source=newsletter` na URL aparece na notificação. Um clique adiciona os cinco parâmetros UTM de uma vez.

Quando um formulário é incorporado, os parâmetros da **página hospedeira** são repassados, então uma página de campanha marca os próprios envios sem nenhum trabalho seu.

## Como fica a mensagem

As respostas vêm primeiro, na ordem em que os campos aparecem:

```
Name: Jane Doe
Email: jane@example.com
Rating: ★★★★☆ 4/5
Message: Do you ship to Canada?

utm_source: newsletter
Form: Contact
IP: 203.0.113.10
Submitted: 2026-09-23 14:05
```

Campos ocultos, o IP do visitante e o horário ficam no final, depois das respostas. O horário usa o fuso horário da sua conta. Tudo é criptografado em repouso com a sua chave pessoal, exatamente como qualquer outra mensagem.

## Título da push

Por padrão, a notificação tem o título `Form: <form name>`. Um modelo deixa o título útil de relance:

```
New lead: {Name} ({Email})
```

Os tokens referenciam campos **pelo rótulo**, sem diferenciar maiúsculas, além de `{form}` para o nome do formulário. Respostas vazias saem do título; se não sobrar nada, usa-se o título padrão. O modelo nunca aparece na página pública.

## O selo do Pocket Alert

Um formulário publicado traz um pequeno link "Powered by Pocket Alert" embaixo. Em um plano pago, você pode desativá-lo em **Design → Marca**.

Quem decide é a API, não o navegador: salvar a opção no plano gratuito a redefine, e se um plano pago expirar, o selo volta a aparecer na página pública sem que você mexa no formulário.

## Roteamento e prioridade

Um formulário pode direcionar a um aplicativo e a um dispositivo específico, e pode ter um nível de prioridade, de silencioso a crítico — os mesmos níveis da API. Deixe o nível em *Padrão* e o formulário segue suas regras normais de entrega.

Cada envio consome uma mensagem da sua cota diária. Quando a cota acaba, o visitante vê uma mensagem neutra de "tente novamente mais tarde", sem menção ao seu plano, e você recebe o e-mail de limite habitual.

## Fechar um formulário

Três chaves independentes, qualquer uma delas fecha o formulário:

- **Aceitando respostas** — desligada, fecha imediatamente
- **Limite de respostas** — fecha após N envios; a vaga é reservada antes de a mensagem ser criada, então um pico de tráfego não ultrapassa o limite
- **Fechar em** — uma data e hora no seu fuso horário

Um formulário fechado continua respondendo: os visitantes veem sua mensagem de fechado no lugar dos campos, e os envios são rejeitados no servidor.

## Incorporação

A aba Compartilhar oferece uma incorporação por script:

```html
<div data-pocketalert-form="<id>"></div>
<script src="https://frms.click/embed/form.js" async></script>
```

O formulário carrega em um iframe que informa a própria altura, então não há barra de rolagem interna nem altura fixa para manter. O fundo da página aparece por trás — defina a cor do cartão do formulário com tons compatíveis com transparência e ele se integra ao site.

Depois de um envio, o contêiner dispara um evento `pocketalert:submit` ao qual você pode conectar sua análise:

```js
document.querySelector('[data-pocketalert-form]')
  .addEventListener('pocketalert:submit', () => gtag('event', 'generate_lead'));
```

Onde scripts não são permitidos, também é fornecido um trecho simples com `<iframe>` — altura fixa, e os parâmetros da URL não são repassados.

## Restringir onde o formulário pode ser usado

O id de um formulário é público — ele viaja no link e no QR code — então, por padrão, qualquer pessoa que o tenha pode incorporar o formulário em qualquer página. **Configurações → Onde pode ser usado** recebe uma lista de domínios e encerra isso:

- apenas esses sites podem incorporar o formulário (a página é servida com uma política `frame-ancestors` correspondente);
- um envio cujo `Origin` (ou `Referer`) não esteja na lista é rejeitado com `403`;
- o link próprio do formulário continua funcionando, independentemente disso.

Escreva hosts, não URLs: `example.com`, `app.example.com`, `*.example.com` para todos os subdomínios, `localhost:3000` durante o desenvolvimento. Até 10 entradas. `www.` é ignorado, então `example.com` cobre `www.example.com`.

Uma lista vazia significa "em qualquer lugar", que é a configuração certa para um link que você compartilha na bio ou um QR code em um cartaz.

> **Warning: O que isso faz e o que não faz**
>
> `Origin` é definido pelo navegador e não pode ser forjado por uma página. Um script que fala diretamente com a API pode enviar qualquer cabeçalho que quiser, então a lista de permitidos impede que o seu formulário seja incorporado no site de outra pessoa — não é uma defesa contra um flooder determinado. Os limites de taxa abaixo cobrem esse caso.

## De onde veio um envio

Quando um envio chega de um formulário incorporado, o host é registrado na mensagem, ao lado do IP:

```
Form: Contact (abc123)
Source: shop.example.com
IP: 203.0.113.10
```

Envios feitos na página própria do formulário não têm a linha `Source`.

## Proteção contra spam

- Um campo honeypot que nenhum humano vê. Bots que o preenchem recebem uma tela de sucesso com aparência normal, e nada é entregue.
- Limites de taxa: 10 envios por minuto a partir de um mesmo IP, 60 por minuto e 300 por hora por formulário. O teto por hora existe para que um flood não esgote um dia inteiro de mensagens em poucos minutos.
- As páginas públicas de formulário são `noindex`, então um formulário não aparece nos resultados de busca por conta própria.

CAPTCHA não é exigido nem oferecido em formulários por enquanto.

## Limites por plano

| Plano | Formulários |
|------|-------|
| Gratuito | 1 |
| Starter | 10 |
| Medium | 30 |
| Large | Ilimitado |

Os envios em si são limitados apenas pela sua cota diária de mensagens.

## API

Tudo o que o criador faz está disponível pela API REST:

| Endpoint | O que faz |
|----------|--------------|
| [`GET /v1/forms`](https://info.pocketalert.app/api/forms/get-forms.md) | Listar seus formulários |
| [`POST /v1/forms`](https://info.pocketalert.app/api/forms/create.md) | Criar um |
| [`PUT /v1/forms/:tid`](https://info.pocketalert.app/api/forms/update.md) | Substituir seus campos, design e configurações |
| [`DELETE /v1/forms/:tid`](https://info.pocketalert.app/api/forms/delete.md) | Excluir |
| [`GET /v1/forms/:tid`](https://info.pocketalert.app/api/forms/get-form.md) | Público: os campos e o design de um formulário ativo |
| [`POST /v1/forms/:tid/submit`](https://info.pocketalert.app/api/forms/submit.md) | Público: aceitar um envio |

As quatro primeiras usam o seu token normal; as duas últimas são o que a própria página do formulário chama.
