Consulta de CEP no Delphi: compare a leitura direta com CSCoder.JSON

Documentação, instalação e limites de CSCoder.CEP e ComJSON

Experimentar o contrato no navegador

Um cadastro pede um CEP e preenche parte do endereço. Parece uma integração pequena, mas envolve perguntas diferentes: o formato informado é válido? O serviço respondeu? O CEP existe? A resposta tem os campos que sua tela espera?

Vamos comparar duas units de consulta, com a mesma interface pública e os mesmos critérios. CSCoder.CEP usa System.JSON diretamente. CSCoder.CEP.ComJSON usa também CSCoder.JSON para ler campos com verificação de tipo. Você pode escolher uma abordagem sem adotar todas as units do blog.

O serviço e os resultados da consulta

O ViaCEP oferece consulta gratuita por CEP. A URL recebe oito números; um formato inválido pode produzir HTTP 400. Para um CEP inexistente, o serviço devolve o campo erro. O provedor alerta que uso massivo pode bloquear o acesso; estes exemplos não fazem varredura de bases nem consultas em lote.

As units aceitam oito números ou a máscara completa 00000-000, removendo apenas espaços nas extremidades. A validação local impede que letras ou separadores inesperados entrem na URL. Um CEP com oito números ainda pode não existir.

O resultado reúne Status, Endereco, StatusHTTP e Mensagem. Endereço só é utilizável com scEncontrado; nos demais estados, seus campos ficam vazios. Timeout não vira “CEP inexistente”, e um HTML de erro não vira um cadastro vazio aparentemente válido.

Versão independente: System.JSON diretamente

Na unit CSCoder.CEP, a leitura de um campo textual está implementada assim:

function LerString(const Obj: TJSONObject; const Campo: string;
  out Valor: string): Boolean;
var V: TJSONValue;
begin
  Valor := '';
  V := Obj.GetValue(Campo);
  Result := V is TJSONString;
  if Result then Valor := TJSONString(V).Value;
end;

É uma função interna: a interpretação já confirmou que a raiz é um objeto. Essa versão não depende de CSCoder.JSON. Para uma integração isolada, manter a regra de leitura ao lado do contrato do serviço pode ser uma escolha simples.

Ela não é uma versão propositalmente frágil para favorecer o helper. As mesmas verificações existem nas duas implementações. O custo da versão independente é repetir uma decisão semelhante se outras integrações precisarem das mesmas leituras.

Versão com CSCoder.JSON

A outra unit utiliza a função da biblioteca:

if not TentarLerString(Obj, 'localidade',
  Result.Endereco.Localidade) then Exit;

O código está dentro de InterpretarRespostaCEP, após confirmar a raiz Obj como TJSONObject. A verificação genérica do tipo sai da unit de CEP; a regra específica permanece: localidade não pode estar vazia, o CEP devolvido deve corresponder ao consultado e UF deve ter duas letras ASCII maiúsculas.

O helper não conhece ViaCEP. Isso permite reutilizá-lo em outra API sem levar junto URL, campos de endereço ou mensagens dessa consulta.

Um detalhe real: o campo erro pode ser texto

Nas respostas HTTPS capturadas para esta comparação, o CEP inexistente 99999999 devolveu {"erro":"true"}. A documentação também descreve o valor verdadeiro para esse campo. As units aceitam booleano JSON ou as strings exatas "true" e "false" nesse campo específico.

Não ampliamos TentarLerBoolean para converter qualquer string. A compatibilidade pertence ao contrato do ViaCEP e fica no consumidor. Texto arbitrário, número ou null em erro continua sendo resposta inválida. Esse caso mostra uma vantagem de separar tipo genérico e regra da integração.

O mesmo exemplo nas duas abordagens

Este é o projeto independente. No outro projeto, o uses utiliza CSCoder.CEP.ComJSON; o ZIP já inclui CSCoder.JSON.

program ExemploCEP;
{$APPTYPE CONSOLE}
uses System.SysUtils, CSCoder.CEP;
var R: TResultadoCEP; CEP: string;
begin
  if ParamCount > 0 then CEP := ParamStr(1) else CEP := '01001000';
  R := ConsultarCEP(CEP);
  Writeln(R.Mensagem);
  if R.Status = scEncontrado then
    Writeln(R.Endereco.CEP, ' | ', R.Endereco.Logradouro, ' | ',
      R.Endereco.Localidade, '/', R.Endereco.UF)
  else ExitCode := 1;
end.

Se for usar ambas as units no mesmo programa, qualifique os tipos, como CSCoder.CEP.TResultadoCEP: cada unit independente declara seu próprio record e sua própria enumeração. Igualdade do contrato não torna esses tipos automaticamente intercambiáveis.

Campos essenciais são CEP, localidade e UF. Logradouro, complemento, bairro, IBGE e DDD podem estar ausentes; nesse caso viram texto vazio. Se estiverem presentes com tipo incorreto ou null, a resposta é rejeitada. Um CEP geral pode não trazer um logradouro específico: não confunda isso com falha.

Rede e interface exigem cuidado separado

ConsultarCEP é síncrona. Num console isso é simples; numa tela VCL, FMX ou UniGUI, defina como executar a operação sem bloquear a interação e sem acessar uma tela destruída.

As units configuram quatro segundos para conexão e oito para resposta no THTTPClient. Esses parâmetros não são uma garantia de duração total da operação. Não há repetição automática, cache nem cancelamento por parte da unit. Um projeto que precisa desses recursos deve desenhá-los fora da leitura JSON.

A rotina rejeita corpos com mais de 65.536 caracteres depois do recebimento. Isso não limita o download em andamento nem substitui uma política de transporte para respostas muito grandes. HTTPS mantém a validação do certificado do sistema; não desative essa verificação para fazer uma consulta passar.

O que foi verificado

As três units e os projetos compilaram com DCC32 37.0, build 37.0.59082.6021. Cada variante de CEP passou pelos mesmos 54 testes sem rede. O teste comparativo executou 127 verificações offline e mais cinco com respostas reais capturadas por HTTPS, confirmando a interpretação equivalente das duas variantes.

A captura HTTPS funcionou. A chamada direta pelo THTTPClient neste ambiente Windows retornou o erro WinHTTP 12185 relacionado a credenciais de certificado de cliente, que foi convertido em scFalhaComunicacao. Portanto, esses resultados validam a compilação e a interpretação; não comprovam sucesso da consulta ponta a ponta nesse ambiente. O relatório nos ZIPs detalha os testes e permite reproduzi-los, mantendo validação HTTPS ativa.

Baixe a abordagem que faz sentido para você

• Exemplo independente: CSCoder.CEP + console + testes.
• Exemplo com helper: CSCoder.CEP.ComJSON + CSCoder.JSON + console + testes.
• Teste comparativo das duas versões e respostas capturadas.
• Unit independente avulsa e helper JSON avulso.

Todos os pacotes de código usam MIT, com autoria de Claudio Santos (CS Coder). Ler a licença.

Escolha a versão independente quando a integração é pequena e você quer poucos arquivos. Considere o helper quando leituras parecidas aparecem em várias APIs. Nenhuma escolha substitui definir o contrato, tratar falhas e testar o comportamento real do serviço.

Continue em CSCoder.JSON: leitura de campos com tipos explícitos para conhecer as regras do helper; ou em HTTP e JSON: receber uma resposta não é validar um contrato para separar transporte e interpretação.

Compare as fronteiras, mantendo o resultado

Entrada → normalização → transporte → HTTP → sintaxe JSON → contrato → resultado → tela.

1. Extraia os pacotes em pastas diferentes e compare parsers.
2. Use InterpretarRespostaCEP com corpos fixos e mesmos status nas duas variantes.
3. Só depois conecte ConsultarCEP fora da thread visual.

Contrato verificado no relatório anterior; consulta ponta a ponta com THTTPClient pendente: WinHTTP 12185. HTTPS por outro transporte não comprova o cliente Delphi. Laboratório HTTP offline.

Abrir projeto de exemplo ↗