Introdução

Autenticar uma integração tem três passos: criar uma credencial, trocar a credencial por um token de acesso e usar o token na primeira chamada.

1. Criar uma credencial de integração

Toda integração começa por uma credencial. A credencial é um par username + senha que pertence à sua loja. Você pode criar quantas precisar (uma por ERP, hub, dashboard, etc.) e revogar individualmente.

  1. Acesse o Portal do Vendedor.

  2. No menu lateral, vá em Configurações → API & Integrações.

  3. Clique em Nova credencial (canto superior direito).

  4. Dê um nome descritivo da aplicação que vai usar a credencial. Exemplos: ERP, Hub de integração, Dashboard de BI, Webhook de notificações.

  5. Confirme. A tela exibe a credencial recém-criada:

    • Username: gerado automaticamente no formato slug-da-loja@xxxxxxxx (ex.: loja-xpto@12345678).
    • Senha: string aleatória de 20 caracteres.

⚠️ A senha aparece uma única vez. Copie e guarde em local seguro (cofre de senhas, gerenciador de segredos do seu sistema). Se perder, dá pra gerar uma nova pelo botão Trocar senha na linha da credencial, mas a anterior deixa de funcionar.

2. Obter um token de acesso

Com a credencial em mãos, o seu sistema externo faz uma chamada autenticada por username + senha pra obter um token de acesso. Esse token é o que vai no Authorization: Bearer de todas as chamadas seguintes.

curl -X POST https://api.sandbox.samdevel.com.br/api/integration/auth \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "loja-xpto@12345678",
    "password": "Xk9p2Lm7nQ4rT8vW3yZ1"
  }'

Resposta:

{
  "success": true,
  "data": {
    "token": "sk_live_a1b2c3d4e5f6...",
    "expires_at": "2026-06-19T12:34:56-03:00"
  }
}
  • O token vale por 30 dias.
  • Cada chamada ao /api/integration/auth emite um token novo e invalida o anterior. Esse é o mecanismo de rotação: não acumule tokens; gere um novo só quando o atual estiver perto de expirar.

Detalhes completos da autenticação (limites, erros, troca de senha) estão no guia de Autenticação.

3. Fazer sua primeira chamada

Use o token obtido como Bearer em qualquer endpoint da API. Para confirmar que está tudo certo, consulte a sessão da sua loja:

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

Você deve receber os dados públicos da loja autenticada (id, nome, status, empresa).