Documentation 13 min read

Form Express

Published: April 16, 2025 Last Updated: June 11, 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.

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. Você provavelmente receberá um e-mail com as credenciais (e-mail e senha) ou instruções assim que o acesso for liberado e sua conta for criada por um administrador.

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 (geralmente clicando no botão "Entrar" na página inicial, se houver, ou navegando diretamente).
  2. Insira suas Credenciais: Utilize o e-mail e a senha fornecidos.
  3. Autentique: Clique no botão de login para acessar seu painel.

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 Lateral (Sidebar)

A barra lateral, que pode ser expandida ou recolhida, 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, domínios permitidos, upload de arquivos e políticas de retenção.
  • Submissions: Visualize os dados enviados por humanos através dos seus formulários.
  • Bot Submissions: Visualize os dados identificados como enviados por bots.
  • Errors: Verifique logs de erros ocorridos durante o processamento de envios (ex: domínio inválido, rate limit).
  • Partner Ads: Crie e gerencie anúncios de parceiros que podem ser exibidos na página de sucesso do envio.
  • Settings: Configure preferências da aplicação, como tema, paginação, e recursos como log de auditoria e busca global.
  • Logout: Desconecta você da plataforma.

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

Cabeçalho Superior (Top Bar)

O cabeçalho superior oferece:

  • Alternar Menu Lateral:
    • Em desktops/tablets: Botão para expandir ou recolher a sidebar.
    • Em dispositivos móveis: Botão "Hamburguer" para abrir/fechar a sidebar.
  • Busca Global (se habilitada): Um campo de busca para encontrar rapidamente API Keys, Submissions, Erros e Partner Ads.

4. Gerenciando Chaves de API (API Keys)

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

Por que Chaves de API?

  • Identificação: Cada chave é única e vincula os envios de um formulário específico à sua conta de usuário.
  • Segurança: Permitem controlar de quais domínios (sites) os envios são aceitos, prevenindo o uso não autorizado da sua chave.
  • Controle de Recursos: Permitem habilitar ou desabilitar funcionalidades, como o upload de arquivos e definir políticas de retenção de dados, por chave.
  • Organização: Ajuda a separar dados de diferentes formulários ou sites.

Criando uma Nova Chave de API

  1. Navegue: Vá para a seção "API Keys" na barra lateral.
  2. Clique em "Create API Key": Você será direcionado para a página de criação.
  3. Preencha os Campos:
    • API Key Name: Um nome descritivo para sua chave (ex: "Formulário de Contato Site Principal").
    • Primary Allowed Domain: (ex: meusite.com.br) O domínio principal onde o formulário será hospedado. Este campo é obrigatório, a menos que o "Development Mode" esteja ativo.
    • Secondary Allowed Domain: (ex: dev.meusite.com.br) Opcionalmente, um segundo domínio permitido (útil para ambientes de teste). Ignorado se o "Development Mode" estiver ativo.
    • Development Mode (Checkbox): Se marcado, as restrições de domínio (primário e secundário) são desabilitadas para esta chave. Use apenas para testes locais ou em ambientes onde o cabeçalho Referer ou Origin pode não ser enviado corretamente.
    • Enable File Uploads (Checkbox): Se marcado, permite que formulários usando esta chave de API aceitem e armazenem uploads de arquivos (até 10MB). Se desmarcado, os arquivos enviados serão ignorados.
    • Submission Retention (Days): Define por quantos dias os envios para esta chave serão mantidos. Após este período, eles são excluídos automaticamente por uma tarefa agendada. Defina como 0 para manter os envios indefinidamente.
  4. Clique em "Create API Key": A chave será gerada e você será redirecionado para a lista de chaves.

Visualizando e Excluindo Chaves

Na página "API Keys", você verá uma tabela listando suas chaves:

  • Name: O nome que você deu à chave.
  • Key: A chave de API gerada (um botão "Copy" permite copiar a chave completa para a área de transferência).
  • Primary Domain: O domínio principal configurado.
  • Secondary Domain: O domínio secundário configurado (ou "N/A").
  • Dev Mode: Indica se o modo de desenvolvimento está ativo ("Yes" ou "No").
  • File Uploads: Indica se o upload de arquivos está habilitado ("Yes" ou "No").
  • Retention: O número de dias que os envios são mantidos (ou "Forever" se for 0).
  • Created: A data de criação da chave.
  • Actions:
    • Edit: Abre o formulário para editar as configurações da chave.
    • Delete: Botão para excluir a chave permanentemente. Cuidado: Excluir uma chave impedirá que formulários que a utilizam funcionem corretamente.

5. Integrando Formulários ao Seu Site

Integrar o Form Express ao seu site requer apenas modificações no seu HTML.

Estrutura Básica do Formulário

Modifique seu formulário HTML existente ou crie um novo com a seguinte estrutura:

<form action="[URL_BASE_DO_FORM_EXPRESS]/submit/SUA_API_KEY_AQUI" method="POST" enctype="multipart/form-data">
  <!-- Seus campos de formulário (inputs, textareas, selects, etc.) -->
  <label for="email">Email:</label>
  <input type="email" id="email" name="email" required>

  <label for="password">Senha:</label>
  <input type="password" id="password" name="password" required>

  <!-- Este campo não será salvo no banco de dados -->
  <label for="password_confirm">Confirmar Senha:</label>
  <input type="password" id="password_confirm" name="_password_confirm" required>

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

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

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

Pontos Chave:

  • method="POST": É essencial usar o método POST.
  • enctype="multipart/form-data": Essencial para formulários que enviam arquivos. Se o seu formulário não tiver um campo de upload de arquivo, este atributo não é necessário.
  • Campos (name attribute): Certifique-se de que cada campo do seu formulário (input, textarea, select) tenha um atributo name. O valor deste atributo será usado como identificador do dado no painel do Form Express.

Campos Especiais (Opcional)

Você pode adicionar campos input para controlar o comportamento pós-envio e adicionar segurança:

  • _next: Redirecionamento em Caso de Sucesso Redireciona o usuário para uma URL específica após o envio do formulário ser processado com sucesso. Se este campo não for fornecido, o usuário verá a página de sucesso padrão do Form Express.

    <input type="hidden" name="_next" value="https://seu-site.com/obrigado.html">

  • _error: Redirecionamento em Caso de Erro Redireciona o usuário para uma URL específica se ocorrer um erro durante o processamento do envio (ex: domínio inválido, rate limit excedido). Se não for fornecido, o usuário verá a página de erro padrão do Form Express.

    <input type="hidden" name="_error" value="https://seu-site.com/ops-algo-deu-errado.html">

  • _honeypot: Proteção Anti-Spam Adiciona um campo invisível para humanos, mas que bots de spam costumam preencher. Se este campo for preenchido, o Form Express silenciosamente tratará o envio como bem-sucedido para o bot, mas não armazenará os dados como uma submissão válida (pode ser registrado como um erro ou evento de honeypot).

    <input type="text" name="_honeypot" style="display:none">

  • Campos Ignorados (prefixo _) Qualquer campo de formulário cujo atributo name comece com um sublinhado (_), com exceção dos campos especiais _next e _error, será ignorado pelo servidor e não será salvo no banco de dados. Isso é útil para campos como confirmação de senha, que são necessários para validação no frontend, mas não precisam ser armazenados.

    <input type="password" name="_password_confirm">

6. Visualizando Envios de Formulários

Páginas "Submissions" e "Bot Submissions"

Acesse as seções "Submissions" (para envios humanos) e "Bot Submissions" (para envios identificados como de bots) para ver os dados recebidos.

  • Filtro por API Key: Um menu dropdown permite filtrar os envios por uma chave de API específica ou visualizar todos.
  • Tabela de Envios: Uma tabela exibe os envios.
    • Colunas Comuns: API Key (nome da chave), Data Preview (uma prévia dos primeiros campos enviados, com um ícone de clipe se houver arquivos), IP Address (clicável para ver detalhes se o IP Lookup estiver habilitado), Timestamp.
    • Ações:
      • View Details: Abre uma página dedicada (/submissions/:id) com todos os dados daquele envio específico, incluindo metadados como IP, User Agent, uma lista de arquivos anexados (com pré-visualização para imagens), e um botão para ver o JSON bruto.
      • Delete: Remove o registro do envio.

Gerenciando Envios

  • Refresh: Use o botão "Refresh" para recarregar a lista de envios.
  • Delete All Bots (na página Bot Submissions): Permite remover todos os envios identificados como de bots para sua conta. Use com cuidado.

7. Analisando Métricas (Dashboard)

A seção "Dashboard" (/dashboard) oferece insights sobre como seus formulários e chaves de API estão sendo utilizados.

Visão Geral em Cards

  • Total Submissions: Número total de envios humanos.
  • Submissions Today: Envios humanos recebidos hoje.
  • Total Errors: Número total de erros de submissão registrados.
  • API Keys: Quantidade total de chaves de API criadas.
  • Submissions Activity: Contagem de envios humanos para "This Week" e "This Month".
  • Errors Activity: Contagem de erros para "This Week" e "This Month".

Gráficos

  • Submissions Over Last 30 Days: Gráfico de linha mostrando a tendência de envios humanos.
  • Human vs. Bot Submissions: Gráfico de pizza comparando o volume de envios humanos e de bots.
  • Submissions by API Key: Gráfico de barras mostrando o total de envios por cada chave de API.

Listas de Topo

  • Top Error Types: Lista os tipos de erro mais comuns.
  • Errors by API Key: Mostra a contagem de erros para cada chave de API que registrou erros.
  • Top 10 Submission User Agents: Lista os user agents mais frequentes em envios bem-sucedidos.
  • Top 10 Error User Agents: Lista os user agents mais frequentes em envios que resultaram em erro.

Use o botão de atualização na página do dashboard (se disponível) ou recarregue a página para obter os dados mais recentes.

8. Gerenciando Configurações da Conta (Settings)

Acesse a página "Settings" pela barra lateral para personalizar o comportamento da sua conta Form Express.

  • Enable Global Search Bar: Ativa ou desativa a barra de busca global no cabeçalho.
  • Enable Audit Logging: Ativa ou desativa o registro detalhado de ações no sistema. Se ativo, você pode acessar o "Audit Log" (veja seção 11).
  • Items Per Page (Pagination): Define quantos itens são exibidos por página nas tabelas de listagem (ex: Submissions, API Keys).
  • IP Address Lookup:
    • Enable IP Address Lookup: Permite que endereços IP clicáveis nas listas de Submissions e Errors busquem detalhes usando o serviço ipdata.co.
    • ipdata.co API Key: Se o lookup estiver habilitado, esta chave (obtida em ipdata.co) é necessária.
  • Form Filtering:
    • Bot User Agents: Uma lista (um por linha) de substrings de user agents. Envios de user agents que contenham qualquer uma dessas substrings serão classificados como "Bot Submissions".

Clique em "Save Settings" para aplicar as alterações.

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

A seção "Partner Ads" permite criar e gerenciar anúncios que podem ser exibidos na página de sucesso padrão após um envio de formulário bem-sucedido (se um redirecionamento personalizado não for usado).

Criando/Editando um Partner Ad

  1. Navegue: Vá para "Partner Ads".
  2. Clique em "Create Partner Ad" ou "Edit" em um anúncio existente.
  3. Preencha/Modifique os Campos:
    • Ad Name: Nome interno para o anúncio.
    • Ad Image: Faça upload de uma imagem (JPEG, PNG, GIF, max 5MB). Ao editar, você pode optar por limpar a imagem existente.
    • Ad Link: A URL para onde o anúncio redirecionará.
    • Description (Alt Text): Texto alternativo para a imagem (importante para acessibilidade).
    • Priority: Número que influencia a probabilidade do anúncio ser selecionado (maior prioridade = mais chances). Padrão é 1.
    • Active (Checkbox): Define se o anúncio está ativo e pode ser exibido.
  4. Clique em "Create Ad" ou "Update Ad".

Visualizando Partner Ads

A lista mostra: Nome, Imagem (miniatura), Link, Descrição, Prioridade, Status (Ativo/Inativo), Contagem de Exibições, Data de Criação e Ações (Editar, Excluir).

10. Visualizando Erros de Submissão (Submission Errors)

A página "Submission Errors" lista todas as tentativas de envio que falharam devido a problemas como:

  • Chave de API inválida ou não encontrada.
  • Envio de um domínio não permitido para a chave de API.
  • Rate limit excedido.
  • Honeypot acionado (se configurado para registrar como erro).
  • Outros erros internos durante o processamento.

Detalhes do Erro

  • Tabela de Erros: Exibe API Key associada (se conhecida), Mensagem de Erro, Endereço IP, Timestamp.
  • Ações:
    • View Details: Abre uma página com todos os detalhes do erro, incluindo URL da requisição, User Agent, e dados adicionais ou stack trace, se disponíveis. Um botão "View Raw Data" mostra o JSON completo do registro de erro.
    • Delete: Remove o registro do erro.

11. Log de Auditoria (Audit Log)

Se habilitado nas "Settings", o "Audit Log" registra ações importantes realizadas por você na plataforma.

Visualizando o Log

  • Acesse "Audit Log" (o link pode estar em "Settings" ou ser um item de menu principal se habilitado).
  • Tabela de Logs: Exibe Timestamp, Usuário (quem realizou a ação), Ação (ex: LOGIN, API_KEY_CREATE, SETTINGS_UPDATE), Coleção Alvo, Registro Alvo, Endereço IP e Detalhes (em formato JSON).
  • Ações:
    • View Details (Botão): Abre um modal mostrando os detalhes do evento em formato JSON.
    • Clear All My Logs: Permite limpar todos os seus registros de auditoria.
    • Export CSV: Baixa seus registros de auditoria em formato CSV.

12. Segurança

O Form Express implementa várias medidas de segurança:

  • Validação de Domínio: Garante que os envios só sejam aceitos dos domínios configurados na sua chave de API (a menos que o modo de desenvolvimento esteja ativo).
  • Honeypot: Técnica simples e eficaz contra bots de spam automatizados.
  • Armazenamento Seguro: Utiliza PocketBase para armazenar dados.
  • HTTPS: Toda a comunicação com a plataforma e o endpoint de envio deve ocorrer sobre HTTPS.
  • Rate Limiting:
    • Limita o número de envios de formulário por IP para cada chave de API, com configurações personalizáveis pelo usuário (via app_settings).
  • Content Security Policy (CSP): Configurado via Helmet para mitigar riscos de XSS e outros ataques de injeção.
  • Sanitização de Dados: Os dados de formulário são sanitizados no backend antes do armazenamento para prevenir XSS nos dados visualizados.
  • 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, embora o sistema disponibiliza uma opção para habilitar e pesquisar endereços IP reais.