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

# Multi-tenant

> Como cada token é vinculado a uma unidade de negócio e o que isso significa para integrações que atendem múltiplos clientes.

A plataforma Pontua é **multi-tenant por arquitetura** — cada cliente
(empresa, escritório contábil, holding) tem **seu próprio banco de dados
isolado**, identificado por um `tenantId`. Isso tem implicações diretas
para quem integra.

<Note>
  **Resumo prático:** cada token de API é amarrado a **uma única unidade de
  negócio**. Se você atende N clientes, gere N tokens diferentes e gerencie
  do lado da sua aplicação.
</Note>

## Como funciona

O `tenantId` está embutido no JWT do token de API (claim `tenantId`). Você
nunca precisa enviá-lo manualmente — toda chamada autenticada já carrega
essa informação, e o backend resolve o banco do tenant a partir do token.

```
┌─────────────────┐
│  Sua integração │
│   (server-side) │
└────────┬────────┘
         │ Authorization: Bearer <token>
         ▼
┌─────────────────────────────────────┐
│  api.pontua.com.br                  │
│  ├─ Verifica token JWT              │
│  ├─ Extrai claim "tenantId"         │
│  └─ Roteia query para o banco       │
│     daquela UN                       │
└─────────────────────────────────────┘
```

## Casos de uso comuns

### Caso 1 — Empresa única integrando seu ERP

Você é uma empresa com **uma única unidade de negócio Pontua** integrando
o ERP interno. Padrão simples:

* 1 token (criado no dashboard)
* Armazena em variável de ambiente / secret manager
* Todas as chamadas usam o mesmo header

Sem mistério. É o caso da maioria dos integradores.

### Caso 2 — Holding com múltiplas unidades de negócio

Sua empresa tem **N unidades de negócio** Pontua (matriz + filiais),
cada uma com seu próprio quadro de funcionários. Cada UN é um tenant
separado.

**Solução:**

* Crie **um token por UN** dentro do dashboard de cada uma
* Mapeie em uma tabela na sua aplicação:

```javascript theme={null}
const tokensPorUnidade = {
  matriz:    process.env.PONTUA_TOKEN_MATRIZ,
  filial_sp: process.env.PONTUA_TOKEN_FILIAL_SP,
  filial_rj: process.env.PONTUA_TOKEN_FILIAL_RJ,
}

async function listarColaboradoresDaUnidade(unidade) {
  const token = tokensPorUnidade[unidade]
  return fetch('https://api.pontua.com.br/colaborador', {
    headers: { Authorization: `Bearer ${token}` },
  }).then((r) => r.json())
}
```

### Caso 3 — Contador atendendo N clientes

Você é um escritório contábil com **N clientes Pontua**. Cada cliente
gerou um token e te entregou.

**Solução recomendada:**

* Armazene tokens criptografados no seu sistema, indexados por `clientId`
* Use cada token apenas para chamadas relacionadas àquele cliente
* **Nunca** misture dados de tenants diferentes em queries / cache /
  logs sem segregação clara

```javascript theme={null}
async function gerarRelatorioParaCliente(clientId, params) {
  const token = await secretManager.getDecryptedToken(clientId)

  const response = await fetch('https://api.pontua.com.br/relatorio/banco-horas', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(params),
  })

  return { clientId, ...(await response.json()) }
}
```

## Boas práticas

<Card icon="lock" title="Não compartilhe tokens entre tenants">
  Nunca tente reusar um token de UN A para chamar dados da UN B — vai falhar
  com 404 ou retornar dados errados. O tenant é parte do contrato do token.
</Card>

<Card icon="rotate" title="Rotacione por tenant">
  Se um token vazou ou um cliente saiu da sua base, **revogue só aquele**.
  Não derrube tokens de outros tenants juntos.
</Card>

<Card icon="folder-tree" title="Logs separados por tenant">
  Estruture seus logs com `tenantId` ou `clientId` na primeira chave
  pra facilitar troubleshooting. Caso 3 (contador) sofre muito quando
  os logs misturam dados de N empresas sem identificação clara.
</Card>

<Card icon="users" title="LGPD: dados são da unidade">
  Como cada banco é isolado, **sua integração só tem acesso aos dados
  daquela UN**. Em caso de incidente, o blast radius é controlado.
</Card>

## Veja também

* [Autenticação](/conceitos/autenticacao) — ciclo de vida do token
* [Erros](/conceitos/erros) — diferenciar `404 Not Found` de `401 Token inválido`