Validação de formulários alinhada à API para impedir dados ruins na origem

Por que regras de validação desalinhadas causam falhas evitáveis

Dados incorretos geralmente não são dramáticos. São situações do dia a dia: um campo obrigatório deixado em branco, uma data digitada como “12/13/24” quando a API espera “2024-12-13”, um número de telefone com letras, ou uma opção de dropdown que mudou no backend mas não no formulário.

Quando o formulário aceita essas entradas e só a API as rejeita depois do envio, o usuário se sente enganado. Ele fez o trabalho, clicou no botão e recebeu um vago “Algo deu errado.” Às vezes o erro aparece longe do campo que causou o problema, forçando o usuário a adivinhar.

Regras desalinhadas deixam escapar alguns problemas previsíveis: campos obrigatórios vazios ou só com espaços, formatos errados (email, data, CEP), valores fora dos limites (texto muito longo, número pequeno demais, itens demais), enums desatualizados (nome de plano antigo ou função removida) e conflitos entre campos como data de término antes da data de início.

O custo soma rápido. Cada requisição falha pode significar um cadastro abandonado, um checkout perdido ou um registro meio criado que precisa de limpeza. Surgem tickets de suporte: “Não consigo criar uma conta”, quando o problema real é uma regra simples de formatação. Com o tempo, registros inconsistentes entram no banco e atrapalham relatórios e automações.

Validação de formulário alinhada à API é uma ideia simples: as mesmas regras rodam nos dois lugares. O formulário evita entradas óbvias e mostra feedback claro no nível do campo antes do envio. A API continua validando tudo (nunca confie apenas no navegador), mas na prática ela confirma o que o usuário já corrigiu.

Validação no cliente vs no servidor, em linguagem simples

Validação no cliente acontece no navegador enquanto alguém preenche um formulário. É o feedback rápido que pega erros óbvios cedo: campos obrigatórios faltando, um email que não parece um email, ou uma senha curta demais.

Validação no servidor acontece depois que o formulário é enviado e sua API recebe os dados. É o controlador final que protege seu banco de dados e seus usuários.

Por que você precisa dos dois

Regras no cliente servem para velocidade e clareza. Elas reduzem frustração porque as pessoas corrigem problemas na hora.

Regras no servidor servem para segurança e verdade. O servidor deve validar porque qualquer um pode contornar o navegador (scripts personalizados, requisições modificadas, versões antigas do app), o servidor vê o estado real (contas existentes, permissões, limites de taxa), e algumas checagens exigem dados confiáveis (propriedade, segurança, restrições de integridade).

Um equívoco comum é achar que a validação no cliente “impede dados ruins”. Ela ajuda, mas não garante. Só a API pode dar essa garantia.

O objetivo real: um manual de regras compartilhado

O que você quer é um manual de regras compartilhado: cliente e servidor aplicam os mesmos requisitos, então o usuário recebe as mesmas respostas em ambos os lugares.

Na prática, isso significa escolher uma única fonte de verdade para as regras (frequentemente um schema da API ou a camada de validação do servidor) e fazer o cliente refletir isso. Se o servidor exige senha com 12+ caracteres e bloqueia senhas comuns, o formulário deve indicar “12+ caracteres” desde o início. A verificação de “senha comum” pode ser um aviso mais suave, mas o requisito rígido precisa ser consistente.

O que validar e onde

Algumas checagens pertencem ao navegador porque ajudam a pessoa a terminar o formulário. Outras devem acontecer no servidor porque só ele sabe o que é verdade agora. O objetivo é consistência: o usuário deve aprender sobre problemas antes do envio, e quando o servidor rejeitar algo, o motivo deve bater com o que a interface já ensina.

Comece pelas regras de formato do campo. Esses básicos devem coincidir em todo lugar:

• Se um campo é obrigatório
• O tipo esperado (texto, número, data)
• O formato que a API espera

Se sua API espera um número e o formulário envia texto, a requisição falha mesmo que a UI pareça correta.

As restrições também devem ser compartilhadas: tamanho mínimo e máximo, valores permitidos (como uma lista de códigos de país) e padrões simples (por exemplo, “deve conter um @”). A validação no cliente dá feedback rápido; a validação no servidor confirma.

Regras entre campos exigem cuidado extra porque envolvem mais de um input. Se o usuário pode corrigir comparando dois campos na mesma tela, valide no formulário e revalide no servidor. Dois exemplos comuns: “senha e confirmar senha devem coincidir” e “data de início deve ser anterior à data de término”.

Algumas regras são exclusivas do backend porque o cliente não pode verificá-las com segurança. Isso inclui checagens de unicidade (o email já está registrado?), permissões (esse usuário pode definir esse valor?), limites de taxa, qualquer coisa que dependa do estado atual do banco, e regras de segurança (rejeitar campos ou valores inesperados).

Um formulário de cadastro pode validar o formato de email localmente, mas só a API pode confirmar se o email já está em uso.

Como as regras saem de sincronia

A deriva de validação costuma começar com boas intenções: alguém corrige um bug rápido, envia, e segue adiante. Uma semana depois, outra pessoa adiciona uma regra “temporária” em outro arquivo. Depois de algumas iterações, UI e API discordam e os usuários recebem falhas confusas.

Copiar e colar validação é uma causa comum. Um time constrói três formulários que coletam o mesmo campo (email, telefone, nome da empresa), mas cada formulário acaba com regras ligeiramente diferentes. A API pode impor um formato mais rígido enquanto um formulário só checa “não está vazio”.

Mudanças de versão são outra fonte. O backend atualiza uma regra (senha de 8 passa a 12 caracteres, ou um campo passa a ser obrigatório) e a UI continua na suposição antiga. Usuários passam na validação do cliente e ainda recebem erro do servidor.

Diferenças de ambiente podem esconder a deriva até que ela cause problema. Staging pode ter configurações mais relaxadas, flags diferentes ou um provedor de autenticação distinto. Tudo parece ok em testes, e a produção rejeita entradas reais porque as regras são mais rígidas.

Código gerado por IA pode piorar isso ao duplicar validação em vários componentes, misturar bibliotecas ou inventar regex que não batem com a API. É comum ver o mesmo campo validado de três formas diferentes em um app.

Você provavelmente tem deriva se notar padrões como:

• Usuários reportam “diz OK, depois falha” ao apertarem Enviar
• O mesmo campo se comporta diferente em páginas distintas
• Erros aparecem como “Algo deu errado” genérico
• Correções são feitas na UI sem atualizar o contrato da API (ou vice-versa)

Passo a passo: faça da API a fonte de verdade

Se usuários conseguem preencher um formulário que sua API rejeitará, você acaba com requisições desperdiçadas e falhas confusas. O conserto é direto: trate o contrato da API como a fonte de verdade e faça a UI espelhar isso.

Comece escrevendo o contrato para o endpoint que você chama. Para cada campo, registre:

• Tipo
• Obrigatório vs opcional
• Intervalos e limites permitidos
• Formatos (email, UUID, data)
• Restrições como comprimento máximo ou valores permitidos

Depois divida as regras em dois grupos. Primeiro, regras que o navegador pode checar instantaneamente (obrigatório, formato, tamanho). Segundo, regras que só o servidor pode conhecer (unicidade, permissões, limites de taxa, “senha atual confere”). Isso mantém o feedback rápido sem fingir que o cliente garante a realidade do servidor.

Um caminho prático que funciona ao longo do tempo:

1. Escolha um formato de schema que você possa reaproveitar (OpenAPI, JSON Schema ou uma biblioteca de validação compartilhada).
2. Coloque as regras de requisição e resposta do endpoint nesse schema, incluindo restrições.
3. Gere ou reutilize validadores de cliente a partir do schema para que as regras da UI não sejam copiadas à mão.
4. Valide no servidor usando o mesmo schema (ou regras equivalentes) antes da lógica de negócio.
5. Padronize códigos de erro e templates de mensagem para que o mesmo problema pareça o mesmo em todo lugar.

Também torne os erros previsíveis. Use códigos de erro estáveis (como email_taken ou password_too_short) e deixe cliente e servidor mapearem isso para texto claro.

Projetando mensagens de erro que o usuário pode agir sobre

As pessoas consertam problemas mais rápido quando a mensagem diz exatamente o que mudar. O objetivo é consistência: a mesma regra deve gerar a mesma mensagem, seja detectada no navegador ou retornada pela API.

Escreva uma sentença clara por regra e mantenha-a estável. Se a regra mudar, atualize a mensagem ao mesmo tempo. “A senha deve ter pelo menos 12 caracteres” é acionável. “Entrada inválida” não é.

Onde mostrar os erros importa tanto quanto o que você diz. Coloque a mensagem ao lado do campo que precisa de atenção. Acrescente um resumo no topo apenas quando ajudar a encontrar campos perdidos, especialmente em formulários longos.

Um padrão confiável para a maioria dos formulários é:

• Mensagem inline abaixo do campo (curta e específica)
• Estilo que destaca o input exato
• Um resumo no topo listando 1–3 problemas (sem duplicatas)
• Foco movendo-se para o primeiro erro após o envio

Erros do servidor precisam de cuidado especial. Mesmo com boas checagens no cliente, requisições falharão por motivos que o cliente não controla totalmente: sessões expiradas, condições de corrida, ou regras que a UI não conhecia. Quando a API responde com erros, mapeie-os de volta para os campos usando chaves consistentes e reutilize a mesma redação. Se um erro não estiver ligado a um campo específico, mostre-o como mensagem de nível de página.

Evite linguagem técnica para o usuário. Pessoas não devem ver “400 Bad Request” ou códigos brutos de validação. Traduza-os para linguagem simples como “Esse endereço de email já está em uso” ou “Por favor insira uma data válida”.

Regras entre campos e checagens assíncronas sem confundir o usuário

Algumas validações não são sobre um único campo, mas sobre como campos interagem. Se você validar apenas cada input isoladamente, usuários ainda podem submeter dados que falham no servidor e então recebem um erro que parece aleatório.

Validação entre campos cobre expectativas dos usuários: “data de término deve ser depois da data de início” ou “senha e confirmar senha devem coincidir.” Uma boa regra prática: se o usuário consegue consertar comparando campos na mesma tela, valide no formulário e explique isso ao lado dos campos.

Mantenha a mensagem ligada à correção. “Datas inválidas” é vago. “Data de término deve ser depois da data de início” diz exatamente o que mudar.

Checagens assíncronas: quando você precisa perguntar ao servidor

Algumas checagens dependem de dados reais ou de permissões e, portanto, exigem o servidor. Exemplos comuns: “email já usado”, “código de convite válido” ou “nome de usuário disponível”. Essas checagens ainda fazem parte de um sistema de validação alinhado, mas a UI precisa tratá-las com suavidade para não interromper a digitação.

Uma abordagem simples:

• Mostre um pequeno estado “Verificando...” depois que o usuário pausar ou sair do campo.
• Deixe o usuário continuar preenchendo o formulário enquanto a checagem roda.
• Se a checagem falhar, explique o que fazer em seguida (usar outro email, solicitar um novo convite).
• Se a checagem não puder ser executada (offline ou timeout), não finja que passou. Peça para tentar novamente no envio.

Quando validar: ao sair do campo (blur), no envio ou progressivamente

O timing importa. Validar a cada pressionar de tecla pode parecer que o formulário está discutindo com o usuário.

Um padrão simples que funciona para muitos times:

• Valide formato básico e tamanho mínimo enquanto o usuário digita.
• Valide regras entre campos quando o segundo campo for tocado (confirm password) ou no blur.
• Rode checagens assíncronas no blur ou após uma pausa curta, não a cada tecla.
• Refaça todas as validações no envio e mapeie erros do servidor de volta para os campos corretos.

Erros comuns que geram falhas ruidosas

Falhas ruidosas de validação parecem aleatórias para os usuários, mas geralmente vêm de poucos erros previsíveis. O tema principal é deriva: UI e API começam lentamente a impor regras diferentes.

Confiar apenas em checagens no cliente é uma armadilha clássica. Usuários podem contornar o navegador, ou sua API pode ser chamada por outro cliente. Quando o servidor vira o primeiro lugar onde a validação acontece, as pessoas só veem falhas depois de preencher o formulário.

Padrões que causam os momentos “por que isso falhou?” incluem:

• O mesmo campo tem regras diferentes em telas distintas (cadastro vs configurações).
• Regras com regex que bloqueiam entradas reais, como nomes com apóstrofos, caracteres não ingleses ou complementos de endereço.
• A API retorna um erro 400/500 genérico, então a UI não consegue destacar o campo que precisa ser corrigido.
• Regras de validação da API mudam, mas testes da UI e scripts de QA ainda esperam o comportamento antigo.
• Mensagens são escritas para desenvolvedores (“constraint violation”) em vez de usuários (“A senha deve ter pelo menos 12 caracteres.”)

Um exemplo simples: a UI aceita “Sam O’Neil” em um perfil, mas a API rejeita porque a regex do servidor só permite A–Z. O usuário vê “Requisição falhou” sem destaque de campo, tenta de novo e desiste.

Reduzir ruído costuma vir de alguns consertos focados: padronizar regras por campo entre telas, afrouxar padrões para corresponder à entrada do mundo real e retornar códigos de erro específicos por campo para que a UI coloque as mensagens exatamente onde os usuários precisam.

Checklist rápido para verificar alinhamento antes do lançamento

Antes de enviar, faça uma verificação rápida que confira o caminho completo: o que o usuário digita, o que a UI bloqueia, o que a API rejeita e qual mensagem o usuário vê.

Comece comparando requisitos da API com o formulário. Se a API diz que um campo é obrigatório, a UI deve marcá-lo claramente como obrigatório e prevenir um envio vazio. Se a UI exige algo que a API não exige, os usuários podem ficar travados sem motivo.

Use um conjunto pequeno e repetível de testes para cada campo:

• Verifique regras de obrigatório: todo campo obrigatório na API é obrigatório na UI, e campos opcionais são realmente opcionais.
• Tente três valores ruins por campo: muito curto, muito longo, formato errado.
• Rode uma regra entre campos de ponta a ponta: a mensagem do cliente e a do servidor devem dizer a mesma coisa.
• Confirme que a API retorna erros ao nível de campo, não apenas uma string genérica.
• Confirme que a UI trata erros de rede de forma diferente de erros de validação (um timeout não deve parecer “seu email é inválido”).

Uma dica prática: faça ao menos um teste real de envio com as ferramentas de desenvolvedor abertas. Se o servidor rejeitar algo que a UI aceitou, há deriva.

Um exemplo realista: um formulário de cadastro que continua falhando

Um time publica uma página de cadastro com quatro campos: email, senha, nome da empresa e código de convite. Tudo parece ok no navegador. Mas chegam tickets de suporte: “Fica dizendo que algo deu errado.”

A causa raiz é um desalinhamento. A UI checa que a senha tem pelo menos 8 caracteres. A API exige 12. Um usuário digita Sunshine1 (9 caracteres), o formulário mostra um ok visual, a requisição é enviada e a API rejeita com 400. O app transforma isso em um banner genérico no topo e o usuário não sabe o que corrigir.

Os sintomas são fáceis de identificar:

• Muitas requisições falhas logo após o envio
• Banners genéricos em vez de dicas por campo
• Usuários tentando de novo com os mesmos dados e travando

O conserto não é “adicionar mais verificações”. É tornar o contrato da API a fonte de verdade e gerar as regras do cliente a partir dele.

Um fluxo de reparo simples:

1. Decida a regra real (8 ou 12) com o time dono da API.
2. Atualize o contrato da API (por exemplo, um schema OpenAPI) para refletir essa regra.
3. Regere ou atualize a validação do cliente a partir do contrato.
4. Mapeie o erro da API para o campo de senha com uma mensagem clara como “A senha deve ter pelo menos 12 caracteres.”
5. Reteste o fluxo, incluindo uma senha curta e um código de convite inválido.

Depois disso, requisições ruins caem porque os usuários recebem feedback antes do envio. Se o código de convite precisa ser verificado no servidor, a UI ainda pode ajudar: valide o formato localmente (tamanho, caracteres permitidos) e mostre “Código de convite não encontrado” apenas depois da confirmação do servidor.

Próximos passos para manter a validação alinhada com o tempo

Escolha um formulário de alto tráfego e faça dele seu piloto de alinhamento. Prefira algo que costuma quebrar ou que impacte receita, como cadastro, checkout ou redefinição de senha. Traga as regras da API (tipos, campos obrigatórios, min/max, valores permitidos) para perto das regras do formulário e feche as lacunas até que as mesmas entradas passem ou falhem em ambos os lados.

Depois que um formulário funcionar sem problemas, repita a abordagem no próximo em vez de tentar arrumar tudo de uma vez. Pequenas vitórias são mais fáceis de verificar e reduzem tickets de suporte rapidamente.

Adicione uma revisão leve de contrato quando a API mudar

A deriva acontece quando a API evolui e a UI não. Adicione um passo ao processo de mudança: sempre que a forma de uma requisição ou resposta mudar, alguém verifica se as regras do formulário e as mensagens de erro ainda batem.

Mantenha a rotina curta:

• Observe quais entradas ficaram mais rígidas ou mais flexíveis.
• Atualize regras do servidor e do cliente no mesmo pull request.
• Confirme que as mensagens de erro mencionam os nomes de campo que o usuário vê no formulário.
• Rode um teste de entrada inválida de propósito (campo obrigatório vazio, string muito longa, formato inválido).

Se o código for bagunçado, comece com uma auditoria

Se seu app foi gerado por uma ferramenta de IA ou herdado de um protótipo, validação desalinhada é muitas vezes sintoma de problemas maiores: regras duplicadas em vários arquivos, fluxos de autenticação pela metade ou padrões inseguros como confiar em checagens apenas no cliente.

Se você precisa de uma revisão externa, FixMyMess (fixmymess.ai) foca em diagnosticar e reparar apps gerados por IA, incluindo reconectar validação cliente/servidor, consertar autenticação quebrada e endurecer questões de segurança que aparecem quando protótipos enfrentam tráfego real.