Documentation 9 min read

Documentação

Published: June 23, 2025 Last Updated: June 23, 2025

1. Introdução

O Form Express é uma plataforma robusta projetada para simplificar radicalmente a coleta de dados através de formulários HTML no seu site. Em vez de construir e manter um backend complexo para processar envios de formulários, o Form Express fornece um endpoint seguro para onde você pode enviar os dados do seu formulário. Os dados enviados ficam disponíveis instantaneamente em um painel de controle (dashboard) intuitivo, com métricas detalhadas e ferramentas de gerenciamento.

Principais Vantagens:

  • Sem Backend Complexo: Elimina a necessidade de programar lógica de servidor extensa para seus formulários.
  • Fácil Integração: Basta adicionar um URL específico ao atributo action do seu formulário HTML.
  • Upload de Arquivos: Suporte integrado para uploads de arquivos de até 10MB por formulário.
  • Dashboard Centralizado: Visualize, gerencie e analise todos os envios e erros em um único local.
  • Seguro: Os dados são armazenados com segurança, e a plataforma oferece recursos como validação de domínio, honeypot e rate limiting.
  • Gerenciamento de Chaves de API: Controle granular sobre quais domínios podem enviar dados, se o upload de arquivos é permitido e por quanto tempo os envios são retidos.
  • Métricas Detalhadas: Acompanhe o desempenho dos seus formulários com gráficos e estatísticas.
  • Separação de Envios: Distinção clara entre envios de humanos e bots.
  • Log de Auditoria: Rastreie ações importantes realizadas na plataforma.
  • Personalização: Opções para tema (claro/escuro) e configurações de comportamento da aplicação.
  • Busca Global: Encontre rapidamente API Keys, Submissions, Erros e outros dados em sua conta.

2. Primeiros Passos

Solicitando Acesso

Para começar a usar o Form Express, o processo de solicitação de acesso geralmente envolve:

  1. Acesse a Página Inicial: Vá para o site principal do Form Express.
  2. Encontre a Seção de Solicitação: Role até a seção "Solicite acesso ao Form Express!" ou clique no link correspondente no menu.
  3. Preencha o Formulário: Informe seu nome completo, e-mail e, opcionalmente, o URL do seu site.
  4. Envie: Clique em "Solicitar Acesso".
  5. Aguarde a Aprovação: Sua solicitação será analisada pela equipe. Um administrador criará sua conta e você receberá um e-mail com as credenciais (e-mail e senha) ou instruções para o primeiro acesso.

Fazendo Login

Após a aprovação e criação da sua conta:

  1. Vá para a Página de Login: Acesse a página /login.
  2. Insira suas Credenciais: Utilize o e-mail e a senha fornecidos.
  3. Autentique: Clique no botão de login para acessar seu painel.

O sistema utiliza cookies de sessão seguros (httpOnly, secure em produção, sameSite: 'lax') para manter sua sessão ativa.

3. Visão Geral do Painel (Dashboard)

Ao fazer login, você será direcionado ao painel principal (/dashboard), que organiza as funcionalidades da plataforma.

Navegação

A interface é composta por uma barra lateral (Sidebar) e uma barra superior (Top Bar).

  • Sidebar: Contém os links para as principais seções:
    • Dashboard: Exibe métricas e uma visão geral da atividade dos seus formulários.
    • API Keys: Gerencie suas chaves de API.
    • Submissions: Visualize os envios de formulários classificados como de humanos.
    • Bot Submissions: Visualize os envios classificados como de bots.
    • Errors: Verifique logs de erros ocorridos durante os envios.
    • Partner Ads: Crie e gerencie anúncios.
    • Logout: Desconecta você da plataforma.
  • Top Bar: Oferece acesso a:
    • Settings: Configure preferências da aplicação.
    • Audit Log: Visualize o registro de atividades (se habilitado).
    • Busca Global: Um campo de busca para encontrar rapidamente dados em sua conta (se habilitado).

No rodapé da sidebar, há um botão para alternar o tema da interface (claro/escuro).

4. Gerenciando Chaves de API (API Keys)

As Chaves de API são essenciais para conectar seus formulários HTML ao Form Express.

Criando uma Nova Chave de API

  1. Navegue: Vá para a seção "API Keys".
  2. Clique em "Create API Key".
  3. Preencha os Campos:
    • API Key Name: Um nome descritivo para sua chave (ex: "Formulário de Contato Site Principal").
    • Primary Allowed Domain: O domínio principal onde o formulário será hospedado (ex: meusite.com.br). Obrigatório, a menos que o "Development Mode" esteja ativo.
    • Secondary Allowed Domain: Um domínio secundário opcional, útil para ambientes de teste (ex: dev.meusite.com.br).
    • Development Mode (Checkbox): Se marcado, desabilita a validação de domínio.
    • Enable File Uploads (Checkbox): Permite que formulários usando esta chave aceitem uploads de arquivos (limite de 10MB por envio).
    • Submission Retention (Days): Define por quantos dias os envios para esta chave serão mantidos. 0 para reter indefinidamente.
  4. Clique em "Create API Key".

Visualizando e Gerenciando Chaves

Na página "API Keys", uma tabela lista suas chaves com as seguintes colunas: Name, Key (com botão para copiar), Primary Domain, Secondary Domain, Dev Mode, File Uploads, Retention e Created. As ações disponíveis são:

  • Edit: Abre o formulário para editar as configurações da chave.
  • Delete: Remove a chave permanentemente.

5. Integrando Formulários ao Seu Site

A integração é feita diretamente no HTML do seu site.

Estrutura Básica do Formulário

Modifique seu formulário para que ele aponte para o endpoint do Form Express:

<form action="https://form-express.com.br/submit/SUA_API_KEY_AQUI" method="POST" enctype="multipart/form-data">
  <label for="email">Email:</label>
  <input type="email" id="email" name="email" required>

  <label for="anexo">Anexo:</label>
  <input type="file" id="anexo" name="anexo">

  <input type="hidden" name="_next" value="[https://seu-site.com/obrigado.html](https://seu-site.com/obrigado.html)">
  <input type="hidden" name="_error" value="[https://seu-site.com/erro.html](https://seu-site.com/erro.html)">
  <input type="text" name="_honeypot" style="display:none">

  <button type="submit">Enviar</button>
</form>

Pontos Chave:

  • action: A URL deve ser https://form-express.com.br/submit/[SUA_CHAVE_DE_API].
  • method="POST": É obrigatório usar o método POST.
  • enctype="multipart/form-data": Essencial se o seu formulário permite upload de arquivos.
  • Atributo name: Cada campo (input, textarea, select) deve ter um atributo name, que será usado como o identificador do dado no painel.

Campos Especiais (prefixo _)

  • _next: Redireciona o usuário para uma URL específica em caso de sucesso.
  • _error: Redireciona para uma URL específica em caso de erro.
  • _honeypot: Um campo oculto para enganar bots. Se preenchido, o envio é descartado silenciosamente.
  • Outros campos com _: Qualquer outro campo cujo name comece com _ (ex: _password_confirm) será ignorado e não será salvo no banco de dados.

6. Visualizando Envios de Formulários

Páginas "Submissions" e "Bot Submissions"

Acesse estas seções para ver os dados recebidos.

  • Filtro por API Key: Permite filtrar os envios por uma chave de API específica.
  • Tabela de Envios: Exibe os envios com colunas para API Key, Data Preview (com um ícone de clipe se houver arquivos), IP Address (clicável, se habilitado) e Timestamp.
  • Ações:
    • View Details: Abre uma página com todos os dados do envio, metadados (IP, User Agent), lista de arquivos (com pré-visualização para imagens) e um botão para ver o JSON bruto.
    • Mark as Bot / Mark as Human: Move o envio entre as categorias de "humano" e "bot".
    • Delete: Remove o registro do envio.
    • Block IP: Adiciona o IP do envio à lista de bloqueio.
  • Gerenciamento em Massa (Bot Submissions):
    • Delete All Bots: Permite remover todos os envios de bots da sua conta.

7. Analisando Métricas (Dashboard)

A seção "Dashboard" (/dashboard) oferece insights visuais sobre a atividade dos seus formulários.

Visão Geral

  • Cards de Contagem: Exibem totais de envios (total, hoje, semana, mês), total de erros e número de API keys.
  • Gráficos:
    • Envios nos últimos 30 dias (gráfico de linha).
    • Comparativo entre envios de humanos e bots (gráfico de pizza).
    • Total de envios por chave de API (gráfico de barras).
  • Listas de Topo:
    • Tipos de erro mais comuns.
    • Contagem de erros por chave de API.
    • Top 10 User Agents para envios com e sem erros.

8. Gerenciando Configurações (Settings)

A página "Settings" permite personalizar sua experiência na plataforma.

  • Enable Global Search Bar: Ativa/desativa a barra de busca global.
  • Enable Audit Logging: Ativa/desativa o log de auditoria.
  • Items Per Page: Define a quantidade de itens por página nas tabelas de listagem.
  • IP Address Lookup:
    • Enable IP Address Lookup: Permite buscar detalhes de IPs usando o serviço ipdata.co.
    • ipdata.co API Key: Chave de API necessária para a funcionalidade acima.
  • Form Filtering:
    • Bot User Agents: Lista de substrings de user agents para classificar envios como bot.
    • Temp Email Providers: Domínios de e-mail descartáveis para classificar envios como bot.
    • Blocked Keywords: Palavras-chave que, se presentes nos dados do formulário, classificam o envio como bot.
  • IP Blocking:
    • Blocked IP Addresses: Lista de endereços IP bloqueados manualmente. Envios destes IPs são classificados como bot.
    • Block and Auto-delete Submissions: Se habilitado, ao bloquear um IP a partir de um envio, o envio original é automaticamente excluído.
  • Rate Limiting:
    • Submit Rate Limit Window (ms): Janela de tempo para o limite de envios.
    • Submit Rate Limit Max Requests: Número máximo de envios por IP dentro da janela.

9. Gerenciando Anúncios de Parceiros (Partner Ads)

Esta seção permite criar anúncios que são exibidos na página de sucesso padrão do Form Express.

Criando/Editando um Anúncio

  1. Navegue até "Partner Ads" e clique em "Create Partner Ad" ou "Edit".
  2. Preencha os campos:
    • Ad Name: Nome interno do anúncio.
    • Ad Image: Upload de uma imagem (até 5MB).
    • Ad Link: URL de destino do anúncio.
    • Description (Alt Text): Texto alternativo para a imagem.
    • Priority: Número que influencia a frequência de exibição (maior = mais frequente).
    • Active: Define se o anúncio pode ser exibido.
  3. Salve as alterações.

Visualizando Anúncios

A lista de anúncios exibe: Nome, Imagem, Link, Descrição, Prioridade, Status (Ativo/Inativo), Contagem de Exibições, Data de Criação e Ações.

10. Visualizando Erros de Submissão

A página "Submission Errors" lista todas as tentativas de envio que falharam por motivos como chave de API inválida, domínio não permitido, rate limit excedido, honeypot acionado, entre outros.

  • Tabela de Erros: Exibe API Key, Mensagem de Erro, IP e Timestamp.
  • Ações:
    • View Details: Mostra detalhes completos do erro, incluindo o JSON bruto dos dados.
    • Delete: Remove o registro de erro.
    • Delete All Errors: Remove todos os registros de erro da sua conta.

11. Log de Auditoria (Audit Log)

Se habilitado em "Settings", o "Audit Log" registra ações importantes realizadas na plataforma.

  • Visualização: A tabela de logs exibe Timestamp, Usuário, Ação (ex: LOGIN, API_KEY_CREATE), Coleção Alvo, Registro Alvo, IP e Detalhes.
  • Ações:
    • View Details: Abre um modal com os detalhes do evento em JSON.
    • Clear All My Logs: Limpa todos os seus registros de auditoria.
    • Export CSV: Baixa seus registros em formato CSV.

12. Busca Global

Se habilitada em "Settings", a barra de busca no topo da página permite pesquisar em:

  • API Keys: Por nome ou domínios.
  • Form Submissions: Por dados contidos no envio, IP ou user agent.
  • Submission Errors: Por mensagem de erro, URL, IP ou user agent.
  • Partner Ads: Por nome, link ou descrição.

Os resultados são exibidos em uma página dedicada com paginação.

13. Segurança

O Form Express implementa várias medidas de segurança para proteger os dados e a plataforma.

  • Validação de Domínio: Garante que envios só sejam aceitos de domínios configurados na chave de API (a menos que o modo de desenvolvimento esteja ativo).
  • Honeypot: Técnica simples contra bots de spam automatizados.
  • Rate Limiting: Limita o número de envios de formulário por IP para cada chave de API e também limita tentativas de login.
  • Sanitização de Dados: Os dados de formulário são sanitizados no backend antes do armazenamento para prevenir ataques de XSS.
  • Content Security Policy (CSP): Configurado via Helmet para mitigar riscos de XSS e outros ataques de injeção.
  • Sessões Seguras: Cookies de sessão configurados com httpOnly, secure (em produção) e sameSite: 'lax'.
  • Hashing de IP: Endereços IP podem ser armazenados como hash para privacidade, com a opção de armazenar o IP real para fins de lookup.
  • Limpeza de Dados: Tarefas agendadas (cron jobs) removem envios expirados (com base na política de retenção da API Key) e registros órfãos para manter a base de dados limpa.