Validador de Formato de CEP

O CEP: código postal brasileiro de 8 dígitos e sua estrutura geografica

O CEP (Código de Enderecamento Postal) e o código postal brasileiro definido pelos Correios. Todo endereço no Brasil tem um. O formato e 8 dígitos numéricos, exibidos convencionalmente com um hífen entre a 5a e a 6a posição: XXXXX-XXX. Os Correios estimam aproximadamente um milhão de CEPs válidos em circulação, com adicoes continuas a medida que novos bairros, ruas e grandes edificios recebem seu código próprio.

Diferente do ZIP+4 norte-americano (que codifica rotas de entrega) ou do postcode britanico (que mistura letras e números), o CEP e puramente numérico e segue estrutura hierarquica estrita. O primeiro dígito identifica uma macro-região brasileira, e da esquerda para a direita o número estreita de região para sub-região, setor, sub-setor e unidade de entrega. So o primeiro dígito ja revela a geografia aproximada do endereço.

Mapa do primeiro dígito: as 10 regiões Correios

• 0 — Cidade de São Paulo (capital)
• 1 — Interior do estado de São Paulo
• 2 — Rio de Janeiro e Espírito 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 = São Paulo, 9 = Rio Grande do Sul" e verdadeira no nível macro. Um validador puramente de formato (como este) consegue verificar o formato de 8 dígitos mas não garante que o CEP exista — para isso e preciso consulta semântica via DNE dos Correios ou via uma das APIs publicas gratuitas descritas abaixo.

Validação por regex vs lookup semantico

Validador de formato olha a forma, não a existência. A regex canônica 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 hífen e opcional — a maioria dos back-ends brasileiros aceita as duas formas e armazena os 8 dígitos sem mascara. Mascaras de front-end exibem o hífen por legibilidade. Esta ferramenta aceita o input nas duas formas e informa se a estrutura e valida; não confirma (e nem poderia) que o CEP corresponde a endereço real.

Para validação semântica — esse CEP existe de fato? — você precisa consultar uma destas APIs publicas:

• ViaCEP (viacep.com.br/ws/{cep}/json/) — o endpoint gratuito mais popular. Sem autenticação. Limite prático de cerca de 10.000 requisições 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 disponível.
• AwesomeAPI (cep.awesomeapi.com.br/json/{cep}) — fallback adicional caso as duas anteriores falhem.
• DNE dos Correios — o Diretorio Nacional de Endereços oficial. Produto pago; obrigatório para integrações de alto volume e a única fonte garantidamente atualizada.

CEPs especiais: -000, -899, -900 e como cidades alocam códigos

Sufixos do CEP codificam a granularidade do endereço. Cidades pequenas tipicamente tem um único CEP terminado em -000 cobrindo toda a área 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 três escalas muito diferentes convivendo na mesma base.

Sufixos -899 e -900 são reservados pelos Correios para Grandes Usuários — orgaos públicos, grandes empresas, universidades. Um CEP como 70150-900 (Palacio do Planalto em Brasilia) entrega correspondência a uma instituição especifica, não a uma rua. Tratar esses casos como "CEP de endereço" num fluxo de e-commerce comum quebra calculadoras de frete porque eles aceitam correspondência mas nem sempre entrega domiciliar.

CEPs terminados em -970 historicamente pertencem a agencias dos Correios (caixas postais e unidades de atendimento). Muitos ainda estão ativos e se comportam mais como caixas postais que endereços residenciais.

Casos de uso: auto-fill em checkout e cálculo de frete

O padrão mais comum em front-ends brasileiros e o checkout com CEP primeiro: o usuário digita o CEP, a página 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 padrão. O fluxo de auto-fill combina:

• Validação de formato (o que esta ferramenta faz) antes de disparar a requisição HTTP.
• Lookup semantico (ViaCEP ou BrasilAPI) para buscar o endereço.
• Cálculo de frete (Correios SIGEP, Frete Rápido, Melhor Envio) usando CEP e peso para estimar custo e prazo.
• Risk score cruzando com o BIN do cartão para detectar fraude quando CEP e UF de cobranca discordam.

Anti-pattern e confiar apenas em validação por regex e pular o lookup semantico. Usuários digitam rotineiramente o CEP de outra rua ou um CEP que não 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 hífen e obrigatório?

Não. Tanto 01310-100 quanto 01310100 são válidos. O hífen e apenas apresentacao. A maioria dos back-ends armazena os 8 dígitos sem hífen.

O lookup do ViaCEP e gratuito?

Sim, gratuito e sem autenticação. O limite prático e de cerca de 10.000 requisições por dia por IP. Para volumes maiores, use a BrasilAPI como fallback ou contrate o DNE dos Correios.

Todo endereço brasileiro tem CEP próprio?

Não. Cidades pequenas compartilham um único CEP para a cidade inteira (sufixo -000). Cidades grandes chegam até granularidade por rua ou por face de quadra. Sufixos especiais (-899, -900, -970) sinalizam CEPs institucionais.

Um mesmo CEP pode pertencer a duas cidades?

Não. Cada CEP esta unicamente atrelado a um município e UF. Se uma cidade e dividida ou emancipada, os Correios reemitem os códigos.

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

Porque 01310-100 e o CEP canônico do MASP e do trecho central da Avenida Paulista em São Paulo. O 0 inicial marca São Paulo capital; os quatro dígitos seguintes afunilam para o bairro do Bela Vista.