Entenda os Códigos IBGE, UF e Feriados Municipais: O Guia Definitivo para Desenvolvedores

Quando equipes de desenvolvimento internacionais (ou até mesmo programadores brasileiros iniciantes) estruturam sistemas de ERP, fintechs, plataformas de e-commerce ou agentes de IA para operar no Brasil, encontram imediatamente siglas e conceitos geográficos essenciais: UF, Códigos IBGE e a hierarquia de feriados municipais, estaduais e nacionais. Dominar esses conceitos é o segredo para evitar erros de banco de dados e cálculos incorretos de prazos.

Em muitos países estrangeiros, os feriados públicos e divisões administrativas são simples: as datas são padronizadas em âmbito nacional ou regional, e os nomes de cidades podem ser salvos como simples textos no banco de dados. No Brasil, tentar hardcodar feriados ou buscar cidades apenas pelo nome textual é uma garantia de falha arquitetural.

Neste guia definitivo, desmistificamos a geografia administrativa brasileira para desenvolvedores, explicamos por que o código IBGE de 7 dígitos é a chave primária (primary key) mais importante na modelagem de software no Brasil e mostramos como validar calendários de forma limpa via API.

1. O que é UF (Unidade da Federação)?

UF significa Unidade da Federação. O Brasil é uma república federativa composta por 26 estados e 1 Distrito Federal (Brasília — DF). Em bancos de dados e APIs de software, cada estado é universalmente representado por uma sigla padronizada de duas letras maiúsculas.

Exemplos comuns incluem SP para São Paulo, RJ para Rio de Janeiro, MG para Minas Gerais e AM para Amazonas.

Por que a UF importa para calendários: Ao contrário de países centralizados, as assembleias legislativas estaduais no Brasil têm autoridade constitucional para sancionar feriados civis oficiais (até 3 por ano). Por exemplo, 9 de Julho é feriado obrigatório em todo o estado de São Paulo (Revolução Constitucionalista), fechando órgãos públicos e comércio civil. No entanto, é um dia útil normal no Rio de Janeiro ou em Minas Gerais! Se o seu software validar apenas feriados nacionais, seus cálculos de prazos e juros falharão ao cruzar divisas estaduais.

2. O que é o Código IBGE e por que nomes de cidades não são únicos?

O IBGE (Instituto Brasileiro de Geografia e Estatística) é o órgão oficial de estatística e geografia do governo federal, equivalente ao U.S. Census Bureau nos Estados Unidos, ao INSEE na França ou ao ONS no Reino Unido.

O Brasil possui exatamente 5.570 municípios. Um erro muito comum no design de bancos de dados é tentar usar o nome da cidade como chave primária ou parâmetro de busca única. No Brasil, isso é matematicamente inviável devido a uma extrema ambiguidade de nomes:

• ⚠️Nomes de Cidades Idênticos em Estados Diferentes: Existem exatamente 23 municípios diferenteschamados "São Domingos", 21 chamados "Bom Jesus" e 18 chamados "Santa Terezinha" espalhados pelo Brasil.
• ⚠️Variações Ortográficas e Acentuação: Nomes de municípios brasileiros contêm acentos, cedilhas, apóstrofos e hifens (ex: São João d'Aliança ou Embu-Guaçu). Consultas textuais são extremamente vulneráveis a erros de codificação (encoding) e digitação.
• ⚠️Homônimos no Mesmo Estado: Mesmo dentro de uma mesma UF, existem cidades com nomes quase idênticos, tornando o matching de texto perigoso para transações financeiras e fiscais.

A Estrutura do Código IBGE de 7 Dígitos

Para eliminar qualquer ambiguidade, todos os sistemas governamentais, emissões de Nota Fiscal Eletrônica (NF-e), redes de liquidação do Banco Central (Pix, TED, Boletos), operadores logísticos e APIs modernas utilizam o código IBGE de 7 dígitos como identificador universal e imutável de cada município.

Por exemplo, o código IBGE para a cidade de São Paulo é 3550308. Veja a divisão lógica e matemática dessa estrutura:

Sempre que você modelar tabelas de endereços, cadastros de clientes ou centros de distribuição, armazene sempre o código IBGE de 7 dígitos junto com a UF. Isso garante precisão absoluta ao consultar dados locais.

3. A Hierarquia de Feriados: Nacional, Estadual e Municipal

No exterior, é comum pensar em feriados apenas como datas nacionais. No Brasil, o calendário cívico funciona em uma hierarquia legislativa de 3 níveis:

• 1.Feriados Nacionais: Instituídos por lei federal e válidos em todo o território nacional (em todas as 27 UFs e nos 5.570 municípios). Exemplos: Confraternização Universal (1º de jan), Tiradentes (21 de abr), Independência (7 de set) e Natal (25 de dez).
• 2.Feriados Estaduais: Instituídos por leis estaduais. Cada UF pode declarar até 3 feriados civis. Exemplos: 2 de Julho na Bahia (Independência da Bahia) e 20 de Setembro no Rio Grande do Sul (Revolução Farroupilha).
• 3.Feriados Municipais: Instituídos pela Câmara Municipal. Pela Lei Federal nº 9.093/1995, cada um dos 5.570 municípios pode declarar até 4 feriados religiosos ou comemorativos por ano. Isso inclui o Aniversário da Cidade e padroeiros locais (como São Jorge em 23 de abril no Rio de Janeiro, ou Corpus Christi em milhares de cidades).

4. Outros Conceitos Essenciais: Facultativos e Bancários

Para desenvolver aplicações financeiras e logísticas à prova de falhas no Brasil, há dois conceitos que complementam os feriados civis:

Pontos Facultativos

O ponto facultativo é uma data comemorativa em que a liberação do expediente é opcional no setor privado, decretada pelo poder executivo. Os exemplos mais clássicos são o Carnaval (segunda e terça-feira) e o Corpus Christi.

Em âmbito federal, essas datas não são feriados civis obrigatórios para empresas privadas. Contudo, centenas de municípios promulgam leis locais que elevam o Carnaval ou Corpus Christi a feriados municipais obrigatórios!

Feriados Bancários e Liquidação Financeira

Se o seu software emite cobranças, gerencia folha de pagamento ou processa transferências, deve seguir as normas do Conselho Monetário Nacional (Resolução CMN nº 4.880/2020) e o calendário oficial da FEBRABAN.

Embora as agências bancárias físicas fechem nos feriados municipais e estaduais da respectiva praça, as compensações eletrônicas interbancárias (como Pix 24/7 e TED) continuam operando normalmente em âmbito nacional, exceto nos feriados bancários nacionais.

5. Automatizando Validações por Código IBGE

A forma mais limpa e performática de lidar com a geografia e o calendário brasileiro em sistemas em produção é consultar uma API REST especializada passando o código IBGE de 7 dígitos do município. Veja um exemplo simples em Python:

import requests

# Exemplo: Verificando se 25 de Janeiro é feriado na cidade de São Paulo
# Usando o código IBGE oficial de 7 dígitos: 3550308
ibge_code = "3550308"
check_date = "2026-01-25"

url = f"https://api.feriadosapi.com/v1/feriados/cidade/{ibge_code}?ano=2026"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
holidays = response.json()

for holiday in holidays:
    if holiday["data"] == check_date:
        print(f"🎉 Feriado Encontrado: {holiday['nome']} ({holiday['tipo']})")
        # Saída: 🎉 Feriado Encontrado: Aniversário de São Paulo (MUNICIPAL)

A API retorna um array JSON estruturado com todos os feriados nacionais, estaduais e municipais aplicáveis àquela cidade específica, trazendo inclusive a flag booleana bancario:

[
  {
    "data": "2026-01-01",
    "nome": "Confraternização Universal",
    "tipo": "NACIONAL",
    "bancario": true
  },
  {
    "data": "2026-01-25",
    "nome": "Aniversário de São Paulo",
    "tipo": "MUNICIPAL",
    "bancario": false,
    "codigo_ibge": "3550308"
  },
  {
    "data": "2026-07-09",
    "nome": "Revolução Constitucionalista",
    "tipo": "ESTADUAL",
    "bancario": false,
    "uf": "SP"
  }
]

Pronto para deixar sua aplicação 100% em conformidade com as regras geográficas e de calendário do Brasil? Crie sua conta grátis na Feriados API e consulte todos os 5.570 municípios com latência sub-milissegundo.