Tarefas Financeiras — crons que automatizam mensalidade, cobrança, conciliação
O módulo de Tarefas Financeiras orquestra crons automáticos: geração de mensalidade, verificação de inadimplência, processamento CNAB, conciliação Pix, cálculo de comissão. Sem isso, provedor com 100+ clientes não opera.
Por que existem tarefas financeiras
Provedor com 1000 clientes não pode esperar humano clicar "gerar mensalidade" 1000 vezes. As tarefas financeiras (crontabs) rodam automaticamente — geram mensalidade, verificam inadimplência, processam remessa CNAB, calculam comissão. Cada tarefa tem horário, frequência, e log de execução.
Princípio: qualquer ação financeira repetitiva tem (ou deveria ter) crontab. Manual fica para exceção e auditoria.
As principais tarefas (crons)
| Tarefa |
Frequência |
O que faz |
| gera_mensalidade |
Diária |
Cria faturas do dia (vencimento configurável por contrato) |
| verifica_fatura_atrasada |
Diária (manhã) |
Marca faturas vencidas, dispara cobrança |
| bloqueia_inadimplente |
Diária |
Bloqueia internet de clientes com N dias de atraso |
| desbloqueia_pagamento |
Várias vezes/dia |
Libera internet quando pagamento confirma |
| cobranca_lembrete |
Diária |
Envia lembrete (SMS/WhatsApp/email) antes do vencimento |
| cobranca_pos_vencimento |
Diária |
Cobra após vencimento (escalada D+3, D+7, D+15) |
| remessa_cnab |
Diária ou sob demanda |
Gera arquivo CNAB de boletos pra envio ao banco |
| processa_retorno_cnab |
Diária |
Importa retorno do banco e baixa boletos pagos |
| concilia_pix |
A cada 15min |
Verifica recebimentos Pix via API e baixa fatura |
| calcula_comissao |
Diária / Mensal |
Calcula comissão das vendas do período |
| renova_token_sefaz |
Diária / 12h |
Renova credenciais fiscais (NFCom/NFe) |
| recalcula_inadimplencia |
Diária |
Atualiza aging de carteira |
Glossário
| Termo |
Significado |
| Cron / crontab |
Agendador de tarefas — executa em horários definidos. |
| Tarefa |
Bloco de código que executa uma rotina financeira. |
| Frequência |
Diária, horária, semanal, mensal, sob demanda. |
| Log |
Registro do que aconteceu na execução — sucesso/erro/tempo. |
| Lock |
Mecanismo que impede 2 instâncias da mesma tarefa rodarem simultaneamente. |
| Janela de execução |
Período em que a tarefa pode rodar (ex: madrugada). |
| Timeout |
Tempo máximo permitido — depois mata processo. |
| Idempotência |
Rodar 2x produz o mesmo resultado que 1x (sem duplicar). |
| Dry-run |
Simulação sem efeito real — útil pra debug. |
| Reprocessamento |
Rodar tarefa pra período passado (correção). |
Fluxo do dia (automação)
TAREFAS FINANCEIRAS — UM DIA TÍPICO
──────────────────────────────────────
00:00 recalcula_inadimplencia
│
01:00 gera_mensalidade (faturas do dia)
│
02:00 verifica_fatura_atrasada → marca BLOQUEADO
│
03:00 bloqueia_inadimplente → corta internet
│
06:00 cobranca_lembrete (D-3 do vencimento)
│
07:00 remessa_cnab → arquivo pro banco
│
08:00 processa_retorno_cnab → baixa boletos pagos
│
a cada 15min concilia_pix
│
12:00 cobranca_pos_vencimento
│
18:00 calcula_comissao
│
23:00 renova_token_sefaz
Tela de tarefas
Financeiro → Tarefas Financeiras / Crontab
Listagem de tarefas — frequência, próxima execução, último resultado.
Log de execução — sucessos, falhas, tempo decorrido.
Logs e monitoramento
Cada execução grava:
| Campo |
O que mostra |
| Tarefa |
Nome do cron |
| Início / Fim |
Timestamp de execução |
| Status |
OK / Falha / Timeout / Cancelada |
| Itens processados |
Quantos registros foram afetados |
| Erros |
Quantos erros ocorreram |
| Mensagem |
Detalhe (ex: "1234 faturas geradas, 0 erros") |
Cron que falha silenciosamente é o pior cenário. Configure alerta (email/Slack/webhook) pra qualquer falha — não confie em ninguém olhar log manualmente.
Pegadinhas frequentes
1. Cron desligado por engano. Alguém suspendeu pra teste e esqueceu de ligar. Mensalidades não geradas, clientes felizes (e empresa quebrada).
2. Cron rodando 2x simultaneamente. Duplica lançamentos. Configure lock.
3. Idempotência quebrada. Rodar de novo cria duplicata. Verifique lógica do cron.
4. Cron lento bloqueando os próximos. Tarefa demora 4h, próxima esperando. Aumente concorrência ou divida.
5. Falha sem alerta. Cron falhou às 2h, ninguém viu até cliente reclamar 2 dias depois.
6. Timezone errado. Cron de fim-de-dia rodando 3h adiantado. Confira TZ do servidor.
7. Reprocessamento sem dry-run primeiro. Rodou pra período antigo e duplicou tudo.
FAQ
Posso desativar uma tarefa temporariamente?
Sim. Mas configure alerta no Slack pra lembrar.
Como debugar cron que falhou?
Veja o log da execução — geralmente tem stack trace. Rode dry-run pra reproduzir.
Posso rodar cron manualmente?
Sim — via UI ou CLI. Útil pra testar antes do horário automático.
Cron de mensalidade roda pra todos os clientes ao mesmo tempo?
Quaza divide em lotes (chunks) pra não sobrecarregar BD. Configurável.
Em qual horário é melhor agendar?
Madrugada (1-5h) — menor carga no sistema, menos impacto a usuários.
O que acontece se servidor reinicia durante cron?
Tarefa interrompe. Próxima execução pega o que faltou (se idempotente). Senão, recupere manualmente.
Posso adicionar tarefa customizada?
Sim — admin pode cadastrar script Python/PHP que vira cron.
Notificação em tempo real?
Configure webhook pra Slack/Discord/Teams. Falha = alerta imediato.
Documentos relacionados