Validador de Formato de CEP

O CEP: codigo postal brasileiro de 8 digitos e sua estrutura geografica

O CEP (Codigo de Enderecamento Postal) e o codigo postal brasileiro definido pelos Correios. Todo endereco no Brasil tem um. O formato e 8 digitos numericos, exibidos convencionalmente com um hifen entre a 5a e a 6a posicao: XXXXX-XXX. Os Correios estimam aproximadamente um milhao de CEPs validos em circulacao, com adicoes continuas a medida que novos bairros, ruas e grandes edificios recebem seu codigo proprio.

Diferente do ZIP+4 norte-americano (que codifica rotas de entrega) ou do postcode britanico (que mistura letras e numeros), o CEP e puramente numerico e segue estrutura hierarquica estrita. O primeiro digito identifica uma macro-regiao brasileira, e da esquerda para a direita o numero estreita de regiao para sub-regiao, setor, sub-setor e unidade de entrega. So o primeiro digito ja revela a geografia aproximada do endereco.

Mapa do primeiro digito: as 10 regioes Correios

• 0 — Cidade de Sao Paulo (capital)
• 1 — Interior do estado de Sao Paulo
• 2 — Rio de Janeiro e Espirito Santo
• 3 — Minas Gerais
• 4 — Bahia e Sergipe
• 5 — Pernambuco, Alagoas, Paraiba, Rio Grande do Norte
• 6 — Ceara, Piaui, Maranhao, Para, Amazonas, Acre, Amapa, Roraima, Rondonia (Norte e parte do Nordeste)
• 7 — Distrito Federal, Goias, Tocantins, Mato Grosso, Mato Grosso do Sul
• 8 — Parana e Santa Catarina
• 9 — Rio Grande do Sul

A afirmacao popular "0 = Sao Paulo, 9 = Rio Grande do Sul" e verdadeira no nivel macro. Um validador puramente de formato (como este) consegue verificar o formato de 8 digitos mas nao garante que o CEP exista — para isso e preciso consulta semantica via DNE dos Correios ou via uma das APIs publicas gratuitas descritas abaixo.

Validacao por regex vs lookup semantico

Validador de formato olha a forma, nao a existencia. A regex canonica e:

// Aceita "01310-100" e "01310100"
const re = /^\d{5}-?\d{3}$/

// Normaliza antes de armazenar
const normalizado = cep.replace(/\D/g, '')  // remove nao-digitos
const mascarado   = normalizado.replace(/(\d{5})(\d{3})/, '$1-$2')

O hifen e opcional — a maioria dos back-ends brasileiros aceita as duas formas e armazena os 8 digitos sem mascara. Mascaras de front-end exibem o hifen por legibilidade. Esta ferramenta aceita o input nas duas formas e informa se a estrutura e valida; nao confirma (e nem poderia) que o CEP corresponde a endereco real.

Para validacao semantica — esse CEP existe de fato? — voce precisa consultar uma destas APIs publicas:

• ViaCEP (viacep.com.br/ws/{cep}/json/) — o endpoint gratuito mais popular. Sem autenticacao. Limite pratico de cerca de 10.000 requisicoes por dia por IP. Retorna logradouro, bairro, localidade e UF.
• BrasilAPI (brasilapi.com.br/api/cep/v2/{cep}) — alternativa mantida pela comunidade, a v2 inclui latitude/longitude quando disponivel.
• AwesomeAPI (cep.awesomeapi.com.br/json/{cep}) — fallback adicional caso as duas anteriores falhem.
• DNE dos Correios — o Diretorio Nacional de Enderecos oficial. Produto pago; obrigatorio para integracoes de alto volume e a unica fonte garantidamente atualizada.

CEPs especiais: -000, -899, -900 e como cidades alocam codigos

Sufixos do CEP codificam a granularidade do endereco. Cidades pequenas tipicamente tem um unico CEP terminado em -000 cobrindo toda a area urbana. Cidades grandes alocam um CEP por logradouro, as vezes um CEP por face de quadra em avenidas longas. O Brasil tem assim CEPs em tres escalas muito diferentes convivendo na mesma base.

Sufixos -899 e -900 sao reservados pelos Correios para Grandes Usuarios — orgaos publicos, grandes empresas, universidades. Um CEP como 70150-900 (Palacio do Planalto em Brasilia) entrega correspondencia a uma instituicao especifica, nao a uma rua. Tratar esses casos como "CEP de endereco" num fluxo de e-commerce comum quebra calculadoras de frete porque eles aceitam correspondencia mas nem sempre entrega domiciliar.

CEPs terminados em -970 historicamente pertencem a agencias dos Correios (caixas postais e unidades de atendimento). Muitos ainda estao ativos e se comportam mais como caixas postais que enderecos residenciais.

Casos de uso: auto-fill em checkout e calculo de frete

O padrao mais comum em front-ends brasileiros e o checkout com CEP primeiro: o usuario digita o CEP, a pagina consulta assincronamente o ViaCEP ou a BrasilAPI e preenche logradouro, bairro, cidade e UF. Magazine Luiza, Mercado Livre, Americanas e a maioria das lojas Vtex seguem esse padrao. O fluxo de auto-fill combina:

• Validacao de formato (o que esta ferramenta faz) antes de disparar a requisicao HTTP.
• Lookup semantico (ViaCEP ou BrasilAPI) para buscar o endereco.
• Calculo de frete (Correios SIGEP, Frete Rapido, Melhor Envio) usando CEP e peso para estimar custo e prazo.
• Risk score cruzando com o BIN do cartao para detectar fraude quando CEP e UF de cobranca discordam.

Anti-pattern e confiar apenas em validacao por regex e pular o lookup semantico. Usuarios digitam rotineiramente o CEP de outra rua ou um CEP que nao existe. Sem confirmacao via ViaCEP, o e-commerce cota frete para lugar nenhum e so descobre o erro quando a transportadora recusa o AWB.

FAQ

O hifen e obrigatorio?

Nao. Tanto 01310-100 quanto 01310100 sao validos. O hifen e apenas apresentacao. A maioria dos back-ends armazena os 8 digitos sem hifen.

O lookup do ViaCEP e gratuito?

Sim, gratuito e sem autenticacao. O limite pratico e de cerca de 10.000 requisicoes por dia por IP. Para volumes maiores, use a BrasilAPI como fallback ou contrate o DNE dos Correios.

Todo endereco brasileiro tem CEP proprio?

Nao. Cidades pequenas compartilham um unico CEP para a cidade inteira (sufixo -000). Cidades grandes chegam ate granularidade por rua ou por face de quadra. Sufixos especiais (-899, -900, -970) sinalizam CEPs institucionais.

Um mesmo CEP pode pertencer a duas cidades?

Nao. Cada CEP esta unicamente atrelado a um municipio e UF. Se uma cidade e dividida ou emancipada, os Correios reemitem os codigos.

Por que o valor de teste 01310-100 resolve para Avenida Paulista?

Porque 01310-100 e o CEP canonico do MASP e do trecho central da Avenida Paulista em Sao Paulo. O 0 inicial marca Sao Paulo capital; os quatro digitos seguintes afunilam para o bairro do Bela Vista.