Skip to main content
A tag Relatório é frequentemente o principal driver de quem integra com o Pontua: contadores, escritórios e ERPs precisam puxar dados consolidados em formatos específicos para folha de pagamento, fiscalização do MTE, ou auditoria interna.

Como funciona

Geração de relatório é assíncrona em três etapas — não tente fazer em uma chamada só:
1. POST /relatorio/<tipo>           ← dispara geração
   ↓ retorna { relatorioId, status: "PROCESSANDO" }

2. GET /relatorio/{relatorioId}     ← polling até concluir
   ↓ status muda para "CONCLUIDO" ou "ERRO"

3. POST /relatorio/download         ← obtém URL ou base64
   ↓ retorna conteúdo final
Por que assíncrono? Relatórios consolidam dezenas de milhares de registros, calculam horas extras com regras CLT complexas, e geram arquivos com assinatura digital — operação CPU-intensiva que não cabe em um request HTTP síncrono.

Tipos de relatório

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
Saída: arquivo .txt assinado digitalmente (CAdES detached .p7s junto). Encoding ISO 8859-1, não UTF-8 — abrir em editor que respeite encoding.
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
Saída: .txt assinado, encoding ISO 8859-1.
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)
Saída: PDF assinado.
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
Saída: PDF ou CSV.
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
Saída: PDF ou CSV.
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
Quando usar:
  • Auditoria fina de cálculos
  • Validação em processo trabalhista
  • Justificativa de divergências entre Pontua e folha externa
Saída: CSV (estrutura tabular para análise).
POST /relatorio/localizacoesO que é: auditoria GPS das batidas — coordenadas, distância do cerco, dispositivo usado.
LGPD pesado. Localização é dado pessoal sensível. Gerar esse relatório requer base legal documentada (acordo trabalhista, consentimento explícito). Não exporte para uso amplo.
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)
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
Saída: PDF ou CSV.
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
Saída: TXT no layout pré-cadastrado. Encoding e separadores seguem o layout escolhido.Ver guia Puxar folha do mês.

Endpoints

Geração e gestão

MétodoRotaDescrição
POST/relatorio/afdGera AFD Portaria 671
POST/relatorio/aejGera AEJ
POST/relatorio/espelho-pontoGera espelho de ponto
POST/relatorio/banco-horasGera relatório de banco de horas
POST/relatorio/horas-extrasGera relatório de horas extras
POST/relatorio/horas-extras-anVersão analítica de HE com adicional noturno
POST/relatorio/localizacoesAuditoria GPS (LGPD)
POST/relatorio/faltas-atrasos-antecipacoesFaltas, atrasos, antecipações
POST/relatorio/eventos-folha-pagamentoEventos consolidados para folha

Listagem, status e download

MétodoRotaDescrição
GET/relatorioLista relatórios gerados (com filtros)
GET/relatorio/{relatorioId}Status + metadata de um relatório
POST/relatorio/downloadObter URL/conteúdo do download
DELETE/relatorio/{relatorioId}Remove (não-recuperável)
Schema completo + try-it em Referência da API.

Padrão geral de polling

async function gerarRelatorio(token, tipo, params, opts = {}) {
  const headers = {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  }

  // 1. Dispara geração
  const dispatchResp = await fetch(
    `https://api.pontua.com.br/relatorio/${tipo}`,
    { method: 'POST', headers, body: JSON.stringify(params) },
  )
  if (!dispatchResp.ok) throw new Error(await dispatchResp.text())
  const { relatorioId } = await dispatchResp.json()

  // 2. Polling com backoff exponencial até concluir
  const maxTentativas = opts.maxTentativas ?? 60
  for (let i = 0; i < maxTentativas; i++) {
    const status = await fetch(
      `https://api.pontua.com.br/relatorio/${relatorioId}`,
      { headers },
    ).then((r) => r.json())

    if (status.status === 'CONCLUIDO') break
    if (status.status === 'ERRO') {
      throw new Error(`Geração falhou: ${status.mensagemErro || 'desconhecido'}`)
    }

    // 5s, 10s, 20s, 40s, capped em 60s
    const delayMs = Math.min(5000 * Math.pow(1.5, i), 60000)
    await new Promise((r) => setTimeout(r, delayMs))
  }

  // 3. Baixa
  const downloadResp = await fetch(
    'https://api.pontua.com.br/relatorio/download',
    { method: 'POST', headers, body: JSON.stringify({ relatorioId }) },
  )
  return downloadResp.json()
}

// Exemplo de uso
const url = await gerarRelatorio(TOKEN, 'banco-horas', {
  dataInicio: '2026-04-01',
  dataFim: '2026-04-30',
  formato: 'CSV',
})

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

Esses arquivos seguem a especificação da Portaria 671 que exige ISO 8859-1 (latin1). Se sua aplicação espera UTF-8, vai ver caracteres acentuados quebrados (“ç”, “ã” como ?). Sempre decode como latin1/iso-8859-1 ao processar.
DELETE /relatorio/{id} apaga o arquivo + metadata. Para auditoria Portaria 671 (Art. 98 — retenção 5 anos), evite deletar e prefira filtrar nas listagens.
Se você gera relatório de mês ainda não fechado, ajustes posteriores no período podem fazer um relatório futuro divergir. Para snapshot imutável, gere após POST /fechamento concluir — ver Fechamento.
POST /relatorio/eventos-folha-pagamento falha se a UN não tem layout configurado. Cadastre o layout primeiro em Folha de Pagamento (via dashboard ou API se exposta para o caso).

Veja também