Skip to main content
Este guia mostra o fluxo geral de geração e download da folha de pagamento via API. Para o schema exato dos parâmetros (nomes de campos, formato de retorno), consulte a Referência da API com try-it interativo.
Pré-requisito: o layout de exportação da sua folha precisa estar cadastrado no dashboard Pontua antes da primeira execução.

​
Visão geral do fluxo

1. POST /payment-sheet/export             ← dispara geração
   ↓ retorna identificador

2. GET /payment-sheet/export/{id}          ← polling até concluir

3. GET /payment-sheet/export/{id}/download ← obtém conteúdo

4. (Sua aplicação) Persiste arquivo + envia para sistema de folha

5. PATCH /payment-sheet/export/{id}/status/processed  ← marca como integrado
A última etapa fecha o ciclo de auditoria — marca como processado no lado da Pontua, evitando re-exportações acidentais.

​
Implementação geral

Os campos exatos do request/response variam por endpoint. Consulte a Referência interativa para os nomes corretos antes de implementar: 
async function puxarFolha(params) {
  const TOKEN = process.env.PONTUA_API_TOKEN
  const headers = {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  }

  // 1. Dispara export — body conforme schema na Referência
  const respostaDispatch = await fetch(
    'https://api.pontua.com.br/payment-sheet/export',
    { method: 'POST', headers, body: JSON.stringify(params) },
  )
  const exportData = await respostaDispatch.json()
  const exportId = exportData.id  // confira o nome exato no schema

  // 2. Polling com backoff até concluir
  for (let attempt = 0; attempt < 60; attempt++) {
    const status = await fetch(
      `https://api.pontua.com.br/payment-sheet/export/${exportId}`,
      { headers },
    ).then((r) => r.json())

    if (status.status === 'CONCLUIDO') break
    if (status.status === 'ERRO') {
      throw new Error(`Export falhou: ${JSON.stringify(status)}`)
    }

    const delay = Math.min(5000 * Math.pow(1.5, attempt), 60000)
    await new Promise((r) => setTimeout(r, delay))
  }

  // 3. Baixa
  const download = await fetch(
    `https://api.pontua.com.br/payment-sheet/export/${exportId}/download`,
    { headers },
  ).then((r) => r.json())

  // 4. Sua aplicação: decodifica + envia pro sistema de folha
  await sistemaDeFolha.importar(download)

  // 5. Marca como processado na Pontua
  await fetch(
    `https://api.pontua.com.br/payment-sheet/export/${exportId}/status/processed`,
    { method: 'PATCH', headers },
  )

  return { exportId, mes: params.mes }
}

​
Listar exports anteriores

GET /payment-sheet/export retorna a lista de exports gerados na UN, com status. Útil para:
  • Auditoria — quem disparou export quando
  • Re-download — pegar arquivo de mês anterior sem regenerar

​
Boas práticas

Rode em horário noturno

Geração de folha consolida todas as batidas + ajustes do mês — é trabalhoso. Faça em horário de baixa carga (22h–6h BRT).

Não disparar 2x o mesmo

A Pontua não dedup automaticamente — disparos repetidos geram exports diferentes. Cache o exportId do seu lado e cheque antes de retentar.

Não exporte com fechamento aberto

Cheque que o período está fechado antes de exportar — exportar com ajustes em curso pode gerar dados que mudam depois.

Guarde o arquivo no seu lado

Por questões fiscais, mantenha cópia do arquivo gerado pela API por pelo menos 5 anos no seu sistema. Não dependa só da Pontua para auditoria histórica.

​
Veja também