Validador de Código UF IBGE

Validacao do codigo UF do IBGE: 2 digitos, 27 estados validos, numeracao nao consecutiva

O codigo UF do IBGE e um identificador numerico de 2 digitos atribuido pelo IBGE (Instituto Brasileiro de Geografia e Estatistica) a cada unidade federativa brasileira — 26 estados mais o Distrito Federal. E o codigo canonico usado em NF-e, eSocial, CNAE, dados georreferenciados e estatisticas federais. Validar nao e checar se a entrada tem dois digitos: apenas 27 valores especificos sao legais, e a numeracao e intencionalmente nao consecutiva.

O risco de confundir o codigo UF do IBGE com qualquer numero de 2 digitos e real: sistemas de emissao que cravam 00..99 como faixa valida silenciosamente aceitam codigos invalidos como 34 ou 44, e a Sefaz so detecta o erro na transmissao, retornando rejeicao 247 ("UF do destinatario invalida") ou 251 ("cUF nao corresponde ao emitente").

A tabela completa dos 27 codigos validos

Os codigos IBGE sao organizados por regiao; o primeiro digito reflete a regiao geografica.

• Norte (1x): 11 RO (Rondonia), 12 AC (Acre), 13 AM (Amazonas), 14 RR (Roraima), 15 PA (Para), 16 AP (Amapa), 17 TO (Tocantins).
• Nordeste (2x): 21 MA (Maranhao), 22 PI (Piaui), 23 CE (Ceara), 24 RN (Rio Grande do Norte), 25 PB (Paraiba), 26 PE (Pernambuco), 27 AL (Alagoas), 28 SE (Sergipe), 29 BA (Bahia).
• Sudeste (3x): 31 MG (Minas Gerais), 32 ES (Espirito Santo), 33 RJ (Rio de Janeiro), 35 SP (Sao Paulo).
• Sul (4x): 41 PR (Parana), 42 SC (Santa Catarina), 43 RS (Rio Grande do Sul).
• Centro-Oeste (5x): 50 MS (Mato Grosso do Sul), 51 MT (Mato Grosso), 52 GO (Goias), 53 DF (Distrito Federal).

Total: 27 codigos validos. Qualquer entrada fora desse conjunto e invalida — nao ha excecao.

As lacunas: por que 18, 19, 20, 30, 34, 36-40, 44-49 nao existem

Fonte classica de bug em validadores de NF-e e supor que os codigos UF sao sequenciais. Nao sao. A Resolucao IBGE de 1976 numerou os estados em ordem regional com espacos deliberados para crescimento:

• 18, 19, 20: nunca atribuidos. Reservados para hipoteticas futuras divisoes da regiao Norte. Quando Tocantins (17) foi criado a partir de Goias em 1988, o IBGE optou por nao preencher 18-20 — permanecem como buffer legado do antigo Norte.
• 30: nunca atribuido. Funcionou como separador entre o ultimo codigo do Nordeste (29 BA) e a faixa do Sudeste.
• 34: vaga no Sudeste. SP recebeu o 35 diretamente na tabela original pela sua proeminencia; o 34 ficou reservado para uma UF Sudeste extra que nunca se concretizou.
• 36 a 40: buffer entre Sudeste e Sul.
• 44 a 49: buffer entre Sul e Centro-Oeste.

Licao: nunca valide um codigo UF com code >= 11 && code <= 53. Sempre consulte contra o conjunto explicito dos 27 codigos.

Implementacao de referencia

const VALIDOS = 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 validarUfIbge(entrada) {
  const re = /^\d{2}$/
  if (!re.test(entrada)) return { ok: false, erro: 'formato' }
  const codigo = parseInt(entrada, 10)
  if (!VALIDOS.has(codigo)) return { ok: false, erro: 'codigo inexistente' }
  return { ok: true, codigo }
}

Codigo vs sigla: duas notacoes paralelas

No Brasil, o estado e identificado de duas formas: a sigla de 2 letras (SP, RJ, MG) e o codigo IBGE de 2 digitos (35, 33, 31). Ambos sao oficiais e inequivocos, mas aparecem em contextos diferentes:

• Sigla: placas de veiculos, prefixos de CEP, enderecos, etiquetas postais, jornalismo.
• Codigo: NF-e (tag cUF), eSocial, FGTS, arquivos INSS, estatisticas IBGE, XML de governo, CNES.

Ao integrar sistemas diferentes, mantenha ambos na sua tabela de lookup. A BrasilAPI expoe um endpoint gratuito de leitura: GET https://brasilapi.com.br/api/ibge/uf/v1 retorna a lista canonica com codigo, sigla e nome completo.

Casos de uso que exigem validacao

• Tag cUF da NF-e: o codigo IBGE do estado do emitente, usado pela Sefaz para rotear o documento para o webservice da UF correta. cUF errado retorna rejeicao 247 ou 251.
• eSocial S-1000: o codigo UF do empregador e obrigatorio no evento de cadastro da empresa.
• Codigos municipais: o codigo IBGE de municipio (7 digitos) comeca com o codigo UF; validar o prefixo pega typos antes do lookup posterior.
• Dados georreferenciados: DataSUS, INEP e IPEA chaveiam tudo pelo codigo UF do IBGE.
• Estatisticas e BI: a maioria dos datasets publicos faz join por codigo IBGE, nao por sigla.

Nota historica: TO e a expansao de 1988

A tabela IBGE original de 1976 tinha 26 estados. Tocantins (codigo 17) foi criado pela Constituicao de 1988 a partir do norte de Goias, e o IBGE o encaixou no bloco Norte — preservando a disciplina do prefixo 1x. Nenhum codigo anterior foi reescrito, razao pela qual tanto software legado tem Tocantins ausente, em vez de incorreto.

Outras propostas de estados da epoca de 1988 (Triangulo Mineiro, Sao Francisco, Maranhao do Sul) nunca se concretizaram, deixando as lacunas reservadas intactas. Qualquer nova UF receberia um codigo do proximo slot disponivel, nao um reciclado.

FAQ

Os codigos sao consecutivos? Nao. Existem lacunas deliberadas (18, 19, 20, 30, 34, 36-40, 44-49). Valide sempre contra o conjunto explicito dos 27 codigos, nunca contra uma faixa.

Quando a tabela muda? So quando uma nova unidade federativa e criada ou uma existente e desmembrada — nada disso acontece desde Tocantins, em 1988. Para fins praticos a tabela e estavel.

Existe API oficial gratuita? Sim. O endpoint do IBGE (servicodados.ibge.gov.br/api/v1/localidades/estados) e gratuito e sem autenticacao; a BrasilAPI faz proxy dos mesmos dados com payloads mais simples.

Por que SP e 35 e nao 34? O codigo 34 ficou reservado como folga futura para o Sudeste; SP, a maior UF do Sudeste, ancorou o proximo numero significativo (35) na tabela original de 1976. A reserva nunca foi usada.

Posso confundir o codigo UF do IBGE com prefixo GS1 de pais? Nao. Os prefixos GS1 para o Brasil sao 789-790 (3 digitos, em codigos de barras EAN/UPC) e servem a outra finalidade. Nao ha sobreposicao com os codigos UF do IBGE.