Como funciona
Geração de relatório é assíncrona em três etapas — não tente fazer em uma chamada só:Tipos de relatório
AFD — Arquivo Fonte de Dados (Portaria 671)
AFD — Arquivo Fonte de Dados (Portaria 671)
POST /relatorio/afdO que é: o arquivo bruto exigido pelo MTE em fiscalização. Contém
todas as marcações brutas do REP-P do período, com NSR sequencial,
formato ISO 8859-1, estrutura tipo 1/3/99.Quando usar:- Fiscalização do MTE (agente fiscal solicita “AFD do período X”)
- Auditoria interna ou de terceiro
- Anexar em processo trabalhista
.txt assinado digitalmente (CAdES detached .p7s
junto). Encoding ISO 8859-1, não UTF-8 — abrir em editor que
respeite encoding.AEJ — Arquivo Eletrônico de Jornada
AEJ — Arquivo Eletrônico de Jornada
POST /relatorio/aejO que é: versão consolidada do AFD que agrega marcações em
jornadas (entrada/saída pareadas) com cálculo de horas
trabalhadas, ausências, horas extras. Estrutura tipo 01-08 + 99
conforme Portaria 671.Quando usar:- Auditoria mais legível que AFD bruto
- Compliance específico que exige jornada calculada (não só batidas)
- Anexar em fechamento mensal
.txt assinado, encoding ISO 8859-1.Espelho de Ponto
Espelho de Ponto
POST /relatorio/espelho-pontoO que é: PDF formatado com a jornada individual ou da equipe
no período. Mostra batidas, jornada esperada, horas extras, atrasos —
ideal para conferência.Quando usar:- Conferência mensal antes de fechar folha
- Anexar em recibo de pagamento
- Validação assinada pelo colaborador (PAdES embed)
Banco de Horas
Banco de Horas
POST /relatorio/banco-horasO que é: saldos e movimentações de banco de horas no período.
Mostra entradas (horas extras acumuladas), saídas (compensações,
abonos), saldo final, e prazo de prescrição (caducidade) por
colaborador.Quando usar:- Conferência de saldos antes de quitação em folha
- Auditoria de banco de horas vencido (Art. 59 CLT — Lei 13.467/2017)
- Relatório para acordo coletivo de banco de horas
Horas Extras
Horas Extras
POST /relatorio/horas-extrasO que é: consolidado de horas extras por colaborador no período,
com percentuais aplicados (50% dia útil, 100% domingo/feriado) e
valores estimados.Quando usar:- Folha mensal — entrada de eventos de hora extra
- Comparação com estimativa orçamentária
- Relatório executivo de custo de HE
Horas Extras Analítico (com Adicional Noturno)
Horas Extras Analítico (com Adicional Noturno)
POST /relatorio/horas-extras-anO que é: versão detalhada do anterior incluindo:- Adicional noturno (CLT Art. 73 — período 22h-5h, hora ficta 52’30”, coeficiente 1.142857)
- Detalhamento por dia, jornada, faixa
- Memória de cálculo
- Auditoria fina de cálculos
- Validação em processo trabalhista
- Justificativa de divergências entre Pontua e folha externa
Localizações (LGPD)
Localizações (LGPD)
POST /relatorio/localizacoesO que é: auditoria GPS das batidas — coordenadas, distância do
cerco, dispositivo usado.Quando usar:- Auditoria de fraude pontual (suspeita de batida fora do trabalho)
- Resposta a solicitação do MTE com base em denúncia
- Atendimento a Art. 18 LGPD do colaborador (acesso a dados próprios)
Faltas, Atrasos e Antecipações
Faltas, Atrasos e Antecipações
POST /relatorio/faltas-atrasos-antecipacoesO que é: consolidado de irregularidades de presença por
colaborador — quantidade de faltas, atrasos, antecipações de saída,
com totais em horas.Quando usar:- Folha — descontos por falta/atraso
- Relatório disciplinar ou advertência
- BI de absenteísmo
Eventos para Folha de Pagamento
Eventos para Folha de Pagamento
POST /relatorio/eventos-folha-pagamentoO que é: arquivo TXT no layout específico do seu sistema de
folha (configurado previamente em Folha de Pagamento).
Contém eventos consolidados (proventos, descontos) prontos para
importação.Quando usar:- Sync automático mensal Pontua → folha externa
- Top use case para contadores e ERPs
Endpoints
Geração e gestão
| Método | Rota | Descrição |
|---|---|---|
| POST | /relatorio/afd | Gera AFD Portaria 671 |
| POST | /relatorio/aej | Gera AEJ |
| POST | /relatorio/espelho-ponto | Gera espelho de ponto |
| POST | /relatorio/banco-horas | Gera relatório de banco de horas |
| POST | /relatorio/horas-extras | Gera relatório de horas extras |
| POST | /relatorio/horas-extras-an | Versão analítica de HE com adicional noturno |
| POST | /relatorio/localizacoes | Auditoria GPS (LGPD) |
| POST | /relatorio/faltas-atrasos-antecipacoes | Faltas, atrasos, antecipações |
| POST | /relatorio/eventos-folha-pagamento | Eventos consolidados para folha |
Listagem, status e download
| Método | Rota | Descrição |
|---|---|---|
| GET | /relatorio | Lista relatórios gerados (com filtros) |
| GET | /relatorio/{relatorioId} | Status + metadata de um relatório |
| POST | /relatorio/download | Obter URL/conteúdo do download |
| DELETE | /relatorio/{relatorioId} | Remove (não-recuperável) |
Padrão geral de polling
Boas práticas
Não bloqueie thread esperando
Polling síncrono em loop é antipattern. Salve o
relatorioId em
fila/DB e processe em worker separado. Para datasets grandes, geração
pode levar minutos.Cache do relatorioId pra retry de download
Se a etapa 3 (download) falhar, não regenere o relatório —
use o mesmo
relatorioId para tentar baixar novamente. Geração custa
caro (CPU + I/O no banco + assinatura digital).Filtre o máximo possível na geração
Não gere “AEJ do ano todo de toda a empresa” se você só precisa de
um departamento de um mês. Filtros antes de gerar = relatórios
menores + mais rápidos + menos pressão no banco.
Persista os arquivos do seu lado
URLs S3 do
download têm TTL configurado. Para auditoria histórica
(5 anos para registros de ponto, 10 anos para folha), baixe
imediatamente e guarde em storage próprio.Gotchas conhecidos
Veja também
- Puxar folha do mês — fluxo completo de export
- Gerar relatório de banco de horas — polling + download
- Idempotência — evitar dispatches duplicados em retry
- Frequência — agregados em tempo real (alternativa pra casos simples)
- Banco de Horas — saldos consolidados por ciclo
- Fechamento — quando relatórios ficam “definitivos”