Validador de Código de Município IBGE

Validador de código de município IBGE: algoritmo, dígito verificador e três níveis de validação

Esta página foca especificamente no algoritmo de validação do código IBGE de 7 dígitos — como confirmar que uma string pode ser um código IBGE válido sem bater na API externa, e como escalar para checagem semântica e ao vivo quando necessário. A taxonomia completa de municípios, prefixos UF e casos de uso está coberta na ferramenta irmã; aqui mergulhamos na matemática e nos trade-offs de engenharia.

O código IBGE identifica cada um dos 5.570 municípios brasileiros (Censo 2022) mais o Distrito Federal. Sua estrutura é fixa: 7 dígitos numéricos, onde os 2 primeiros são o prefixo UF, os dígitos 3 a 6 são o micro-código sequencial e o 7º é o dígito verificador (DV) historicamente calculado pelo próprio IBGE.

Nível 1: validação de formato (regex)

A checagem mais barata — puramente estrutural, sem rede, sem tabela. Rejeite qualquer coisa que não tenha exatamente sete dígitos com um prefixo UF do conjunto permitido:

const FORMATO = /^\d{7}$/;
const UFS_VALIDAS = new Set([
  '11','12','13','14','15','16','17',
  '21','22','23','24','25','26','27','28','29',
  '31','32','33','35',
  '41','42','43',
  '50','51','52','53'
]);
function formatoValido(codigo) {
  if (!FORMATO.test(codigo)) return false;
  return UFS_VALIDAS.has(codigo.slice(0, 2));
}

Isso pega erros como códigos de 6 dígitos (CEP confundido com IBGE), zeros à esquerda removidos pela serialização JSON e prefixos UF inválidos como 34 ou 44 (que não existem — a numeração deixou lacunas propositais).

Nível 2: dígito verificador (DV)

O 7º dígito é um DV computado a partir dos primeiros seis. O algoritmo histórico do IBGE usa pesos estilo Luhn:

function dvIBGE(seis) {
  // seis = primeiros 6 dígitos como string
  const pesos = [1, 2, 1, 2, 1, 2];
  let soma = 0;
  for (let i = 0; i < 6; i++) {
    let prod = parseInt(seis[i], 10) * pesos[i];
    if (prod > 9) prod = Math.floor(prod / 10) + (prod % 10);
    soma += prod;
  }
  const dv = (10 - (soma % 10)) % 10;
  return dv;
}
function dvValido(codigo) {
  if (codigo.length !== 7) return false;
  const esperado = dvIBGE(codigo.slice(0, 6));
  return esperado === parseInt(codigo[6], 10);
}

Exemplo com São Paulo (3550308): primeiros 6 = 355030, produtos = 3,10,5,0,3,0, somando dígitos dos >9 (10 → 1), soma = 3+1+5+0+3+0 = 12, dv = (10 - 12 % 10) % 10 = 8. Confirmado.

Nível 3: existência (API IBGE)

Mesmo um código com formato válido e DV correto pode se referir a um município que nunca foi criado. A checagem autoritativa é uma chamada ao vivo à API REST do IBGE:

async function existeNoIBGE(codigo) {
  const r = await fetch(
    `https://servicodados.ibge.gov.br/api/v1/localidades/municipios/${codigo}`
  );
  if (r.status === 200) {
    const j = await r.json();
    return { ok: true, nome: j.nome, uf: j.microrregiao.mesorregiao.UF.sigla };
  }
  return { ok: false };
}

O endpoint é gratuito, retorna JSON, dispensa API key e tem rate limit de alguns milhares de requisições por hora por IP. O BrasilAPI espelha os mesmos dados em brasilapi.com.br/api/ibge/municipios/v1/{UF} com cache extra e CORS aberto por default — preferido para chamadas no browser em checkouts.

Usos obrigatórios em que a validação importa

• NF-e: campo cMun (município da operação), cMunFG (fato gerador), cMunDescarga (descarga) — a Sefaz rejeita o XML se algum código IBGE estiver ausente ou inválido.
• eSocial: layouts S-1010 (Estabelecimento) e S-2200 (Admissão) exigem codMunic.
• IRRF, FGTS, RAIS, CAGED, DIRF: todos os reports federais trabalhistas e fiscais usam código IBGE para segmentação geográfica.
• SUS DATASUS: datasets de hospital, procedimento e epidemiologia indexados por código IBGE.
• Georreferência: junções de código IBGE com tabelas de estado/região para dados do Censo, MapBiomas e alertas de desmatamento do INPE.

Anti-padrões e pegadinhas

• Lista hardcoded fica desatualizada: novos municípios são raros mas acontecem (Mojuí dos Campos/PA em 2013, Pinto Bandeira/RS em 2013). Um JSON hardcoded de dois anos atrás vai perder esses — prefira a API ou recarregue a lista a cada release.
• Libs NPM antigas: muitas libs (brasileiro, br-cidades) foram atualizadas pela última vez em 2018-2020 e não têm municípios recentes. Audite antes de subir.
• Zeros à esquerda: códigos do Acre (12xxxxx) e Amazonas (13xxxxx) frequentemente chegam sem o padding correto de planilhas — sempre trate como string.
• Confusão com CEP: CEP tem 8 dígitos e muda por rua; IBGE tem 7 dígitos e é por município. Nunca use um para derivar o outro sem tabela de cruzamento adequada.
• Exceção do Distrito Federal: o DF tem um único código IBGE (5300108) cobrindo toda Brasília — não há códigos sub-municipais para regiões administrativas.

FAQ

A API do IBGE é mesmo gratuita? Sim — o endpoint em servicodados.ibge.gov.br é operado pelo próprio IBGE, dispensa cadastro ou API key, e tem rate limit de alguns milhares de requisições por hora por IP. Para volumes maiores, espelhe a tabela localmente e atualize semanalmente.

O dígito verificador é obrigatório? Sim — o 7º dígito faz parte do código. A maioria dos validadores aceita códigos sem computar o DV e confia só na consulta à tabela, mas a checagem algorítmica de DV é um pré-filtro útil para rejeitar erros de digitação óbvios antes de qualquer chamada de rede.

O código muda ao longo do tempo? Não. Uma vez atribuído, o código IBGE é vitalício para aquele município. Mesmo que a cidade seja renomeada, desmembrada ou fundida, o código original nunca é reatribuído a outro município — garantindo integridade referencial em datasets históricos desde os anos 1970.

Dá para validar offline? Sim — combinando o regex (nível 1) e o algoritmo do DV (nível 2) você pega mais de 95% dos códigos malformados sem nenhuma chamada de rede. Só a existência real exige a API ou uma cópia local da tabela do IBGE (um CSV de 5.570 linhas, ~120 KB).