# Marketing Forms — Master Implementation Guide (LLM-Ready)
> Formulários que pessoas preenchem no seu site, por uma linha de script ou
> por um link pronto, e que agentes preenchem pelo MCP. Cada resposta vira um
> evento assinado (Standard Webhooks, cabeçalhos `x-ccm`) para os destinos que
> a conta escolher, com a página, a UTM e o link curto de onde veio — e fica na
> fila, sem se perder, quando o destino recusa. Contra robôs, sem captcha.
> Consentimento com prova, e apagar uma resposta é de uma pessoa.
>
> Este arquivo é a documentação para agentes. **Leia a seção 10 antes de
> prometer qualquer coisa**: ela diz o que o produto não faz.
Worker (API, script, formulário pronto, MCP): https://forms.worker.mymarketing.click
Painel: https://forms.dashboard.mymarketing.click
Servidor MCP: https://forms.worker.mymarketing.click/mcp — ver a seção 7.
O mapa da linha (todos os produtos, login): https://mymarketing.click/llms.txt
## 0. Estado e credenciais — leia antes de tudo
- **No ar desde 07/10/2026; na linha Marketing desde 08/10/2026.** `GET https://forms.worker.mymarketing.click/status`
responde `{"service":"marketing-forms",…}` com as entregas pendentes e
retidas.
- **Login:** o Auth da linha (`https://auth.worker.mymarketing.click`,
aplicação Marketing), com código por e-mail. Mesmo login, autorização por
produto. Passo humano obrigatório: a pessoa lê um código no e-mail e o
informa. Não tente contornar.
- **Chave da conta:** `frk_…`, criada no painel e mostrada uma vez, para um
sistema enviar respostas (`Authorization: Bearer frk_…`, até 60 por hora).
Não apaga respostas nem formulários (403) e é recusada no `/mcp`. Fica só no
servidor.
- **MCP:** OAuth, com o mesmo login (seção 7). Não usa a `frk_`.
- **Preço:** não há preço público e nada é cobrado.
Não cite valor, plano, franquia em minutos nem "grátis".
Se perguntarem: "Ainda não há planos, e nada é cobrado."
## 1. Modelo mental
- **Formulário** — até 40 campos, estado (Rascunho, Publicado, Pausado) e
versões. Publicar exige um campo de **E-mail**. Cada mudança num formulário
publicado cria a versão seguinte; cada resposta guarda a versão que viu.
- **Campos (7):** Texto curto, E-mail, Telefone (WhatsApp), Escolha única,
Múltipla escolha, Texto longo, Oculto. **Não há lógica condicional nem envio
de arquivo.**
- **Oculto** — preenchido pelo endereço da página: `utm_source`,
`utm_campaign`, `lk` (o link curto do Links que trouxe a pessoa).
- **Resposta** — os valores, a página, a origem, a versão, o canal (pessoa,
API ou agente) e o estado da entrega em cada destino. O IP nunca fica em
claro: só um hash e o começo do endereço para exibir.
- **Destino** — um endpoint de webhook, com os eventos que assina; pode ser
desligado por formulário.
## 2. Instalar
```html
```
O script desenha o Web Component `` (Shadow DOM, sem
dependências), que herda a fonte e a cor do texto da página; `show-title`
mostra o título e o texto do formulário. Sem site, o link pronto:
`https://forms.worker.mymarketing.click/f/`. Opcional: até 20
domínios onde o formulário pode rodar (conferidos pela origem do pedido).
Rotas públicas, sem login:
```
GET /embed.js o script
GET /f/:code o formulário pronto
GET /f/:code.json o esquema publicado: campos e consentimento
POST /f/:code/views conta uma abertura (robô declarado não conta)
POST /f/:code envia uma resposta → 201, ou 429 passado o limite
```
## 3. Contra robôs, sem captcha
- Um campo-isca escondido; tempo mínimo de **3 s** por um bilhete assinado
pelo servidor; limite de **5 por hora** por endereço, por formulário.
- O bloqueado vê a mesma resposta de sucesso. No painel, cada bloqueio aparece
com o motivo por 30 dias e pode virar resposta ("Aceitar como resposta", só
uma pessoa, nunca com consentimento).
- Não há captcha ligado. Não prometa um.
## 4. Consentimento e LGPD
- **Caixa de consentimento** opcional por formulário, nunca marcada sozinha,
com o texto em versões. A prova guarda a versão e o SHA-256 do texto, a hora,
a página, a versão do formulário, o hash do IP e o navegador declarado.
- **Agente nunca consente**: uma resposta de agente com consentimento é
recusada.
- **Apagar uma resposta** (`DELETE /api/responses/:id`, só a sessão de uma
pessoa) tira a resposta, a prova e o que ainda ia ser entregue; fica um
registro anônimo de que algo foi apagado. Leitura técnica da lei, não
parecer jurídico.
- **E-mail de confirmação** para quem respondeu: pelo Messages, com a chave do
Messages da conta, no máximo um por endereço, por formulário, a cada 24 h.
O SMTP próprio pode ser salvo, mas ainda não envia.
## 5. Rotas do painel e da API
Base: `https://forms.worker.mymarketing.click`, sem versão no caminho, com a
sessão do painel ou a `frk_` onde vale. Coleções respondem `{items, page}`;
erros, `{error: {code, message}}`.
```
GET /status o serviço e as promessas dele
GET /api/overview os números do mês e o que exige atenção
GET /api/forms · POST /api/forms os formulários
GET /api/forms/:id · PATCH · DELETE um formulário (DELETE pede o código, só uma pessoa)
POST /api/forms/:id/publish|pause|resume
GET /api/forms/:id/versions as versões
POST /api/forms/:id/consent-versions um texto novo de consentimento (só uma pessoa)
GET /api/forms/:id/export as respostas em CSV
POST /api/forms/:id/responses um sistema (frk_) envia uma resposta
GET /api/responses · GET …/:id as respostas, com origem, prova e entregas
DELETE /api/responses/:id apaga (LGPD) — só uma pessoa
GET /api/blocked · POST …/:id/accept as tentativas bloqueadas; aceitar como resposta
GET /api/webhooks · POST · PATCH · DELETE os destinos
POST /api/webhooks/:id/secret troca o segredo e solta as entregas retidas
POST /api/webhooks/:id/test um evento de teste assinado, agora
GET /api/deliveries · POST …/:id/retry a caixa de saída, com reenvio
GET /api/pending-actions · POST …/:id/approve|reject o que um agente pediu
GET /api/keys · POST · DELETE a chave frk_
GET /api/sender · PUT · POST /api/sender/check quem envia o e-mail de confirmação
```
## 6. Webhooks para fora
Até 20 destinos por conta. Padrão **Standard Webhooks** com o prefixo `x-ccm`:
```
x-ccm-id:
x-ccm-timestamp: 1790265731
x-ccm-signature: v1,
```
A chave do HMAC é o base64 depois de `whsec_`. Recuse timestamp com mais de
5 minutos e ignore um `x-ccm-id` já visto. Corpo:
`{ type, timestamp, data: { person, channel, properties } }`.
| Evento | Quando |
|---|---|
| `form.viewed` | o formulário foi mostrado a um visitante (sem pessoa) |
| `form.submitted` | toda resposta aceita, de pessoa ou de agente |
| `form.consented` | só quando a pessoa marca a caixa de consentimento |
| `form.blocked` | uma tentativa barrada pela isca, pelo tempo ou pelo limite |
| `form.delivery_failed` | uma entrega parou (retida por 401/403 ou falhou de vez); nunca para o destino que falhou |
| `action.pending` | um agente pediu algo que espera aprovação |
**A entrega não se perde:** toda entrega é primeiro uma linha na caixa de
saída. Se o destino falhar: nova tentativa em 1 min, 5 min, 30 min, 2 h e
12 h; depois, reenvio à mão. **401 e 403 ficam retidos**, sem gastar tentativa,
com um teste por hora; trocar o segredo solta as retidas. Só 410 é definitivo.
O reenvio leva o mesmo id: o outro lado não duplica.
**O Forms não recebe eventos de outros sistemas.** Não há
`POST /events/:sourceId`: só respostas entram.
## 7. Servidor MCP
- **Endereço:** `https://forms.worker.mymarketing.click/mcp` (Streamable
HTTP), para a conta inteira — a conta vem do token, nunca de um argumento.
- **OAuth 2.1:** metadados em
`https://forms.worker.mymarketing.click/.well-known/oauth-protected-resource`.
O token só vale para este servidor. A `frk_` é recusada.
- **Limite de envio por agente:** 5 respostas por hora, por conta, cliente e
formulário.
| Tool | Regra | O que faz |
|---|---|---|
| `forms_list` | Livre | os formulários, com estado, respostas do mês e onde estão |
| `forms_get_schema` | Livre | os campos, tipos e obrigatórios |
| `forms_submit` | Livre | envia uma resposta como agente, com o nome dele; **nunca com consentimento** |
| `forms_list_responses` | Livre | as respostas, com origem, canal e entrega |
| `forms_create` · `forms_update` · `forms_publish` | Confirma | viram pedido de aprovação que uma pessoa aprova no painel |
| `forms_delete_response` | Só humano | **não é registrada** |
## 8. Perguntar
A tela "Perguntar" do painel não tem modelo por trás: não prometa que ela
responde perguntas.
## 9. Retenção
As respostas ficam enquanto a conta existir, até alguém apagar. As tentativas
bloqueadas, 30 dias.
## 10. Escopo — o que este produto NÃO faz
- **Captcha.** **Lógica condicional** entre perguntas. **Envio de arquivo.**
- **Receber eventos** de outros sistemas.
- **Consentimento por agente**, nunca.
- **SMTP próprio**: ainda não envia; o e-mail de confirmação sai pelo Messages.
- **Avisar a conta por e-mail** a cada resposta: isso é um destino (um webhook
para a sua automação).
- **Cobrança.** Não há plano publicado, e nada é cobrado.
## 11. Checklist para agentes de IA
1. **Peça o código do formulário** (`f_…`) a uma pessoa; não invente.
2. **Instale o script** onde o formulário deve aparecer, ou entregue o link pronto.
3. **Para receber as respostas,** cadastre um destino e confira a assinatura
`x-ccm` no seu servidor.
4. **Para enviar como agente,** use `forms_submit`, sem consentimento.
5. **Não prometa lógica condicional, arquivo nem captcha.**
6. **Não invente rota nem tool.** As seções 2 e 5 listam as rotas; a 7, as tools.