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

# Folha de Pagamento

> Eventos de folha (proventos/descontos), exportação no layout do seu sistema (Domínio, Sage, Senior, etc.) e marcação de processados. Top use case para contadores e ERPs.

A tag **Payment Sheet** consolida os eventos da folha de pagamento da
UN — proventos (salário, HE, adicional noturno, comissões) e descontos
(faltas, vale-transporte, INSS) — e exporta no layout específico do seu
sistema de folha externa.

É o **principal use case de integradores B2B** porque resolve o problema
clássico: ter o cálculo de jornada Pontua-side e a folha em um sistema
externo (Domínio Sistemas, Sage Senior, Alterdata, ContabilQuasar, etc.).

## Conceitos

<CardGroup cols={2}>
  <Card title="Source" icon="database">
    Origem do evento: `SISTEMA` (cálculo automático), `PONTO` (derivado de batidas),
    `AJUSTE` (correção manual), e outros conforme configuração. Veja
    `GET /payment-sheet/source`.
  </Card>

  <Card title="System Event" icon="bolt">
    Eventos pré-cadastrados pelo sistema (ex.: HE 50%, HE 100%, Adicional
    Noturno, Faltas). Cada evento tem código próprio que mapeia para
    rúbrica da folha externa. Veja `GET /payment-sheet/system-event`.
  </Card>

  <Card title="Export Layout" icon="file-export">
    Layout do arquivo TXT esperado pelo seu sistema de folha. Cada
    sistema tem seu formato (Domínio Sistemas usa um, Sage outro).
    Cadastrado uma vez por UN, reutilizado em todo export.
  </Card>

  <Card title="Parameter" icon="sliders">
    Parâmetros de configuração específicos do export — quais eventos
    incluir, regra de arredondamento, agrupamentos. Avançado.
  </Card>
</CardGroup>

## Endpoints

### Eventos (Event)

| Método | Rota                               | Descrição                 |
| ------ | ---------------------------------- | ------------------------- |
| GET    | `/payment-sheet/event`             | Lista eventos cadastrados |
| GET    | `/payment-sheet/event/{id}`        | Detalhe                   |
| POST   | `/payment-sheet/event`             | Cria evento custom        |
| POST   | `/payment-sheet/event/sync`        | Sincronização em massa    |
| PATCH  | `/payment-sheet/event/{id}/status` | Ativa/inativa             |
| DELETE | `/payment-sheet/event/{id}`        | Remove                    |

### Exportações (Export)

| Método | Rota                                          | Descrição                            |
| ------ | --------------------------------------------- | ------------------------------------ |
| GET    | `/payment-sheet/export`                       | Lista exports gerados                |
| GET    | `/payment-sheet/export/{id}`                  | Detalhe + status                     |
| GET    | `/payment-sheet/export/{id}/download`         | Conteúdo (URL S3 ou base64)          |
| GET    | `/payment-sheet/export/{id}/{collaboratorId}` | Eventos de um colaborador específico |
| POST   | `/payment-sheet/export`                       | Disparar nova exportação             |
| PATCH  | `/payment-sheet/export/{id}/status/processed` | Marcar como processado pela folha    |
| PATCH  | `/payment-sheet/export/{id}/{collaboratorId}` | Editar valores de eventos            |
| DELETE | `/payment-sheet/export/{id}`                  | Remove export                        |
| DELETE | `/payment-sheet/export/{id}/{collaboratorId}` | Remove colaborador do export         |

### Layout e Parâmetros

| Método | Rota                                          | Descrição                               |
| ------ | --------------------------------------------- | --------------------------------------- |
| GET    | `/payment-sheet/export-layout`                | Lista layouts cadastrados               |
| GET    | `/payment-sheet/export-layout/{id}`           | Detalhe do layout                       |
| POST   | `/payment-sheet/export-layout`                | Cria layout custom (avançado)           |
| PUT    | `/payment-sheet/export-layout/{id}`           | Atualiza                                |
| DELETE | `/payment-sheet/export-layout/{id}`           | Remove                                  |
| GET    | `/payment-sheet/parameter`                    | Lista parâmetros                        |
| GET    | `/payment-sheet/parameter/{id}`               | Detalhe                                 |
| GET    | `/payment-sheet/parameter/{id}/collaborators` | Colaboradores vinculados a um parâmetro |

| Método | Rota                          | Descrição                                  |
| ------ | ----------------------------- | ------------------------------------------ |
| GET    | `/payment-sheet/source`       | Lista origens de eventos disponíveis       |
| GET    | `/payment-sheet/system-event` | Lista eventos pré-cadastrados pelo sistema |

Schema completo em [Referência da API](/api-reference#tag/Payment-Sheet).

## Fluxo end-to-end típico

```
1. Setup (uma vez):
   ├── Cadastrar Layout (POST /export-layout) — formato do TXT
   └── Cadastrar Parâmetros (POST /parameter) — quais eventos, regras

2. Mensalmente (após fechamento):
   ├── POST /export — dispara exportação
   ├── GET /export/{id} — polling até CONCLUIDO
   ├── GET /export/{id}/download — baixa TXT
   ├── (Seu sistema importa o TXT na folha externa)
   └── PATCH /export/{id}/status/processed — marca como integrado
```

Ver guia detalhado [Puxar folha do mês](/guias-praticas/puxar-folha-do-mes).

## Gotchas conhecidos

<Warning title="Layout não cadastrado bloqueia export">
  `POST /export` falha com `400` se a UN não tem layout cadastrado.
  Cadastre o layout primeiro (via dashboard tipicamente, ou via API
  em setup automatizado).
</Warning>

<Warning title="Não exporte com fechamento aberto">
  Cheque que o período tem **fechamento concluído** antes de exportar.
  Exportar com ajustes em curso pode gerar TXT que diverge da folha
  oficial. Ver [Fechamento](/referencia/fechamento).
</Warning>

<Warning title="Marcar como processado é ato auditável">
  `PATCH /export/{id}/status/processed` é a forma de fechar o ciclo
  Pontua → folha externa. Em caso de fiscalização, esse marcador prova
  que a folha foi efetivamente importada. Sempre marque após confirmação
  do sistema downstream.
</Warning>

<Warning title="Layout customizado é raro e arriscado">
  Layouts pré-cadastrados pela Pontua cobrem maioria dos sistemas BR.
  Criar layout custom (`POST /export-layout`) é necessário só em
  formato proprietário não suportado. Erro no layout custom causa folha
  errada — valide caso a caso.
</Warning>

## Veja também

* [Puxar folha do mês](/guias-praticas/puxar-folha-do-mes) — fluxo completo passo-a-passo
* [Relatórios — Eventos Folha](/referencia/relatorios) — alternativa simplificada via tag Relatório
* [Fechamento](/referencia/fechamento) — exportar só após fechado
* [Estrutura Organizacional — Centro de Custo](/referencia/estrutura-organizacional) — alimenta apropriação