Relatório é frequentemente o principal driver de quem integra
com a Pontua — contadores, escritórios e ERPs precisam puxar dados
consolidados em formatos específicos para folha, fiscalização ou auditoria.
Como funciona
Geração de relatório é assíncrona em três etapas:Endpoints principais
Geração
| Método | Rota | Tipo de relatório |
|---|---|---|
| POST | /relatorio/afd | AFD (Portaria 671) |
| POST | /relatorio/aej | AEJ (Arquivo Eletrônico de Jornada) |
| POST | /relatorio/espelho-ponto | Espelho de Ponto |
| POST | /relatorio/banco-horas | Banco de Horas |
| POST | /relatorio/horas-extras | Horas Extras |
| POST | /relatorio/horas-extras-an | Horas Extras (Analítico) |
| POST | /relatorio/localizacoes | Auditoria GPS |
| POST | /relatorio/faltas-atrasos-antecipacoes | Faltas, Atrasos, Antecipações |
| POST | /relatorio/eventos-folha-pagamento | Eventos para folha de pagamento |
Gestão
| 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 de download |
| DELETE | /relatorio/{relatorioId} | Remove (não-recuperável) |
Padrão geral de polling
Os campos exatos do body (status enum, formato de retorno do download)
podem variar por endpoint e estão documentados na Referência. Cheque o
schema antes de implementar pra cada tipo.
Boas práticas
Não bloqueie a thread esperando
Polling síncrono em loop é antipattern. Salve o
relatorioId em fila/DB,
processe em worker separado quando concluir.Cache do `relatorioId` para retry
Se a etapa de download falhar, não regenere o relatório — use o mesmo
relatorioId para tentar baixar de novo. Geração custa caro
(CPU + I/O no banco).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.
Veja também
- Idempotência — evitar dispatches duplicados em retry
- Frequência — agregados diários (alternativa para casos simples)