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

# Quick Start

> Da geração do token à primeira chamada autenticada em menos de 5 minutos.

Em 5 minutos você gera um token, faz a primeira chamada autenticada e entende
o formato das respostas.

## Pré-requisitos

* Conta Pontua **com plano que inclui acesso à API** (se não tiver certeza, fale com sua gerência)
* Permissão de **administrador** na unidade de negócio (gestão de tokens é restrita)
* Cliente HTTP da sua escolha — `curl`, Postman, ou um SDK (Node, Python, Go, etc.)

## 1. Gere um token de API

<Steps>
  <Step title="Acesse o dashboard">
    Entre em [oi.pontua.com.br](https://oi.pontua.com.br) com sua conta administrativa.
  </Step>

  <Step title="Vá para Configurações → API">
    No menu lateral: **Gestão de Pessoas → Configurações → API**.
  </Step>

  <Step title="Crie um novo token">
    Clique em **Criar novo token**. Defina:

    * **Nome identificador** — descritivo por integração (ex.: `[PROD] erp-domínio`, `[HML] script-relatorio-mensal`)
    * **Validade** — entre 7 dias e 5 anos (ver [Autenticação](/conceitos/autenticacao) para detalhes)
  </Step>

  <Step title="Copie o token IMEDIATAMENTE">
    O valor aparece **uma única vez** após gerar. Cole em um cofre de senhas
    (1Password, Doppler, AWS Secrets Manager) — você não conseguirá vê-lo
    de novo no dashboard.

    <Warning>
      Trate o token como senha. Quem o tem **lê e modifica dados da unidade de
      negócio**. Não comite em git, não envie por email/Slack, não bote em
      código frontend.
    </Warning>
  </Step>
</Steps>

## 2. Faça sua primeira chamada

Liste os primeiros 10 colaboradores:

<CodeGroup>
  ```bash curl theme={null}
  curl --request GET \
    --url 'https://api.pontua.com.br/colaborador?pagina=0&limite=10' \
    --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
    --header 'Accept: application/json'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.pontua.com.br/colaborador?pagina=0&limite=10',
    {
      headers: {
        Authorization: `Bearer ${process.env.PONTUA_API_TOKEN}`,
        Accept: 'application/json',
      },
    },
  )

  if (!response.ok) {
    const erro = await response.json()
    throw new Error(`${erro.service}.${erro.method}: ${erro.message}`)
  }

  const { resultados, totalRegistros, pagina, limite } = await response.json()
  console.log(`Página ${pagina} de ~${Math.ceil(totalRegistros / limite)}: ${resultados.length} colaboradores`)
  ```

  ```python Python theme={null}
  import os
  import requests

  resp = requests.get(
      'https://api.pontua.com.br/colaborador',
      params={'pagina': 0, 'limite': 10},
      headers={
          'Authorization': f"Bearer {os.environ['PONTUA_API_TOKEN']}",
          'Accept': 'application/json',
      },
      timeout=30,
  )
  resp.raise_for_status()

  data = resp.json()
  print(f"Página {data['pagina']}: {len(data['resultados'])} de {data['totalRegistros']} colaboradores")
  ```

  ```go Go theme={null}
  package main

  import (
      "encoding/json"
      "fmt"
      "net/http"
      "os"
  )

  type ColaboradoresResp struct {
      Pagina         int           `json:"pagina"`
      Limite         int           `json:"limite"`
      TotalRegistros int           `json:"totalRegistros"`
      Resultados     []interface{} `json:"resultados"`
  }

  func main() {
      req, _ := http.NewRequest("GET",
          "https://api.pontua.com.br/colaborador?pagina=0&limite=10", nil)
      req.Header.Set("Authorization", "Bearer "+os.Getenv("PONTUA_API_TOKEN"))
      req.Header.Set("Accept", "application/json")

      resp, err := http.DefaultClient.Do(req)
      if err != nil { panic(err) }
      defer resp.Body.Close()

      var data ColaboradoresResp
      json.NewDecoder(resp.Body).Decode(&data)
      fmt.Printf("Página %d: %d de %d colaboradores\n",
          data.Pagina, len(data.Resultados), data.TotalRegistros)
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.pontua.com.br/colaborador?pagina=0&limite=10');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer ' . getenv('PONTUA_API_TOKEN'),
          'Accept: application/json',
      ],
  ]);

  $response = curl_exec($ch);
  $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($status !== 200) {
      $err = json_decode($response, true);
      throw new Exception("{$err['service']}.{$err['method']}: {$err['message']}");
  }

  $data = json_decode($response, true);
  echo "Página {$data['pagina']}: " . count($data['resultados'])
     . " de {$data['totalRegistros']} colaboradores\n";
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.pontua.com.br/colaborador?pagina=0&limite=10')
  req = Net::HTTP::Get.new(uri)
  req['Authorization'] = "Bearer #{ENV['PONTUA_API_TOKEN']}"
  req['Accept'] = 'application/json'

  resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }

  if resp.code != '200'
    err = JSON.parse(resp.body)
    raise "#{err['service']}.#{err['method']}: #{err['message']}"
  end

  data = JSON.parse(resp.body)
  puts "Página #{data['pagina']}: #{data['resultados'].size} de #{data['totalRegistros']} colaboradores"
  ```
</CodeGroup>

## 3. Resposta esperada

```json theme={null}
{
  "pagina": 0,
  "limite": 10,
  "totalRegistros": 142,
  "resultados": [
    {
      "id": "b9f3d8e0-7f3a-4ec0-9b1e-1234567890ab",
      "nome": "João da Silva",
      "cpf": "12345678900",
      "status": "ATIVO",
      "departamento": {
        "id": "d1e2f3a4-...",
        "nome": "Tecnologia"
      },
      "cargo": {
        "id": "c1a2r3g4-...",
        "nome": "Desenvolvedor Pleno"
      }
    }
    /* ... mais 9 itens ... */
  ]
}
```

Veja [Paginação](/conceitos/paginacao) para iterar todas as páginas e
[Referência: Colaboradores](/referencia/colaboradores) para o schema completo.

## 4. Próximos passos

<CardGroup cols={2}>
  <Card title="Cadastrar primeiro colaborador via API" icon="user-plus" href="/guias-praticas/primeiro-colaborador">
    Walkthrough completo do POST `/colaborador` com payload mínimo
  </Card>

  <Card title="Puxar folha do mês" icon="money-check-dollar" href="/guias-praticas/puxar-folha-do-mes">
    Use `/payment-sheet/export` para gerar o TXT no layout da sua folha
  </Card>

  <Card title="Entender erros" icon="circle-exclamation" href="/conceitos/erros">
    Códigos HTTP, mensagens comuns, estratégias de retry com backoff
  </Card>

  <Card title="Configurar multi-tenant" icon="building" href="/conceitos/multi-tenant">
    Como funciona se você atende múltiplas unidades de negócio
  </Card>
</CardGroup>

## Troubleshooting do primeiro request

| Sintoma                                 | Causa provável                         | Ação                                                                               |
| --------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------- |
| `401 Token inválido`                    | Token corrompido ou de ambiente errado | Verifica que `Bearer ` tem espaço, e que o token é o do ambiente que está chamando |
| `401 Token expirado`                    | Validade ultrapassou                   | Gera novo token no dashboard, atualiza secret                                      |
| `401 Acesso não autorizado`             | Header `Authorization` ausente         | Confirma que está enviando o header (cuidado com proxies que filtram headers)      |
| `500 Erro interno` em todas as chamadas | Possível incidente                     | Checa [status.pontua.com.br](https://status.pontua.com.br)                         |
| Timeout sem resposta                    | Firewall corporativo                   | API está em `*.pontua.com.br` e `*.pontua.tech` (HTTPS 443). Libera no firewall    |

Mais detalhes em [Erros](/conceitos/erros).