Para preparar feriados municipais para uma automação de IA, crie uma base revisada por município, com data, classificação, fonte oficial e período de validade. A IA pode ajudar a extrair informações de publicações, mas a decisão de liberar uma cobrança, marcar uma visita ou prometer atendimento deve consultar regras verificáveis.
O principal desafio é transformar um calendário em uma decisão operacional: qual localidade vale para aquela tarefa, o que acontece com pontos facultativos e como agir quando falta informação. Uma lista nacional de datas, mesmo correta, não resolve essas perguntas para filiais espalhadas pelo Brasil.
Resumo rápido
- Identifique cada município com código oficial e UF.
- Separe feriado, ponto facultativo e fechamento interno.
- Guarde a publicação que fundamenta cada registro.
- Calcule o dia local antes de consultar o calendário.
- Trate ausência de cobertura como pendência, não como dia útil.
Defina qual município governa cada tarefa
Uma transportadora pode ter sede, depósito e destinatário em cidades diferentes. O calendário relevante para retirar um pacote pode ser o do depósito; para entregar, o da unidade de destino. Um agente que usa sempre a cidade da sede produz decisões consistentes com uma regra inadequada. Comece descrevendo a operação e sua referência territorial.
Cadastre o município pelo identificador oficial, acompanhado do nome e da UF. A API de localidades do IBGE oferece consultas por município e por estado. Ela serve para identificar a localidade, não para certificar seus feriados. Evite transformar um bairro, uma região comercial ou um nome abreviado em município sem conferir o cadastro.
Defina também quem resolve conflitos. Uma visita pode depender do funcionamento do técnico e do cliente. Nesse caso, a regra proposta pode exigir disponibilidade nos dois calendários, registrando qual deles bloqueou a agenda. Outras operações terão prioridades diferentes. Documente essa escolha antes de conectá-la ao agente.
Para tarefas remotas, a residência do usuário nem sempre determina a operação. A regra pode depender da unidade que presta o serviço ou do contrato atendido. Grave essa referência na própria tarefa para que alterações posteriores no cadastro não mudem silenciosamente a justificativa de um agendamento já aprovado.
Separe natureza da data e efeito no negócio
Feriado, ponto facultativo e fechamento decidido pela empresa precisam de categorias distintas. A Lei nº 9.093 estabelece categorias de feriados civis e trata de feriados religiosos declarados em lei municipal. Esse enquadramento não substitui a leitura do ato aplicável à cidade e à atividade.
Ao coletar uma publicação, confira seu alcance. Um calendário de expediente da prefeitura pode orientar o funcionamento daquela administração, sem demonstrar que toda empresa privada fecha na mesma data. Não transforme a expressão “ponto facultativo” em proibição geral de trabalhar. Registre o que a fonte efetivamente informa e deixe a política operacional em campo separado.
| Registro | Evidência necessária | Decisão proposta para a automação |
|---|---|---|
| Feriado local confirmado | Ato oficial e localidade abrangida | Consultar política da operação |
| Ponto facultativo | Publicação e público ao qual se aplica | Bloquear apenas calendários abrangidos |
| Fechamento interno | Aprovação do responsável pela unidade | Aplicar à unidade e ao período aprovados |
| Informação não confirmada | Fonte ausente ou contraditória | Encaminhar para revisão |
| Data sem restrição na base | Cobertura revisada do período | Avaliar horário e demais regras |
Essas decisões são um desenho sugerido de sistema. Para prazos contratuais, obrigações legais ou jornadas de trabalho, o responsável precisa confirmar o tratamento aplicável. O calendário deve fornecer evidências para essa análise, sem assumir que um único campo “dia útil” responde a todas as situações.
Monte registros com fonte, cobertura e versão
Use campos separados para identificador do evento, código do município, UF, data local, nome, natureza, abrangência, URL oficial, identificação do ato, início de validade e responsável pela revisão. Inclua quando a informação foi consultada e qual versão do calendário recebeu aprovação. Uma observação livre complementa esses campos, mas não deve carregar sozinha a lógica de bloqueio.
Prefira portais de legislação, diários oficiais e páginas institucionais que apontem para o ato correspondente. Calendários comerciais ajudam na descoberta, porém não devem encerrar a verificação. Quando a IA extrair uma data de um PDF, mantenha o trecho e a página que sustentam o registro. Depois, uma pessoa confere nome, alcance e vigência.
A cobertura merece uma tabela própria. Ela informa quais municípios e intervalos foram efetivamente revisados. “Nenhum feriado cadastrado” pode significar uma semana normal ou uma importação incompleta. Sem essa distinção, um erro de coleta vira autorização de execução. Uma consulta deve poder retornar “sem cobertura”, além de “permitido” e “bloqueado”.
Não sobrescreva versões já usadas. Ao corrigir uma publicação, gere uma nova versão, explique a mudança e identifique tarefas futuras afetadas. O procedimento de registro de versões de documentos citados pela IA ajuda a preservar a relação entre decisão e evidência. Guarde somente os documentos e metadados necessários para refazer a análise.
Conecte o calendário ao fluxo sem delegar o cálculo ao modelo
Receba uma tarefa com localidade, horário pretendido e tipo de operação. Valide esses campos antes de pedir qualquer explicação à IA. Converta o instante para o fuso da unidade e consulte a data local resultante. A base de fusos da IANA é uma referência técnica para identificadores e mudanças de regras de horário.
Uma data de feriado representa um dia do calendário local. Ela não deve ser armazenada automaticamente como meia-noite UTC e depois convertida, porque essa transformação pode deslocar o dia exibido. Mantenha a data civil separada do instante de uma tarefa. Para problemas de horários, consulte também o guia de fusos horários em agentes de agendamento.
Se exportar arquivos de calendário, confira como o consumidor interpreta eventos de dia inteiro. A RFC 5545 descreve valores de data e data com horário no formato iCalendar. Importe e exporte um evento de teste para conferir se o bloqueio continua no mesmo dia, inclusive em outra interface.
A consulta determinística deve devolver decisão, motivo, referências e versão. O modelo recebe esse resultado para redigir uma mensagem compreensível: “a unidade está fechada nessa data; aguarde confirmação da próxima opção”. Ele não precisa inventar a próxima data. Um componente de agenda calcula alternativas e verifica novamente cada uma delas.
Separe consulta de execução. Uma sugestão de nova data pode virar uma proposta pendente, sem enviar convites ou alterar pedidos. Quando a operação for executada, valide novamente cobertura e versão. Isso protege tarefas que ficaram horas na fila enquanto o calendário recebeu uma correção relevante.
Exemplo: assistência técnica com unidades em Curitiba e Recife
Considere uma assistência técnica fictícia com unidades em Curitiba e Recife. O caso é ilustrativo e não afirma datas reais de feriados dessas cidades. A empresa quer que um agente ofereça visitas somente quando a unidade responsável e o cliente tiverem disponibilidade confirmada.
A equipe cria duas localidades no cadastro e associa cada técnico à sua unidade. No ambiente de testes, inclui uma “Data de fechamento simulado” para a unidade de Curitiba, com marcação explícita de dado fictício. Esse evento serve para testar o fluxo; ele nunca entra no calendário de produção.
Um pedido de visita chega com endereço de atendimento e preferência de horário. A aplicação identifica o município do endereço, consulta a cobertura e cruza a disponibilidade da unidade escalada. Se a tarefa cair no fechamento simulado, o sistema devolve o motivo e pede ao agendador outras opções. A IA apenas explica o resultado ao atendente.
Em outro teste, a cobertura de Recife é removida deliberadamente. O resultado esperado é “revisão necessária”. O agente não diz que a unidade estará aberta. O atendimento pode registrar a preferência do cliente, mas não confirmar a visita. Assim, a falta de dados aparece como pendência visível.
Antes da implantação, o gerente aprova os registros reais com suas fontes oficiais. O teste simulado é mantido em uma base separada para regressões. A empresa não mede sucesso pelo número de datas importadas: verifica se cada decisão consegue explicar localidade, regra, fonte e responsável.
Teste atualizações, conflitos e retomadas
Monte uma matriz com data comum, fechamento confirmado, ponto facultativo de alcance restrito, ausência de cobertura e duas fontes divergentes. Repita os cenários para unidades distintas. O mesmo dia pode produzir decisões diferentes, e isso deve ser consequência de regras documentadas, não de respostas diferentes do modelo.
Inclua entradas difíceis: cidade sem UF, município com nome parecido, endereço incompleto, horário próximo à virada do dia e tarefa criada antes de uma atualização. Verifique o resultado esperado e a justificativa. Um teste só de “resposta bem escrita” não revela se o calendário consultado pertence ao município correto.
Para atualizar a base, prepare uma versão candidata e compare inclusões, exclusões e alterações. O revisor aprova as diferenças antes da ativação. Se uma fonte oficial estiver indisponível, preserve a última versão aprovada dentro de sua cobertura e sinalize que a revisão está pendente; não amplie sua validade por conveniência.
Registre tarefas reagendadas com um identificador estável, para que uma retomada não envie duas confirmações. Mantenha separadas a decisão anterior e a nova. Quando várias tarefas dependem da mesma correção, a orientação sobre simulação e limites para ações em lote ajuda a revisar o impacto antes de executar mudanças.
Erros comuns
Usar a memória da IA como calendário. Uma resposta plausível não comprova uma data municipal. Exija fonte oficial por registro e aprovação de cobertura. O modelo pode localizar candidatos, mas não publicar sozinho a base que autoriza ações.
Repetir todas as datas no ano seguinte. Recorrência precisa de regra e vigência confirmadas. Datas móveis e atos específicos exigem revisão. Gerar um calendário candidato não equivale a aprová-lo.
Confundir fechamento interno com feriado. Essa mistura prejudica auditorias e reutilização por outras unidades. Mantenha a categoria original e registre separadamente o efeito operacional aprovado.
Falhar sem avisar. Se a API, a importação ou a identificação da cidade falhar, uma resposta vazia não pode virar “liberado”. Defina estados explícitos, alertas e uma pessoa responsável pela pendência.
Perguntas frequentes
Uma API de feriados pronta resolve o problema?
Pode fornecer dados, mas verifique cobertura municipal, origem, atualização e tratamento de pontos facultativos. Sua aplicação ainda precisa decidir qual município e qual política se aplicam à tarefa.
É necessário cadastrar o país inteiro?
Não. Comece pelas localidades atendidas e declare a cobertura. Municípios novos entram em revisão antes de permitir confirmações automáticas. Uma cobertura pequena e explícita é operacionalmente mais verificável.
Posso importar uma agenda compartilhada?
Sim, como entrada controlada. Confira proprietário, origem dos eventos e interpretação de dia inteiro. A agenda visual não substitui os campos de abrangência, versão e aprovação necessários para decisões automáticas.
Como tratar informações oficiais divergentes?
Registre ambas e suspenda a decisão afetada até a revisão do responsável. Verifique se tratam de períodos ou públicos diferentes antes de concluir que existe contradição.
Quando revalidar uma tarefa agendada?
Na confirmação e perto da execução, conforme o risco e o prazo da operação. Mudanças aprovadas no calendário devem permitir identificar tarefas futuras afetadas e encaminhá-las para nova decisão.
