Autenticação

A API do marketplace UniSupri usa autenticação bearer token em todos os endpoints de seller. O token é obtido a partir de uma credencial (username + senha) criada no Portal do Vendedor. Leia Primeiros Passos se ainda não criou a sua.

Modelo

Dois conceitos distintos:

A credencial fica parada no seu cofre de senhas e não vai em chamadas de API. O token é o que circula em cada requisição.

Obter um token

POST/api/integration/auth

Endpoint público, não exige Authorization. A própria credencial (no body) é a forma de autenticação.

Request

{
  "username": "loja-xpto@12345678",
  "password": "Xk9p2Lm7nQ4rT8vW3yZ1"
}

Response 200

{
  "success": true,
  "data": {
    "token": "sk_live_a1b2c3d4e5f6...",
    "expires_at": "2026-06-19T12:34:56-03:00"
  }
}

Rotação

Cada chamada bem-sucedida ao /api/integration/auth:

• Emite um token novo.
• Substitui o token anterior. O antigo deixa de funcionar imediatamente.
• Repopula expires_at para agora + 30 dias.

Implicação prática: só existe 1 token ativo por credencial. Se você roda dois sistemas que precisam de tokens independentes, crie duas credenciais separadas no portal.

Quando renovar

Renove antes de expirar. Recomendamos disparar uma nova chamada quando faltarem 24-48h pra expiração. Você não vai encontrar um endpoint de refresh-token separado, e isso é proposital: pra manter o fluxo simples, a renovação é a própria chamada ao /api/integration/auth — a mesma que você já usa pra obter o token. Um endpoint só, que serve tanto pra primeira emissão quanto pra renovar. Se o token expirar e você fizer uma chamada com ele, a API responde 401 e o ERP deve renovar e tentar de novo.

Usar o token

Em qualquer endpoint do seller, envie o token no cabeçalho Authorization:

curl https://api.sandbox.samdevel.com.br/api/products \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6..."

A API valida:

1. Formato: o token começa com sk_live_ e tem comprimento esperado.
2. Existência: existe uma credencial associada a este token.
3. Ativação: a credencial não foi revogada (active = false).
4. Validade:expires_at ainda não passou.

Falha em qualquer uma → resposta 401 Unauthorized.

Confirmar a autenticação

GET/api/stores/auth/session

Use para validar que o token está autenticando a loja correta. A resposta traz os dados da loja (id, nome, código, status, tipo, limites e features), a company associada (CNPJ, razão social, regime tributário) e auth_type: "integration_token".

Limites de taxa

O /api/integration/auth é protegido contra brute-force:

• 5 tentativas por minuto por par (IP, username).
• Estourou o limite: 429 Too Many Requests, com Retry-After em segundos.

O contador é por par IP+username; tentativas legítimas de outras lojas/IPs não são afetadas.

Este limite é só da emissão de token. O limite das demais rotas de integração está em Limites de uso.

Erros possíveis

Trocar a senha

Quando trocar:

• Você suspeita que a senha vazou.
• Rotação preventiva periódica (recomendado a cada 90 dias).
• Trocou de mãos a operação do ERP.

Como trocar:

1. Portal do Vendedor → Configurações → API & Integrações.
2. Localize a credencial na lista.
3. Clique no ícone de chave (🔑 Trocar senha).
4. Escolha Gerar aleatória (recomendado) ou Definir manualmente (mínimo 12 caracteres).
5. Copie a nova senha. Ela aparece uma única vez.

Importante: trocar a senha não invalida o token corrente. O ERP que está usando o token atual continua funcionando até a próxima expiração ou até você revogar a credencial inteira. Se você precisa invalidar imediatamente (suspeita de comprometimento), revogue a credencial (lixeira) e crie uma nova.

Revogar uma credencial

Portal do Vendedor → Configurações → API & Integrações → ícone de lixeira na linha da credencial.

Efeito imediato:

• Username e senha deixam de autenticar no /integration/auth.
• O token corrente (se ainda estiver dentro do prazo) continua válido até a expiração, porque a checagem do middleware é pelo token, e o registro inteiro foi removido.

Se precisa cortar acesso de imediato, faça nessa ordem:

1. Marque a credencial como inativa (botão futuro) ou delete.
2. Acompanhe last_used_at para confirmar que o ERP parou de chamar.

Boas práticas

• Cache o token. Não chame /integration/auth antes de cada requisição; emita um token e use-o pelos 30 dias.
• Renove proativamente. Agende um job que renove o token quando faltarem ~24h.
• Trate 401 como sinal de renovação. Se uma chamada autenticada retornar 401, renove o token e tente uma vez. Se ainda falhar, alerte um humano.
• Uma credencial por sistema. Não compartilhe credenciais entre ERPs diferentes; a rotação substitui o token, e isso quebra o sistema que ficou pra trás.
• Não logue a senha nem o token em arquivos de log persistentes. Use mascaramento (sk_live_...XXXX).
• Cofre de senhas. Guarde username + password em um gerenciador de segredos (1Password, Vault, AWS Secrets Manager, etc.), nunca em código-fonte commitado.