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.unisupri.com/api/integration/auth \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "loja-xpto@12345678",
    "password": "Xk9p2Lm7nQ4rT8vW3yZ1"
  }'

Resposta:

{
  "success": true,
  "message_code": "SUCCESS",
  "data": {
    "token": "sk_live_a1b2c3d4e5f6...",
    "expires_at": "2026-06-19T12:34:56-03:00",
    "credential": {
      "name": "ERP Bling",
      "username": "loja-xpto@12345678",
      "abilities": ["*"]
    },
    "store": {
      "store_id": "01KYN1VYYBFRDF14ZDXVWFB2MY",
      "store_name": "Loja XPTO",
      "store_code": "LOJA-XPTO",
      "store_status": "active",
      "document": "12345678000190",
      "company_name": "XPTO Comércio Ltda"
    }
  }
}

O bloco store diz a qual loja o token pertence — guarde o store.store_id. É o identificador público da loja (um ULID), e ele reaparece como store_id nas demais respostas da API.

O token vale por 30 dias e cada nova emissão substitui a anterior. Detalhes completos (rotaçã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.unisupri.com/api/stores/auth/session \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6..."

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