Tokens de API permitem que sistemas externos chamem a API Pontua em nome
da sua unidade de negócio, sem necessidade de login interativo de usuário.
Esta seção cobre o ciclo de vida do token via API.
Recomendação: gerencie tokens prioritariamente pelo dashboard
(Configurações → API). A interface web é mais segura para gestão
diária — mostra o token uma única vez no momento da criação e tem trilha
de auditoria visual.Use estes endpoints quando precisar automatizar rotação de tokens
ou inventariar tokens em um sistema de gerenciamento centralizado.
Endpoints
| Método | Rota | Descrição |
|---|
| POST | /api-key | Cria uma nova API Key |
| GET | /api-key | Lista todas as API Keys da unidade |
| PATCH | /api-key/{apiKeyId} | Atualiza status ou nome de uma API Key |
Quando usar a API vs. o dashboard
| Situação | Recomendado |
|---|
| Setup inicial da integração | Dashboard (uma vez) |
| Rotação trimestral automática | API |
| Auditoria de tokens existentes | API (GET /api-key) ou dashboard |
| Revogar token comprometido (urgência) | Dashboard (mais rápido) |
| Inventário multi-tenant para contadores | API |
Padrão de rotação zero-downtime
async function rotacionarTokenPontua() {
// 1. Cria novo token
const respostaCriacao = await fetch('https://api.pontua.com.br/api-key', {
method: 'POST',
headers: {
Authorization: `Bearer ${TOKEN_ATUAL}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
// Veja a Referência da API para os campos exatos do body
nome: `[PROD] erp-${new Date().toISOString().slice(0, 10)}`,
}),
})
const novaChave = await respostaCriacao.json()
const novoToken = novaChave.token // valor aparece UMA vez
// 2. Atualiza secret do sistema (sem deletar o antigo ainda)
await secretManager.updateSecret('PONTUA_API_TOKEN', novoToken)
// 3. Aguarda 24h pra todos os processos pegarem o novo
// (deploys progressivos, caches de secret, etc.)
// 4. Após validar que o novo está sendo usado, revoga o antigo
await fetch(`https://api.pontua.com.br/api-key/${TOKEN_ATUAL_ID}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${novoToken}`, // já usa o novo
'Content-Type': 'application/json',
},
body: JSON.stringify({ status: 'INATIVO' }),
})
}
O valor do token só aparece na resposta de criação. Salve
imediatamente em cofre — não há endpoint para recuperá-lo depois.
Veja também
