Por que você deve parar de hardcodar feriados no seu banco de dados

Se você é desenvolvedor no Brasil, já escreveu este código:

# NÃO FAÇA ISSO EM CASA
feriados_2026 = [
    "2026-01-01",
    "2026-04-21",
    "2026-05-01",
    # ... mais 10 linhas
]

Ou pior, criou uma tabela holidays no banco de dados e todo mês de dezembro alguém do time (provavelmente o estagiário) precisa rodar um script de INSERT para o ano seguinte.

Neste artigo, vou argumentar tecnicamente por que essa prática é uma dívida técnica perigosa e como APIs modernas resolvem isso definitivamente.

O pesadelo dos Feriados Móveis

O primeiro problema é matemático. Feriados como Carnaval, Sexta-feira Santa e Corpus Christi não têm data fixa. Eles dependem da Páscoa, que depende da lua cheia (sério).

Para calcular a Páscoa, você precisa implementar o Algoritmo de Gauss ou algo similar. Você quer mesmo manter um algoritmo astronômico no seu utils.ts apenas para saber se o banco abre na terça-feira?

O pesadelo Legislativo

O segundo problema é político. As leis mudam.

• 2023:O Dia da Consciência Negra (20/11) tornou-se feriado nacional. Antes era municipal ou estadual em alguns lugares.
• Pandemia:Em 2020/2021, diversos feriados foram “antecipados” por decretos estaduais.
• Municípios:O Brasil tem 5.570 municípios. Cada um com seu aniversário e padroeiro.

Se seu sistema hardcoda feriados, toda vez que um prefeito assina um decreto, você precisa fazer um deploy. Isso não escala.

Hardcoded vs API: O Comparativo

A solução limpa (Clean Code)

Em vez de sujar seu domínio com regras de calendário, trate feriados como uma dependência externa.

Exemplo de como verificar se hoje é dia útil usando a Feriados API:

import requests
from datetime import date

def is_workday(check_date: date):
    # Consulta API para verificar se é feriado
    resp = requests.get(
        f"https://feriadosapi.com/api/v1/feriados/data/{check_date}?ano={check_date.year}",
        headers={"X-API-Key": "SEU_TOKEN_AQUI"}
    )
    
    # A API retorna sempre 200, com lista de feriados
    if resp.status_code == 200:
        dados = resp.json()
        
        # Se houver feriados na lista, não é dia útil
        if dados.get('total', 0) > 0:
            feriado = dados['feriados'][0]
            print(f"Folga! É {feriado['nome']}")
            return False
            
    return True

Exemplo de resposta da API

A API retorna um objeto JSON detalhado. Veja a documentação completa para mais detalhes:

{
  "data": "2026-01-01",
  "feriados": [
    {
      "data": "01/01/2026",
      "nome": "Ano Novo",
      "tipo": "NACIONAL",
      "descricao": "O Ano-Novo ou Réveillon é um evento que acontece...",
      "uf": null,
      "codigo_ibge": null
    }
  ],
  "total": 1
}

Conclusão

Hardcodar dados voláteis é um anti-pattern. Calendários parecem estáticos, mas são políticos e astronômicos — ou seja, altamente voláteis.

Delegue essa complexidade. Seu código fica mais limpo, seu banco de dados mais leve e seu time foca no que importa: a regra de negócio do seu produto.