# 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.

```bash
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:

```json
{
  "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](/guia/autenticacao).

---

## 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:

```bash
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).