Levar holerites e relatórios para outro sistema

Com a folha aprovada ou paga, outros sistemas precisam dos números: o BI quer o custo por centro de custo, o arquivo digital guarda os holerites em PDF, o financeiro concilia as guias, a controladoria acompanha as provisões. Esta jornada lê tudo isso pela API, disparada pelo próprio ciclo da folha.

Quando usar	Holerites, resumos e relatórios da folha precisam chegar a um BI, a um arquivo de documentos ou a outro portal
Porta	REST · Automação/webhook (o gatilho) · Agente (MCP)
Você vai precisar	Módulo FOLHA_PAGAMENTO; permissão FOLHA (leitura); usuário de integração com token JWT

Como funciona

folha aprovada / paga ─► evento FOLHA_APROVADA ou FOLHA_PAGA
        │  webhook assinando o evento ─► seu sistema
        ▼
GET /folha/processamento?competencia=…&empresaId=…     ─► os processamentos do mês
GET /folha/resumo/{processamentoId}?analitica=true     ─► totais, quebras, uma linha por pessoa
GET /folha/holerite/processamento/{processamentoId}    ─► holerites (JSON)  ·  …/pdf (todos num PDF)

Passo a passo

1. Ache os processamentos da competência. Uma competência tem vários (mensal, adiantamento, férias, rescisão…):

   curl "https://api.taitecnologia.com/folha/processamento?competencia=2026-10&empresaId=3" \
     -H "Authorization: Bearer $TAI_TOKEN"

   Use só os que interessam pelo status — APROVADA, PAGA ou FECHADA têm os valores congelados — e guarde o id.

2. Leia o resumo gerencial — a melhor fonte para o BI:

   GET /folha/resumo/118?analitica=true

   Traz os totais (totalProventos, totalDescontos, totalLiquido, totalEncargosPatronais, totalFgts, custoTotal), as quebras por rubricas, departamentos e centrosCusto, o comparativo com a folha anterior do mesmo tipo, os alertas da conferência automática e colaboradores: uma linha por pessoa com cpf, matricula, cargo, centroCusto, proventos, descontos, líquido, INSS, IRRF, FGTS e encargos. Com analitica=true, cada pessoa vem com as suas verbas.

3. Leia os holerites.

   GET /folha/holerite/processamento/118        ← lista, com bases e totais de cada pessoa
   GET /folha/holerite/{id}                     ← um holerite com itens, memória de tributos e encargos

   Cada item do holerite traz a rubrica, a referência (quantidade, minutos, percentual), o valor e a origem (FIXO, VARIAVEL, PONTO, BANCO_HORAS, FERIAS…), com o id do lançamento ou do espelho de ponto que o gerou.

4. Baixe os PDFs, se o destino é um arquivo de documentos:

   Chamada	Devolve
   GET /folha/holerite/{id}/pdf	O demonstrativo de uma pessoa, em duas vias (empresa e empregado)
   GET /folha/holerite/processamento/{processamentoId}/pdf	Todos os holerites da folha num PDF, um por página, em ordem de nome
   GET /folha/resumo/{processamentoId}/pdf?analitica=true	A folha sintética (retrato) ou analítica (paisagem)

   Os PDFs são gerados na hora a partir dos valores congelados. Holerite de folha ainda não paga sai marcado como PRÉVIA.

Outros relatórios

Chamada	Para que serve
GET /folha/holerite/colaborador/{colaboradorId}/historico	Os holerites de uma pessoa em folhas pagas ou fechadas — para um portal próprio do colaborador
GET /folha/holerite/{id}/variacao	O que mudou em relação ao holerite anterior do mesmo tipo: líquido antes e agora, um resumo e as rubricas que mudaram, com o motivo de cada uma
GET /folha/holerite/{id}/explicacao	A mesma variação em linguagem simples, redigida por IA e conferida contra os valores (nome e CPF não vão para a IA)
GET /folha/informe-rendimentos/colaborador/{colaboradorId}?ano=2026	O informe de rendimentos de uma pessoa (ano de pagamento); …/pdf em PDF
GET /folha/informe-rendimentos/empresa/{empresaId}/pdf?ano=2026	Os informes de toda a empresa num PDF, um por página
GET /folha/obrigacao?empresaId=3&competencia=2026-10	As guias da competência (FGTS, previdenciária, IRRF…) com a composição de cada valor, vencimento e status
GET /folha/obrigacao/pendencias?empresaId=3	O que falta pagar, o que venceu e o que foi pago com valor divergente
GET /folha/provisao?empresaId=3&competencia=2026-10	As provisões de férias e 13º (1/12, 1/3 e encargos), com centro de custo para rateio
GET /folha/resumo/conciliacao-provisao?empresaId=3&competenciaAte=2026-10	Provisionado × pago; …/pdf em PDF

Automatize

Para o seu sistema buscar os relatórios na hora certa, crie um webhook assinando A folha é aprovada (FOLHA_APROVADA) — um aviso por processamento:

{
  "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 o processamentoId, faça os passos 2 a 4. Se o destino é o arquivo de holerites definitivos, assine A folha é encerrada (FOLHA_PROCESSAMENTO_FECHADO), com os mesmos campos: a folha encerrada não muda mais. Para conciliar as guias, Uma guia da folha é paga (OBRIGACAO_FOLHA_PAGA) traz obrigacaoId, tipo, competencia, dataPagamento e valorPago.

Não há rotina que empurre holerites para fora: a TAI os entrega ao próprio colaborador em Meus holerites, e o seu sistema busca o que precisa.

Pelo seu agente de IA

“Qual foi o custo total da folha de outubro por centro de custo, comparado com setembro?”

O agente lê o resumo gerencial e responde com os números da folha — só leitura. Para gerar os PDFs, ele usa a ferramenta gerar_arquivo, que devolve um link de download válido por 15 minutos (Ferramentas).

Cuidados

• Valores congelados só depois da aprovação. Uma folha CALCULADA ou EM_REVISAO ainda pode ser recalculada; leia a partir de APROVADA.
• Três números diferentes. Proventos, líquido e custo total não são o mesmo número — o custo inclui encargos patronais e FGTS, que não aparecem no holerite.
• Dados pessoais. Holerites e o resumo analítico trazem salário e CPF: dê ao usuário de integração só a permissão FOLHA de leitura e proteja o destino.
• PDFs grandes demoram. O PDF de todos os holerites e os informes da empresa podem levar dezenas de segundos — use tempo limite de 60 segundos (Limites).