Skip to main content
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.
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.

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

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.

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.

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.

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.

​
Veja também

  • Autenticação — ciclo de vida do token
  • Erros — diferenciar 404 Not Found de 401 Token inválido