Como Prevenir Envios Duplos de Formulários

Um usuário clica em “Enviar” no seu formulário de checkout. Nada acontece imediatamente. Ele clica novamente. Agora você tem dois pedidos, duas cobranças e um cliente frustrado.

Este cenário ocorre constantemente em aplicações em produção. Usuários clicam duas vezes por hábito, redes apresentam latência imprevisível e dedos impacientes tocam repetidamente. O resultado: entradas duplicadas no banco de dados, transações falhadas e tickets de suporte.

Este artigo aborda como prevenir envios duplos de formulários usando proteção em camadas—combinando estratégias client-side com idempotência server-side para construir fluxos de envio que permanecem resilientes sob condições do mundo real.

Por Que Proteção de Camada Única Falha

Confiar apenas em desabilitar um botão de envio parece direto. Mas considere estes cenários:

• JavaScript falha ao carregar ou executar
• Usuários enviam via teclado (tecla Enter) antes que seu handler execute
• Requisições de rede expiram e usuários recarregam a página
• Bots ou scripts contornam seu frontend completamente

Medidas client-side melhoram a experiência do usuário, mas não podem garantir proteção. Validação server-side permanece essencial porque requisições podem se originar de qualquer lugar—navegadores, curl, aplicativos móveis ou atores maliciosos.

Boas práticas efetivas de envio de formulários requerem defesa em profundidade.

Estratégias Client-Side para Evitar Requisições Duplicadas em Formulários Web

Rastreie o Estado de Envio

Em vez de simplesmente desabilitar botões, rastreie se um formulário está sendo enviado no momento:

document.querySelectorAll('form').forEach(form => {
  form.addEventListener('submit', (e) => {
    if (form.dataset.submitting === 'true') {
      e.preventDefault();
      return;
    }
    form.dataset.submitting = 'true';
  });
});

Esta abordagem lida com cliques em botões e envios por teclado. Frameworks modernos frequentemente fornecem este estado automaticamente—o hook useFormStatus do React e padrões similares em outras bibliotecas expõem estados pendentes que você pode usar diretamente.

Forneça Feedback Visual Claro

Usuários reenviam quando não têm confiança de que sua ação foi registrada. Substitua incerteza por clareza:

• Desabilite o botão de envio e mostre um indicador de carregamento
• Altere o texto do botão para “Enviando…” ou exiba um spinner
• Considere desabilitar o formulário inteiro para prevenir modificações nos campos

form[data-submitting="true"] button[type="submit"] {
  opacity: 0.6;
  cursor: not-allowed;
  pointer-events: none;
}

Trate Erros com Elegância

Um erro comum: desabilitar o botão permanentemente após uma falha no envio. Sempre reabilite os controles do formulário quando erros ocorrerem para que os usuários possam tentar novamente:

async function handleSubmit(form) {
  form.dataset.submitting = 'true';
  try {
    await submitForm(form);
  } catch (error) {
    form.dataset.submitting = 'false'; // Permite nova tentativa
    showError(error.message);
  }
}

Aplique Debounce em Envios Rápidos

Para formulários usando validação assíncrona ou processamento complexo, debouncing previne envios em rajada de usuários impacientes ou teclas Enter mantidas pressionadas:

let submitTimeout;
form.addEventListener('submit', (e) => {
  if (submitTimeout) {
    e.preventDefault();
    return;
  }
  submitTimeout = setTimeout(() => {
    submitTimeout = null;
  }, 2000);
});

Idempotência Server-Side: A Camada de Proteção Definitiva

Medidas client-side reduzem envios duplicados. Idempotência server-side elimina seu impacto.

Envio de Formulário Idempotente com Tokens

Gere um token único ao renderizar o formulário. Inclua-o como um campo oculto:

<input type="hidden" name="idempotency_key" value="abc123-unique-token">

No servidor, verifique se você já processou este token. Se sim, retorne a resposta em cache. Se não, processe a requisição e armazene o token.

Este padrão—às vezes chamado de deduplicação de requisições—garante que mesmo se requisições idênticas chegarem múltiplas vezes, apenas uma produz efeitos colaterais.

Por Que Isso Importa para Prevenir Requisições de API Duplicadas

Processadores de pagamento como Stripe exigem chaves de idempotência exatamente por este motivo. Falhas de rede, retentativas e timeouts podem fazer com que a mesma requisição chegue múltiplas vezes. Sem idempotência, você pode cobrar um cliente duas vezes.

O mesmo princípio se aplica a qualquer operação que altera estado: criar registros, enviar emails ou disparar workflows.

Juntando Tudo

Proteção efetiva camada estas estratégias:

1. Frontend: Rastreie estado, desabilite controles, mostre feedback
2. Frontend: Reabilite em erros, aplique debounce em envios rápidos
3. Backend: Valide tokens de idempotência, deduplique requisições
4. Backend: Retorne respostas consistentes para envios duplicados

Nenhuma técnica única é suficiente. Tratamento client-side melhora a UX, enquanto idempotência server-side garante correção.

Conclusão

Para prevenir envios duplos de formulários de forma confiável, combine feedback visual imediato com deduplicação de requisições server-side. Trate medidas client-side como melhorias de UX, não controles de segurança. Projete seus fluxos de envio assumindo que requisições chegarão múltiplas vezes—porque sob condições reais de rede, elas chegarão. Proteção em camadas não é opcional: é a única abordagem que se sustenta quando usuários, redes e casos extremos conspiram contra você.

Perguntas Frequentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.