Gerador de CEP por estado

O Código de Endereçamento Postal é lido da esquerda para a direita, do mais geral para o mais específico. Os cinco primeiros dígitos formam o prefixo, que localiza a área; os três últimos são o sufixo, que aponta o logradouro, um trecho de logradouro ou uma unidade de distribuição — caixas postais e grandes usuários entram aqui. Não existe dígito verificador em lugar nenhum: os oito dígitos são todos informação de endereço.

01310-100, dígito a dígito

O CEP de um trecho da Avenida Paulista, em São Paulo, se decompõe assim:

• 0 — região. É o dígito que divide o país em dez regiões postais; a região 0 cobre a capital paulista e o entorno.
• 1 — sub-região. Recorta a região em blocos menores.
• 3 — setor.
• 1 — subsetor.
• 0 — divisor de subsetor, o último dígito do prefixo e o mais fino dos cinco.
• 100 — sufixo, os três dígitos que identificam o logradouro ou o trecho atendido.

Andar alguns quarteirões pela mesma avenida costuma mexer só no sufixo. Atravessar para outro bairro muda o setor ou o subsetor. Mudar de estado muda o primeiro dígito, ou os dois primeiros. É essa hierarquia que permite descobrir a UF de um CEP comparando o número com intervalos, sem consultar base alguma.

As dez regiões postais

A numeração começa em São Paulo — região 0 para a capital e o entorno, região 1 para o interior do estado — e segue pelo restante do país até terminar em 9, o Rio Grande do Sul. Como a divisão é geográfica e contínua, cada UF ocupa um ou dois intervalos fechados, listados na tabela mais abaixo. Três estados aparecem partidos em dois intervalos porque um vizinho corta a faixa: Distrito Federal e Goiás se intercalam duas vezes, e o bloco de Roraima separa em dois o do Amazonas. O mapa completo das regiões está no guia como o CEP é estruturado.

Sem dígito verificador, sobra a faixa

CPF, CNPJ, PIS e RENAVAM carregam um dígito calculado que denuncia a troca de um algarismo. O CEP não. Digitar 01310-100 como 01810-100 produz outro CEP plausível, dentro da mesma faixa de São Paulo, e nenhuma verificação local percebe o erro. Para os documentos que têm essa proteção, a conta está no guia de módulo 11; para o CEP, o que dá para checar offline é formato mais faixa.

Nem todo CEP aponta para uma rua. Municípios pequenos costumam ter um único código atendendo o território inteiro, o CEP geral, reconhecível pelo sufixo 000. Nas cidades grandes acontece o oposto: o mesmo bairro tem dezenas de CEPs, um por logradouro e às vezes um por trecho, além dos códigos reservados a caixas postais e a grandes usuários — um órgão público ou uma empresa que recebe correspondência em volume ganha CEP próprio. Esse último tipo identifica o destinatário, não a via.

A diferença aparece no primeiro formulário que preenche endereço a partir do CEP. Com um CEP geral, a consulta devolve município e UF, mas logradouro e bairro voltam em branco — e a tela precisa deixar o usuário digitar a rua em vez de travar ou exibir erro. Uma massa de teste de endereços sem pelo menos um CEP geral não exercita esse caminho, que é justamente o que quebra em produção.

Os números sorteados aqui respeitam a faixa da UF, mas não distinguem entre os tipos: pelo número não há como saber se ele seria um CEP geral, de logradouro ou de grande usuário. Para montar o endereço completo em volta dele, com estado e cidade coerentes, use o gerador de pessoas.

Sem sair da sua aplicação dá para checar três coisas. Primeira: se restaram oito dígitos depois de remover a máscara. Segunda: se o número cai em algum intervalo conhecido — fora deles, o CEP não pertence a UF nenhuma. Terceira, a mais útil e a mais esquecida: se a UF daquele intervalo bate com o estado selecionado no formulário. É essa terceira checagem que pega o cadastro com CEP da faixa de Pernambuco e estado Paraná, um erro que a consulta de logradouro sozinha não denuncia.

Um serviço externo responde outra pergunta: se aquele CEP existe e a que logradouro corresponde. Pergunta legítima em produção, péssima dependência dentro da suíte de testes. A partir do momento em que um teste de unidade faz uma requisição HTTP, ele depende de rede, de um serviço de terceiro estar no ar e do limite de requisições dele. O que passava ontem falha hoje por timeout, o tempo total cresce junto com o número de casos e o resultado deixa de ser determinístico, porque a base de CEPs muda com o tempo.

O arranjo que costuma sobreviver: validar formato e faixa localmente, com dados fixos; isolar a chamada externa atrás de uma interface e usar um duplo de teste nos testes de unidade e de componente; e manter um punhado de testes de integração que realmente batem no serviço, rodando fora da suíte principal, onde uma falha de rede não derruba o build. O mesmo raciocínio vale para montar massa de dados de teste e é o motivo de preferir dados fictícios a dados reais em ambiente de desenvolvimento.