O que é um calendário de feriados e por que ele te dá trabalho
Calendário de feriados é simplesmente uma lista estruturada de datas que não são dias úteis. No Brasil, isso parece simples até você perceber que existem feriados federais, estaduais e municipais, além de pontos facultativos, comemorações religiosas e datas comerciais que bancos e empresas usam de forma diferente. Se você está construindo uma aplicação que precisa calcular prazos, SLAs ou agendamentos, ignorar isso custa tempo. Eu já perdi uma manhã inteira debugando um problema onde um cliente em Porto Alegre reclamava que o sistema havia marcado um praso para uma data que era feriado no município, embora não fosse feriado federal. A resposta do sistema estava tecnicamente correta pelo padrão nacional, mas comercialmente errada. Desde então, sempre peço a cidade e o estado do usuário antes de validar qualquer data.
feriado calendario: construindo o seu
O primeiro passo é decidir qual nível de feriado você vai considerar. Feriados fedrais no Brasil são poucos: 1º de janeiro (Confraternização Universal), Sexta-Feira Santa, Tiradentes (21 abril), Dia do Trabalho (1º maio), Independência (7 setembro), Nossa Senhora Aparecida (12 outubro), Finados (2 novembro), Proclamação da República (15 novembro), Natal (25 dezembro). Dois desses, Páscoa e Corpus Christi, são móveis e dependem do cálculo da lua. Se você não quer implementar o cálculo sozinho, use uma biblioteca como python-holiday ou workingdays. Para feriados estaduais e municipais, a coisa muda. Cada um dos 27 estados e milhares de municípios tem suas próprias datas. São Paulo tem 3 de maio (Revolução Constitucionalista). Rio de Janeiro tem 20 de janeiro (padroeiro). Curitiba tem 19 de dezembro. Isso não vem embutido em nenhuma biblioteca genérica, então você precisa montar sua própria tabela ou comprar acesso a uma API paga.
No meu caso, a solução que funcionou foi manter um arquivo CSV local atualizado manualmente uma vez por ano, com colunas para code, date, name, type (federal/state/municipal), and applicable_cities. A atualização anual leva cerca de 30 minutos. Eu faço isso em dezembro, quando as câmaras municipais publicam as leis do ano seguinte. O formato que uso é: code,date,name,type,state,municipality
BR_NEW_YEAR,2025-01-01,Confraternização Universal,federal,,,
BR_CARNAVAL,2025-03-04,Carnaval,federal,,,
SP_REVOLUTION,2025-05-03,Revolução Constitucionalista,state,SP,
CURITIBA_PADROEIRO,2025-12-19,Santa Cruz,municipal,,Curitiba
Isso é simples demais para ser perfeito. Funciona para 95% dos casos. Os 5% restantes são quando uma lei municipal muda no meio do ano, o que já aconteceu comigo quando o município de Campinas alterou o feriado de Emancipação Política sem atualizar a fonte oficial que eu acompanhava. A lição: sempre confira a legislação original, nunca confie em agregadores de terceiros para dados sensíveis.
Implementação prática
Se você está usando Python, a biblioteca holiday cobre feriados federais brasileiros com precisão razoável. O código fica assim: from holiday import Brazil
br = Brazil(years=[2025])
print(br['2025-09-07']) 'Independence Day'
👉 Clique no botão abaixo para saber mais sobre o assunto!
Para feriados estaduais, você sobrescreve o dicionário com seus dados locais. Para municipais, filtra por cidade. O desempenho de uma busca em 500 linhas de CSV é desprezível — menos de 1ms por consulta, mesmo com buscas por intervalo de datas. Se você está em JavaScript, o pacote date-fns-holiday ou dayjs-feriados fazem o trabalho para o federal. Novamente, estaduais e municipais ficam por sua conta.
Erros comuns que eu vejo todo dia
O erro mais frequente é tratar feriado como sinônimo de dia não útil. Não é. Um feriado estadual em SP não significa nada para uma empresa em Recife. Outro erro comum é assumir que feriados móveis são fixos. Páscoa muda todo ano. Corpus Christi varia entre maio e junho. Se você hardcode essas datas, vai falhar no primeiro ano que não olhar. Um terceiro erro, e esse é o que mais causa prejuízo, é não considerar que alguns feriados federais podem ser substituídos por ferados estaduais em certas jurisdições. A Lei Federal 662/1949 permite que estados e municípios criem feriados locais que se sobrepõem aos nacionais. Na prática, isso significa que 7 de setembro em São Paulo pode ser apenas um feriado nacional, mas em 15 de novembro, dependendo do município, pode haver sobreposição com uma data estadual que cancela o ponto.
Onde baixar um calendário pronto
Se você não quer montar a tabela do zero, há opções. O GitHub tem repositórios mantidos pela comunidade, como o adieltonmendes/feriados-brasileiros, que contém uma lista completa de feriados municipais por código IBGE. O Banco Central também disponibiliza tabelas de feriados bancários, mas: apenas feriados bancários, não o calendário completo. Para dados oficiais, a fonte primária é o Diário Oficial de cada município, o que é trabalhoso mas impecável. Eu recomendo começar com o repositório do GitHub como base e depois cruzar com os diários oficiais dos municípios que você realmente opera. O custo de não fazer isso é alto. Um cliente meu já perdeu contrato por enviar uma proposta com prazo calculado sobre um feriado municipal que o departamento jurídico não havia considerado.
Limitações que ninguém menciona
Calendário de feriados não resolve tudo. Ele não lida com compensação de horas, horas extras, adicionais noturnos ou regras de CLT sobre pagamento de feriados. Se o seu sistema precisa calcular custo de pessoal, você precisa de uma regra de negócio acima da tabela de datas. E mesmo com a tabela perfeita, eventos excepcionais — como a pandemia de COVID-19, que gerou decretos de suspensão de expediente em milhares de municípios de forma descentralizada — vão furar qualquer calendário estático. Nesses casos, a única solução é um sistema de override manual com aprovação de alguém da equipe jurídica ou de RH antes de propagar para a produção. Se você trabalha com múltiplos países além do Brasil, a complexidade cresce exponencialmente. Feriados na Argentina são diferentes dos do Chile, que são diferentes dos da Colômbia. Cada país tem seu próprio conjunto de regras para feriados religiosos, civis e regionais. O módulo Brazil da biblioteca holiday é sólido, mas não espere a mesma qualidade para outros países sul-americanos. Para eles, o caminho mais seguro é manter uma tabela manual ou contratar uma API especializada como a do Nexus ou Feriados.com.br.
A verdade é que não existe solução mágica. Um feriado calendario bem feito exige manutenção contínua, validação contra fontes oficiais e um processo claro para tratar exceções. O que eu posso dizer com certeza é que começar com uma tabela manual em CSV e evoluir para automação conforme a necessidade pega é mais barato e mais confiável do que tentar integrar uma API que promete cobertura completa desde o primeiro dia.
