Validação na API é uma decisão de arquitetura antes de ser uma decisão técnica. Cada verificação tem custo, tempo de resposta e grau de certeza diferentes, e colocá-la no lugar errado produz sistemas lentos, mensagens confusas ou confiança injustificada. Este texto organiza as camadas, discute quando vale consultar um cadastro externo e mostra como responder a uma recusa sem transformar o serviço em um oráculo.
Por que conferir nos dois lados?
A conferência no cliente existe para dar retorno imediato a quem digita: uma sequência com dígito verificador que não fecha pode ser sinalizada antes de qualquer requisição. Isso reduz tráfego, evita esperas inúteis e melhora a experiência sem custo relevante.
A conferência no servidor existe por outro motivo: ela é a única em que se pode confiar. Qualquer verificação que roda no cliente pode ser contornada, desligada ou simplesmente ignorada por um consumidor que fale diretamente com a sua interface. Se uma regra de negócio depende da consistência dos dados, ela precisa ser reaplicada no servidor, mesmo que pareça redundante.
Daí a formulação útil: o cliente confere por conveniência, o servidor confere por obrigação. Duplicar a regra é aceitável desde que a duplicação seja intencional e as duas versões sejam alimentadas pela mesma fonte de dados.
O que o cliente pode decidir sozinho
Tudo o que depende apenas da sequência enviada pode ficar no cliente: limpeza de separadores, comparação de comprimento, conjunto de caracteres e o cálculo do dígito verificador. É trabalho local, determinístico e rápido, que não precisa de rede nem de estado.
Faz sentido, inclusive, que o cliente seja responsável pela experiência da digitação — normalizar enquanto a pessoa digita, aplicar máscara de exibição, indicar completude do campo. Nada disso é conferência de negócio, e sim higiene de entrada.
O que o cliente não pode decidir é qualquer coisa que dependa de informação que ele não tem: se o número existe, se está em situação regular, se já foi usado antes. Essas perguntas dependem de estado do servidor ou de terceiros, e delegá-las ao cliente produz uma falsa sensação de verificação.
Quando é preciso consultar um registro externo
A consulta a um cadastro externo é uma camada diferente, e vale tratá-la como exceção, não como padrão. Ela custa tempo, depende de disponibilidade de terceiros e, muitas vezes, tem limite de chamadas.
| Camada | Onde roda | Custo típico | O que devolve |
|---|---|---|---|
| Estrutura e dígito verificador | Cliente e servidor | Baixo, local | Confere ou não confere |
| Regra específica de esquema | Servidor | Baixo, local | Confere, apenas formato ou sem regra |
| Existência em cadastro | Consulta externa | Alto e sujeito a falha | O que o registro consultado informar |
A ordem de execução deve seguir essa tabela, de cima para baixo. Conferir o dígito antes de consultar o cadastro elimina chamadas inúteis: por que gastar uma consulta para um número que não fecha aritmeticamente?
Há também um argumento de projeto: a existência de um registro é uma informação que envelhece. Ela pode mudar entre o momento da conferência e o momento do uso, o que a torna inadequada para ser tratada como invariante do sistema. Quando a resposta externa é necessária, ela deve vir acompanhada do instante em que foi obtida.
Como responder sem revelar demais?
A mensagem de erro é uma superfície de exposição. Se a API diferencia com clareza excessiva entre motivos, quem consulta o serviço passa a usá-lo como oráculo: descobre, por tentativa, quais números existem, quais faixas estão ativas e o que muda entre elas.
O equilíbrio costuma estar em separar o que é útil para corrigir de boa-fé do que só interessa a quem está sondando. Falhas de formato podem ser detalhadas — a sequência tem comprimento inesperado, o dígito verificador não confere —, porque não revelam nada sobre registros e ajudam quem digitou errado.
Consultas a cadastro são outra história. A resposta pública deve ser genérica o suficiente para não permitir enumeração, e o detalhe deve ficar no registro interno e no log. É comum que a orientação ao usuário final e o motivo técnico divirjam de propósito, e isso precisa estar previsto no desenho, não improvisado na hora.
Vale lembrar o limite de qualquer uma dessas camadas: consistência de formato não é existência, como discutido em números sem dígito verificador.
Limites, tempos de espera e repetição de chamadas
Quando a conferência depende de terceiros, três fatores passam a dominar o comportamento do serviço.
O primeiro é o limite de chamadas. Um endpoint que consulta um cadastro externo a cada digitação esgota a cota em poucos minutos de uso real. A correção usual é separar a conferência local, que roda a cada tecla, da consulta remota, que roda sob demanda explícita.
O segundo é o tempo de espera. Uma dependência externa lenta não pode arrastar o tempo de resposta do seu serviço. Definir um limite interno, menor que o limite do chamador, e devolver um resultado explícito de indisponibilidade é melhor do que manter a conexão aberta até o cliente desistir.
O terceiro é a repetição. Nem toda falha deve ser repetida: um erro de formato na requisição vai falhar de novo, quantas vezes for tentada. A repetição faz sentido para falhas transitórias, com espaçamento crescente entre as tentativas, e precisa de um limite claro para não virar tempestade.
Em todos os três casos, o resultado precisa distinguir indisponibilidade de reprovação. Um cadastro fora do ar não torna o número inválido.
Para quem desenvolve: um contrato de erro previsível
A maior parte da manutenção vem de respostas ambíguas. Um contrato de erro previsível resolve isso com pouco esforço.
- Defina um conjunto fechado de resultados, incluindo os de formato: confere, não confere, apenas formato, sem regra e indisponível.
- Devolva sempre o esquema aplicado e a versão da regra, para que um resultado possa ser explicado meses depois.
- Separe o motivo técnico, destinado ao log, da mensagem exibida a quem consome o serviço.
- Nunca converta falha de dependência externa em reprovação do dado recebido.
- Registre o instante da consulta quando a resposta vier de um cadastro, já que ela envelhece.
- Trate a conferência local como filtro barato antes de qualquer chamada remota.
Um ponto de atenção específico para volumes altos: quando o mesmo número aparece muitas vezes na mesma janela de tempo, o cache interno reduz chamadas repetidas sem alterar o resultado observado. O fluxo de conferência em massa, descrito em validação em lote, compartilha as mesmas decisões de camada, apenas com outra ordem de grandeza.
As respostas de exemplo neste texto são ilustrativas. Uma resposta de formato aceitável atesta apenas a consistência da sequência enviada, e nunca a existência do número em qualquer cadastro.
Próximos passos
Se o seu cenário envolve arquivos com muitas linhas, leia o fluxo de validação em lote e compare as etapas com as camadas descritas aqui. Para o caso em que não existe regra publicada, volte ao texto sobre números sem dígito verificador. E para inspecionar o resultado de uma sequência antes de integrá-la, use a ferramenta de validação de número.