> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pontua.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Puxar folha do mês

> Fluxo geral de POST /payment-sheet/export para gerar arquivo de folha de pagamento no layout cadastrado da sua UN.

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](/api-reference#tag/Payment-Sheet)
com try-it interativo.

<Note>
  **Pré-requisito:** o **layout de exportação** da sua folha precisa estar
  cadastrado no dashboard Pontua antes da primeira execução.
</Note>

## 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:

```javascript theme={null}
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

<Card icon="moon" title="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).
</Card>

<Card icon="rotate-right" title="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.
</Card>

<Card icon="ban" title="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.
</Card>

<Card icon="vault" title="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.
</Card>

## Veja também

* [Referência: Relatórios](/referencia/relatorios) — outros relatórios além de folha
* [Idempotência](/conceitos/idempotencia) — não disparar 2x o mesmo export