Levar o ponto fechado para a folha de outro sistema

A empresa bate ponto na TAI, mas a folha roda em outro sistema. Quando o mês do ponto fecha, o sistema de folha precisa dos números congelados de cada pessoa — horas extras por percentual, faltas, atrasos, adicional noturno, banco de horas — para lançar as verbas. Esta jornada leva esses números da TAI para lá, disparada pelo próprio fechamento.


Quando usar	A folha de pagamento é feita fora da TAI (ERP, sistema de folha, escritório contábil) e consome o ponto fechado
Porta	Webhook (o aviso) · REST (a leitura) · Agente (MCP)
Você vai precisar	Módulo `PONTO`; permissão `PONTO` para fechamentos e espelhos; `PONTO_EQUIPE` para o banco de horas da folha; `PONTO_EXPORTAR` para AFD e AEJ; usuário de integração com token JWT

Como funciona

todo dia, de madrugada ─► ponto-apuracao-diaria apura o dia anterior
fim do mês ─► fechamento (à mão ou ponto-fechamento-automatico)
                 congela o espelho de cada pessoa e movimenta o banco de horas
                        │
                        ▼
          evento PONTO_COMPETENCIA_FECHADA (fechamentoId, competencia)
                        │  webhook assinando o evento
                        ▼
          seu sistema recebe dados.fechamentoId e dados.competencia
                        │
                        ▼
          GET /ponto/fechamento/{id}/espelhos  +  GET /ponto/banco-horas/folha
                        │
                        ▼
          verbas lançadas na folha do seu sistema

O fechamento vale para a conta inteira: uma competência (AAAA-MM) fecha uma vez para todas as empresas do ponto. Depois de fechada, os números não mudam mais — a não ser que o dono da conta ou um administrador reabra o mês.

Passo a passo

Ache o fechamento da competência. Se a chamada veio do webhook, você já tem o fechamentoId. Senão, liste os fechamentos e pegue o da competência com status FECHADA:
Terminal window
```
curl https://api.taitecnologia.com/ponto/fechamento \
  -H "Authorization: Bearer $TAI_TOKEN"
```
```
[
  { "id": 41, "competencia": "2026-09", "status": "FECHADA",
    "dataFechamento": "2026-10-05 03:00:12", "fechadoPor": "fechamento automático (TAI)" }
]
```
Uma competência reaberta aparece com status REABERTA; ao fechar de novo, nasce outro fechamento, com outro id.

Leia os espelhos congelados. Uma linha por pessoa, com tudo em minutos:

curl https://api.taitecnologia.com/ponto/fechamento/41/espelhos \
  -H "Authorization: Bearer $TAI_TOKEN"

[
  {
    "colaboradorId": 812,
    "colaboradorNome": "Ana Ribeiro",
    "competencia": "2026-09",
    "minutosPrevistos": 10560,
    "minutosTrabalhados": 10890,
    "minutosAtraso": 25,
    "minutosFalta": 0,
    "diasFalta": 0,
    "diasDsrPerdido": 0,
    "minutosNoturnoConvertido": 0,
    "minutosIntervaloSuprimido": 30,
    "reflexoDsrHeMinutos": 48,
    "bancoHabilitado": true,
    "creditosBanco": 120,
    "debitosBanco": 0,
    "saldoBancoFinal": 340,
    "extras": [
      { "percentual": 50, "minutos": 210, "destino": "PAGAR" },
      { "percentual": 100, "minutos": 120, "destino": "BANCO" }
    ]
  }
]

O espelho traz o colaboradorId da TAI, não o CPF nem a matrícula. Para casar com o seu sistema, busque o colaborador uma vez (GET /colaborador/{id}, campos cpf e codigoFuncionario) e guarde a correspondência — veja o guia de Pessoas.

Leia o que o banco de horas manda para a folha. Quitações feitas pelo RH (PAGAMENTO) e créditos vencidos pagos no fechamento (EXPIRACAO_PAGA):
Terminal window
```
curl "https://api.taitecnologia.com/ponto/banco-horas/folha?competencia=2026-09" \
  -H "Authorization: Bearer $TAI_TOKEN"
```
Cada movimento traz colaboradorId, tipo, minutos e competenciaFolha. Um movimento com referenciaExterna (HOLERITE:<id>) já foi pago numa rescisão — não pague de novo.

Lance as verbas no seu sistema. É assim que a folha da própria TAI lê o espelho — use como referência para o seu mapeamento de rubricas:

No espelho	Vira na folha
`extras[]` com `destino` `PAGAR`	Hora extra no `percentual` da linha (50, 60, 100…)
`extras[]` com `destino` `BANCO`	Nada — os minutos foram creditados no banco de horas
`minutosNoturnoConvertido`	Adicional noturno (só o adicional)
`minutosIntervaloSuprimido`	Indenização do intervalo não usufruído (Art. 71 §4º)
`reflexoDsrHeMinutos`	DSR sobre horas extras
`diasFalta`, `minutosAtraso`	Desconto de faltas e atrasos — só quando `debitosBanco` é zero; com débito no banco, a regra já descontou do banco
`diasDsrPerdido`	Desconto do DSR perdido
`PAGAMENTO` e `EXPIRACAO_PAGA` do passo 3	Horas do banco pagas na folha

(Opcional) Baixe os documentos do mês. Os espelhos em PDF de todos, num ZIP, para arquivar ou mandar assinar:
```
GET /ponto/fechamento/espelhos-pdf?competencia=2026-09
```
E os arquivos fiscais por empresa do ponto (empregadorId vem de GET /ponto/empregador), período de até 366 dias, datas em yyyy-MM-dd:
- Para a fiscalização
- Sem assinatura
GET /ponto/afd/assinado?empregadorId=3&dataInicio=2026-09-01&dataFim=2026-09-30 GET /ponto/aej/assinado?empregadorId=3&dataInicio=2026-09-01&dataFim=2026-09-30
Cada um devolve um ZIP com o .txt e o .txt.p7s (assinatura digital da TAI). Responde 400 se a assinatura estiver indisponível no momento.
GET /ponto/afd?empregadorId=3&dataInicio=2026-09-01&dataFim=2026-09-30 GET /ponto/aej?empregadorId=3&dataInicio=2026-09-01&dataFim=2026-09-30
Texto puro (ISO-8859-1, CRLF), útil para validar o leiaute num leitor de mercado.
Antes do AEJ, GET /ponto/aej/prontidao (mesmos parâmetros) diz se o período está congelado ou quantos dias ainda podem mudar, nomeando pessoa e dia.

Antes do fechamento: prévia e totais

Para acompanhar o mês ainda aberto, ou saber o que trava o fechamento:

Chamada	Devolve
`GET /ponto/fechamento/previa?competencia=2026-10`	`podeFechar`, `bloqueios` e `alertas` em texto, dias inconsistentes, correções e ausências pendentes
`GET /ponto/apuracao/totais-periodo?dataInicio=2026-10-01&dataFim=2026-10-31`	Uma linha por pessoa com extras, atrasos, faltas, noturno e banco do período, em minutos e em `horasExtras` formatado
`GET /ponto/mes?competencia=2026-10`	O mês em cinco etapas, com o que precisa de alguém e a prévia do fechamento

Os totais do mês aberto ainda mudam a cada recálculo. Para lançar na folha, use sempre o espelho do fechamento.

Automatize

O que a TAI já faz sozinha:

ponto-apuracao-diaria apura, de madrugada, o dia anterior de todo mundo.
ponto-previa-fechamento avisa os gestores das pendências antes do fechamento.
ponto-fechamento-automatico fecha a competência no dia escolhido, às 03:00, se nada travar. Ligue em Departamento Pessoal › Ponto › Configurações › Automações › Fechar o mês sozinho, ou pela API:
```
PUT /ponto/config-tenant

{ "fecharAutomatico": true, "diaFechamentoAutomatico": 5 }
```
Se algo travar, o mês não fecha e nada é enviado — o fechamento automático nunca contorna um bloqueio.

Para o seu sistema saber que o mês fechou, crie um webhook em Processos › Central de Automações › Webhooks com o endereço da folha e assine:

Evento	Para a folha
O ponto do mês é fechado (`PONTO_COMPETENCIA_FECHADA`)	Ler os espelhos e lançar as verbas
O ponto do mês é reaberto (`PONTO_COMPETENCIA_REABERTA`)	Suspender o lançamento da competência até ela fechar de novo
O banco de horas de alguém é pago (`BANCO_HORAS_QUITADO`)	Saber que há horas do banco a pagar na `competenciaFolha`
O ciclo do banco de horas é encerrado (`BANCO_HORAS_CICLO_ENCERRADO`)	Idem, para todos os saldos pagos no encerramento

Os dois do banco de horas só avisam: os minutos a pagar continuam sendo lidos uma vez, em GET /ponto/banco-horas/folha (passo 3), para não lançar a mesma quitação duas vezes.

O fechamento chega assim:

{
  "id": "evt_57610",
  "tipo": "PONTO_COMPETENCIA_FECHADA",
  "descricao": "O ponto do mês é fechado",
  "versao": 1,
  "ocorridoEm": "2026-10-05T06:00:12.481Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "fechamentoId": 41,
    "competencia": "2026-09"
  }
}

Ao receber, responda 2xx na hora e faça os passos 2 a 4 numa fila sua — a chamada tem até 30 segundos. Com o seu sistema fora, a TAI tenta de novo por cerca de 21 horas, com o mesmo X-Tai-Entrega (Entregas e novas tentativas).

Quando o lançamento na folha precisa de alguém que confira antes, um fluxo de Processos pode ouvir O ponto do mês é fechado e abrir um card por competência, com responsável e prazo — veja Da TAI para o seu sistema.

Pelo seu agente de IA

“Quem fez mais hora extra em setembro e quanto? E o ponto de setembro já fechou?”

O agente consulta os totais do período e a lista de fechamentos — só leitura. Fechar ou reabrir o mês são ações de confirmação forte: o agente externo não as executa pelo MCP (Escrita e segurança); faça-as na plataforma ou pela Tali.

Cuidados

Leia o espelho, não a apuração. Só o espelho do fechamento é definitivo. Totais do mês aberto servem para acompanhamento.
Idempotência pelo fechamentoId. Grave o fechamentoId processado. Se o mês for reaberto e fechado de novo, chega O ponto do mês é reaberto e, depois, outro O ponto do mês é fechado com outro fechamentoId — trate como substituição da competência, não como um segundo mês.
Reabertura tem limite. O mês do ponto não reabre se a folha da TAI daquela competência já foi aprovada; se ela já foi paga, o ponto do mês fica definitivo. Correções entram no mês seguinte.
Alcance do usuário. GET /ponto/fechamento/{id}/espelhos devolve todos os espelhos para quem tem PONTO. Já GET /ponto/banco-horas/folha e GET /ponto/apuracao/totais-periodo devolvem só as pessoas que o usuário enxerga — os liderados pela estrutura, ou todos para o dono da conta e administradores. Confira se o usuário de integração alcança todo mundo.
Minutos, não horas. Os campos minutos* são inteiros em minutos; converta no seu lado.
Competência é AAAA-MM e datas de período são yyyy-MM-dd — veja Datas e formatos.
Arquivos grandes demoram. O ZIP de espelhos e os arquivos fiscais podem levar dezenas de segundos — configure tempo limite de 60 segundos (Limites).

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