Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.dokstamp.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Autenticação

Todos os pedidos à API são autenticados através de um Token de Serviço — um Bearer token de curta duração obtido via o grant OAuth2 Client Credentials. Trata-se de um fluxo máquina a máquina: não existe qualquer login humano envolvido.

​
Como funciona

A sua integração dispõe de um client_id e de um client_secret (fornecidos pelo seu gestor de conta DokStamp). Troque-os por um token de acesso e inclua esse token em cada pedido à API. 
client_id + client_secret
        │
        ▼
POST /oauth/token
        │
        ▼
access_token (válido 12h)
        │
        ▼
Authorization: Bearer {access_token}

​
1. Obtenha um token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

curl -X POST https://api.dokstamp.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
Resposta: 
{
  "token_type": "Bearer",
  "expires_in": 43200,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}
CampoDescrição
access_tokenIncluir em cada pedido à API via Authorization: Bearer
expires_inValidade em segundos — 43 200 = 12 horas

​
2. Utilize o token

Inclua o token em cada pedido subsequente: 
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Accept: application/json
X-Tenant: your-tenant-identifier

​
3. Renovação do token

Os tokens expiram após 12 horas. Não existe refresh token — solicite um novo com as suas credenciais quando necessário. Padrão recomendado: guarde o token em cache e renove-o proativamente ~60 segundos antes da expiração. 
let token = null;
let expiresAt = null;

async function getToken() {
  if (token && Date.now() < expiresAt - 60_000) return token;

  const res = await fetch('https://api.dokstamp.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.DOKSTAMP_CLIENT_ID,
      client_secret: process.env.DOKSTAMP_CLIENT_SECRET,
    }),
  });

  const data = await res.json();
  token = data.access_token;
  expiresAt = Date.now() + data.expires_in * 1000;
  return token;
}

​
Endpoints públicos

Estes endpoints não requerem autenticação:
EndpointFinalidade
POST /oauth/tokenObter um token de serviço
GET /files/{uuid}/downloadTransferir um documento assinado
Guarde client_id e client_secret em variáveis de ambiente ou num gestor de segredos. Nunca os inclua diretamente no código-fonte.