Criando um Agendamento à Prova de Falhas: Como Evitar Conflitos com Feriados Locais no seu SaaS

Se você desenvolve software para agendamento (SaaS médico, beleza, consultorias ou field service), existe um problema silencioso que gera churn e frustração: o conflito de agenda em feriados locais.

Imagine o cenário: seu cliente, uma clínica em São Paulo, usa seu sistema. O feriado da Consciência Negra (20 de novembro) chega. O sistema, padronizado para feriados nacionais, não bloqueia a data. Pacientes agendam. A clínica não abre. Resultado: no-shows, reclamações e estresse.

Neste artigo, vou mostrar como resolver isso de forma elegante e automatizada, garantindo que seu calendário respeite não apenas o calendário nacional, mas a realidade local de cada cliente.

O Problema do “Hardcoded”

A primeira tentativa de solução geralmente é criar uma tabela de feriados no banco de dados. Funciona bem para 1º de Janeiro ou 25 de Dezembro. Mas o Brasil é complexo.

Temos milhares de municípios, cada um com seus aniversários e padroeiros. Tentar manter essa base atualizada manualmente é, tecnicamente, uma dívida técnica impagável.

A Solução: Validação Backend

A melhor abordagem é tratar a “validade” de um dia útil como uma verificação de lógica de negócio no seu backend. Desacople essa complexidade mantendo seu banco de dados limpo e consultando uma fonte confiável.

Vamos usar a Feriados API para verificar dinamicamente a agenda.

Exemplo Prático: Verificação em Python

Aqui está um exemplo simples de uma função backend que verifica se uma data específica é válida para agendamento em uma cidade, consultando a API:

import requests
from datetime import date

def verificar_disponibilidade(data_consulta: date, ibge_cidade: str):
    """
    Verifica se uma data é feriado naquela cidade.
    Retorna (True, motivo) se for feriado, ou (False, None) se estiver livre.
    """
    ano = data_consulta.year
    # Consulta a API para pegar todos os feriados daquele ano para a cidade
    url = f"https://feriadosapi.com/api/v1/feriados/cidade/{ibge_cidade}?ano={ano}"
    
    try:
        response = requests.get(url)
        response.raise_for_status()
        dados = response.json()
        
        # A API retorna os feriados dentro da chave 'feriados'
        lista_feriados = dados.get('feriados', [])
        
        # Formata a data para DD/MM/YYYY (padrão da API)
        data_str = data_consulta.strftime("%d/%m/%Y") # ex: '20/11/2026'
        
        # Procura se a data existe na lista de feriados retornada
        for feriado in lista_feriados:
            if feriado['data'] == data_str:
                return True, feriado['nome']
                
        return False, None
        
    except Exception as e:
        # Tratamento de erro (fallback ou log)
        print(f"Erro na verificação de feriados: {e}")
        return False, None

# --- Simulação de Uso ---
# Cliente de São Paulo (IBGE 3550308) tentando agendar para 20/11/2026
data_desejada = date(2026, 11, 20)
is_feriado, nome_feriado = verificar_disponibilidade(data_desejada, "3550308")
if is_feriado:
    print(f"❌ Agendamento bloqueado: {nome_feriado}")
else:
    print("✅ Data disponível para agendamento.")

O que a API retorna?

Para tomar essa decisão, nós analisamos a resposta JSON da API. Ao chamar o endpoint, você recebe uma estrutura como esta:

{
  "tipo": "MUNICIPAL",
  "ano": "2026",
  "feriados": [
    {
      "data": "20/11/2026",
      "nome": "Dia da Consciência Negra",
      "tipo": "NACIONAL",
      "descricao": "Dia Nacional de Zumbi ou Dia da Consciência Negra...",
      "uf": null,
      "codigo_ibge": null
    },
    {
      "data": "25/01/2026",
      "nome": "Aniversário de São Paulo",
      "tipo": "MUNICIPAL",
      "descricao": "Aniversário da cidade",
      "uf": "SP",
      "codigo_ibge": "3550308"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

Por que isso reduz o Churn?

• ⚙️Zero Configuração: Seu cliente não precisa cadastrar feriados manualmente todo ano. O sistema consulta a API e já sabe quais dias estão bloqueados.
• 💬Feedback Claro: Como visto no código (variável nome_feriado), você pode dizer ao usuário final por que a data está bloqueada. “Desculpe, não abrimos no Aniversário da Cidade.”
• 🔄Manutenção Zero: Quando leis mudam (novos feriados nacionais ou municipais), a API atualiza e seu sistema “aprende” automaticamente.

Conclusão

Pequenos detalhes de regras de negócio, como impedir um agendamento em feriado local, se somam para criar um produto robusto. Não deixe seu usuário descobrir na prática que o sistema dele agendou um cliente para um dia em que a loja está fechada.

Para documentação completa e para obter sua chave de acesso gratuita, acesse a documentação da Feriados API.