Conduzir o ciclo da competência

Cada folha da TAI percorre um ciclo: abrir, calcular, conferir, aprovar, pagar e fechar. Esta jornada mostra as chamadas de cada etapa e, principalmente, como o seu sistema fica sabendo de cada uma — para o financeiro provisionar o pagamento quando a folha é aprovada, o banco receber a remessa e o BI atualizar o custo do mês.


Quando usar	O financeiro, o banco ou um painel externo dependem das etapas da folha; ou um orquestrador seu conduz o ciclo
Porta	Automação/webhook (os avisos) · REST (as etapas) · Agente (MCP, leitura)
Você vai precisar	Módulo `FOLHA_PAGAMENTO`; `FOLHA_PROCESSAR` para abrir, calcular, revisar, cancelar e gerar remessa; `FOLHA_APROVAR` para aprovar, pagar, fechar e reabrir; usuário de integração com token JWT

Como funciona

ABERTA ─calcular─► CALCULADA ─revisar─► EM_REVISAO ─aprovar─► APROVADA ─pagar─► PAGA ─fechar─► FECHADA
   │                  │  ▲                                        │
   │                  └──┘ recalcular                             └─reabrir─► REABERTA ─calcular─► …
   └─ cancelar (de ABERTA, ERRO ou CALCULADA)

eventos:  FOLHA_PROCESSAMENTO_ABERTO · FOLHA_CALCULADA · FOLHA_APROVADA · FOLHA_PAGA
          FOLHA_PROCESSAMENTO_FECHADO · FOLHA_PROCESSAMENTO_REABERTO · FOLHA_PROCESSAMENTO_CANCELADO
          REMESSA_FOLHA_ENVIADA · REMESSA_FOLHA_RETORNO_PROCESSADO
                  │
                  └──► webhook assinando os eventos ─► seu sistema (assinado, com novas tentativas)

EM_REVISAO só existe quando a empresa exige revisão (exigirRevisao na configuração da folha); sem ela, a folha calculada vai direto para aprovação.

Passo a passo

Confira a prontidão da empresa antes da primeira folha (e sempre que entrar gente nova):
```
GET /folha/preparacao/prontidao/empresa/3
```
apto diz se dá para rodar; checksEmpresa e colaboradores listam o que falta (salário vigente, CPF, PIS, dados bancários…). Exige FOLHA_CADASTRO.
Abra a folha da competência.
Terminal window
```
curl -X POST https://api.taitecnologia.com/folha/processamento \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "empresaId": 3, "competencia": "2026-10", "tipo": "MENSAL",
        "dataPagamentoPrevista": "2026-11-05" }'
```
Guarde o id do processamento. Existe um processamento ativo por empresa, competência e tipo — a mesma competência costuma ter vários: ADIANTAMENTO, MENSAL, FERIAS, RESCISAO. A dataPagamentoPrevista decide a tabela de IRRF (o imposto segue o regime de caixa).
Calcule.
```
POST /folha/processamento/{id}/calcular
```
A resposta traz os totais (totalProventos, totalDescontos, totalLiquido, totalEncargosPatronais, totalFgts) e qtdColaboradoresErro. Os holerites com problema aparecem em GET /folha/holerite/processamento/{id} com status ERRO e mensagemErro. A folha mensal exige o ponto do mês fechado quando a empresa tem exigirPontoFechado (o padrão). Recalcular é seguro enquanto a folha não foi aprovada.
Confira e aprove. O resumo gerencial compara com a folha anterior e lista os achados da conferência automática:
```
GET /folha/resumo/{id}
POST /folha/processamento/{id}/revisar     ← só quando a empresa exige revisão
POST /folha/processamento/{id}/aprovar
```
A aprovação é recusada enquanto houver holerite em erro.
Pague. Registra o pagamento e gera os pagamentos por favorecido:
```
POST /folha/processamento/{id}/pagar

{ "dataPagamento": "2026-11-05" }
```
Sem dataPagamento, vale a data de hoje.

(Opcional) Gere a remessa bancária. Com a folha paga, a prévia mostra quem entra no arquivo e quem fica de fora, com o motivo; a geração produz o CNAB 240:

GET  /folha/remessa/previa/{processamentoId}?contaId=2
POST /folha/remessa/gerar
{ "processamentoId": 118, "contaId": 2, "dataPagamento": "2026-11-05" }

GET  /folha/remessa/{id}/arquivo            ← o arquivo para o banco
POST /folha/remessa/{id}/enviada            ← marque quando entregar ao banco
POST /folha/remessa/{id}/retorno            ← o arquivo de retorno (multipart, campo arquivo)

A geração recusa se houver pagamento sem condição de ir ao banco; com "ignorarBloqueados": true, leva só os aptos. Processar o mesmo retorno duas vezes não muda o resultado.

Feche.
```
POST /folha/processamento/{id}/fechar
```

Automatize

O que a TAI já faz sozinha, conforme a configuração da folha de cada empresa (PUT /folha/config/empresa/{empresaId}, permissão FOLHA_CADASTRO):

folha-automatica — com folhaAutomatica ligado, a partir do dia diaFolhaAutomatica (padrão 25) abre a folha mensal da competência, se ainda não existir, e a calcula de madrugada; recalcula quando entram variáveis aprovadas. Com adiantamentoAutomatico (e o adiantamento habilitado), abre e calcula também o adiantamento no dia do adiantamento. Nunca aprova nem paga.
apurarGuiasAoAprovar — ao aprovar, apura as guias da competência (também disponível sob demanda em POST /folha/obrigacao/apurar?empresaId=3&competencia=2026-10).
gerarEsocialAoPagar — ao pagar, gera os eventos periódicos do eSocial (veja eSocial).
folha-guardiao-prazos (começa desligada) — avisa por e-mail quem processa a folha dos prazos de guias, rescisões, salário do mês, fechamento do eSocial e 13º.

Avisar o seu sistema a cada etapa

Para o seu sistema acompanhar o ciclo, crie um webhook em Processos › Central de Automações › Webhooks › Novo webhook e marque os eventos da etapa que interessa — ou o módulo inteiro (Tudo de Folha de pagamento). Um exemplo comum: quando a folha é aprovada, o ERP financeiro provisiona o pagamento. Assinando A folha é aprovada (FOLHA_APROVADA), chega:

{
  "id": "evt_51877",
  "tipo": "FOLHA_APROVADA",
  "descricao": "A folha é aprovada",
  "versao": 1,
  "ocorridoEm": "2026-11-03T18:22:10.512Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "processamentoId": 118,
    "empresaId": 3,
    "competencia": "2026-10",
    "tipo": "MENSAL"
  }
}

Com Enviar também o registro completo, o envio leva junto, em registro, o processamento como GET /folha/processamento/{id} o devolve — com os totais. Sem ele, o seu sistema lê os totais nessa rota e as guias em GET /folha/obrigacao?empresaId=…&competencia=…. Confira a assinatura e use X-Tai-Entrega para não processar duas vezes.

Etapa	Evento
Folha aberta (pela pessoa ou pela folha automática)	`FOLHA_PROCESSAMENTO_ABERTO`
Cálculo ou recálculo — traz `holeritesComErro`	`FOLHA_CALCULADA`
Aprovação	`FOLHA_APROVADA`
Reabertura de uma folha aprovada	`FOLHA_PROCESSAMENTO_REABERTO`
Cancelamento de uma folha não aprovada	`FOLHA_PROCESSAMENTO_CANCELADO`
Pagamento registrado	`FOLHA_PAGA`
Folha encerrada	`FOLHA_PROCESSAMENTO_FECHADO`
Remessa marcada como enviada ao banco	`REMESSA_FOLHA_ENVIADA`
Retorno do banco lido — traz `qtdConfirmados` e `qtdRejeitados`	`REMESSA_FOLHA_RETORNO_PROCESSADO`
Guia da folha paga ou cancelada	`OBRIGACAO_FOLHA_PAGA`, `OBRIGACAO_FOLHA_CANCELADA`

Para avisar num formato próprio — uma mensagem no Slack, por exemplo —, ou junto de outras ações, use um fluxo automatizado (Processos › Fluxos › Novo processo › Fluxo automatizado) que começa por Quando algo acontece com o evento e segue para o bloco Chamar outro sistema; o Corpo (JSON) usa os dados do evento:

{
  "text": "Retorno do banco: {{gatilho.qtdConfirmados}} pagamentos confirmados e {{gatilho.qtdRejeitados}} rejeitados"
}

Veja Da TAI para o seu sistema para escolher entre os caminhos.

Pelo seu agente de IA

“Como está a folha de outubro da empresa matriz? Tem alguém com erro?”

O agente lê a competência (/folha/mes), os processamentos e os holerites com erro — só leitura. Calcular, aprovar, pagar, fechar e reabrir são de confirmação forte: o agente externo não os executa pelo MCP (Escrita e segurança). Essas etapas ficam na plataforma, na Tali ou na sua integração REST.

Cuidados

“Folha paga” avisa uma vez por empresa e competência. O evento Folha paga não traz o tipo nem o processamento: pagar a segunda folha da mesma competência (o adiantamento e depois a mensal, por exemplo) não dispara de novo. Se o seu sistema precisa de cada pagamento, use o evento Folha aprovada (um por processamento) ou consulte GET /folha/processamento?competencia=… e olhe status e dataPagamentoEfetiva.
Reaprovar não avisa de novo. Folha aprovada é identificado pelo processamento: reabrir e aprovar a mesma folha não dispara outra vez — a reabertura chega como Uma folha é reaberta. Folha calculada, Uma folha é reaberta e O banco devolve o retorno do pagamento disparam a cada vez que acontecem.
Folha paga não reabre. PAGA e FECHADA nunca voltam; só APROVADA reabre.
Ponto antes da folha. Com exigirPontoFechado, calcular a mensal antes de fechar o ponto responde 400 — veja Ponto eletrônico.
Cálculo demora. Calcular uma folha grande leva dezenas de segundos — use tempo limite de 60 segundos (Limites).
Competência AAAA-MM, datas yyyy-MM-dd (Datas e formatos).

Referência gerada do contrato da API em 30 de outubro de 2026. taitecnologia.com · Termos de uso · Privacidade