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

# Introdução

> Visão geral da API pública Pontua para integrações externas, com foco em casos de uso reais (folha, ERP, BI, REPs).

A **API Pontua** dá acesso programático aos dados de jornada da sua empresa
gerenciados pela plataforma Pontua. Foi construída para integrações de
**servidor-para-servidor** (não para uso direto em frontend público), com
autenticação por token de API gerado no dashboard.

<Note>
  **Quem deve ler isto:** desenvolvedores integrando sistemas internos
  (folha, ERP, BI, relógios de ponto customizados) com a Pontua. Você já é
  cliente e tem **plano com acesso à API**.

  Procurando documentação do produto (manual de uso do dashboard, app mobile)?
  Visite [ajuda.pontua.com.br](https://ajuda.pontua.com.br).
</Note>

## O que dá pra fazer

<CardGroup cols={2}>
  <Card title="Sincronizar quadro de funcionários" icon="users">
    Listar colaboradores ativos/inativos, criar e atualizar cadastros, importar
    em massa via CSV, exportar para folha.
  </Card>

  <Card title="Consultar e ajustar pontos" icon="clock">
    Listar batidas e registros de ponto, criar registros via API (relógios
    customizados), aprovar ajustes, gerar AFD em conformidade com Portaria 671.
  </Card>

  <Card title="Gerar relatórios sob demanda" icon="file-chart-line">
    AFD, AEJ, espelho de ponto, banco de horas, horas extras, faltas/atrasos,
    eventos para folha de pagamento. Polling status + download em JSON/PDF/CSV.
  </Card>

  <Card title="Ler folha de pagamento pronta" icon="money-check">
    Eventos consolidados por colaborador, exportação no layout do seu sistema
    de folha (Domínio, Sage, Senior, etc.), confirmação de processado.
  </Card>
</CardGroup>

## Padrão técnico

<Columns cols={2}>
  <div>
    ### Protocolo

    REST sobre HTTPS. Payloads e respostas em **JSON** (UTF-8). Datas em
    ISO 8601 com timezone (`2026-04-25T14:30:00-03:00`).

    ### Autenticação

    Token de API enviado no header `Authorization: Bearer <SEU_TOKEN>`.
    Tokens são gerados, rotacionados e revogados pelo dashboard em
    **Configurações → API**.

    ### Multi-tenant

    Cada token é vinculado a uma **unidade de negócio** específica. Se você
    atende múltiplos clientes (ex.: contador), gere um token por unidade e
    gerencie do lado da sua aplicação.
  </div>

  <div>
    ### Paginação

    Padronizada em todas as listagens. Query string `?pagina=0&limite=100`,
    resposta em envelope `{ pagina, limite, totalRegistros, resultados }`.

    ### Erros

    Envelope JSON `{ service, method, message }` com HTTP status code semântico.
    Mensagens em português, prontas para log.

    ### Versionamento

    Algumas rotas convivem em duas versões via NestJS versioning. A
    [Referência da API](/api-reference) mostra a versão estável recomendada
    para cada endpoint.
  </div>
</Columns>

## Ambientes

| Ambiente               | Base URL                      | Uso                                                      |
| ---------------------- | ----------------------------- | -------------------------------------------------------- |
| **Produção**           | `https://api.pontua.com.br`   | Integrações reais                                        |
| **Homologação (HML)**  | `https://api.hml.pontua.tech` | Testes antes de ir para produção                         |
| **Pré-produção (PRE)** | `https://api.pre.pontua.tech` | Validação de mudanças finais antes de promover para PROD |

Você pode (e deve) gerar tokens **separados** para cada ambiente — o token de
HML não funciona em PROD e vice-versa. Recomendamos prefixar o nome do token
com o ambiente, ex.: `[HML] integracao-erp`, `[PROD] integracao-erp`.

## Política de estabilidade

* **Adições não-quebrantes** (novos campos opcionais em response, novos endpoints) podem entrar a qualquer momento — sua integração deve ser tolerante a campos extras e novos valores em enums
* **Endpoints marcados como deprecated** continuam funcionando hoje; mudanças relevantes são comunicadas por e-mail ao contato técnico da sua conta

Detalhes em [Versionamento](/conceitos/versionamento).

## Entender e começar

<CardGroup cols={3}>
  <Card title="Quick Start" href="/quick-start" icon="rocket">
    Sua primeira chamada autenticada em 5 minutos
  </Card>

  <Card title="Autenticação" href="/conceitos/autenticacao" icon="key">
    Como gerar, usar, rotacionar e revogar tokens
  </Card>

  <Card title="Erros" href="/conceitos/erros" icon="circle-exclamation">
    Códigos HTTP, envelope de erro, estratégias de retry
  </Card>

  <Card title="Paginação" href="/conceitos/paginacao" icon="list-ol">
    Como iterar listagens grandes
  </Card>

  <Card title="Multi-tenant" href="/conceitos/multi-tenant" icon="building">
    Como o token é vinculado à unidade de negócio
  </Card>

  <Card title="Referência da API" href="/api-reference" icon="book">
    Catálogo completo dos endpoints com try-it interativo
  </Card>
</CardGroup>

## Suporte

* **Bug ou comportamento inesperado:** `tecnologia@pontua.com.br` com `service`, `method`, `message` da resposta + timestamp
* **Caso de uso não coberto:** mesmo endereço — descreva o problema de negócio que está tentando resolver
* **Atrasos ou degradação:** [status.pontua.com.br](https://status.pontua.com.br)
* **Sugestões de roadmap:** seja bem específico, gostamos