Autenticação

Toda rota administrativa exige uma credencial. Na API legada, ela é uma chave de API enviada com HTTP Basic junto do e-mail do usuário. Quem prefere um token pode trocar e-mail e senha por um JWT na rota auth_tokens. As duas formas identificam um usuário da loja, e as permissões vêm desse usuário.

As formas de entrar

HTTP Basic com chave de API

A API foi desenhada antes dos JWT. Você envia o e-mail do usuário e uma chave de API, que funciona como uma senha própria para integrações: pode ser revogada sem trocar a senha de login do usuário.

Gerar a chave de API no painel

1. Entre no painel como administrador

   Acesse https://<sua-loja>/admin com um usuário que tenha o privilégio de gerenciar senhas de usuários (manage_user_passwords). Sem ele, a opção de chave não aparece.

2. Abra o usuário que será a conta de integração

   No menu lateral, vá em Usuários e abra o usuário (do tipo administrador) cujo e-mail vai identificar a integração. Crie um usuário dedicado, como erp@minhaloja.com.br, em vez de reaproveitar o de uma pessoa.

3. Gere a chave

   No topo da página do usuário, abra o menu de ações (ícone de engrenagem) e escolha Gerar API Key (ou Gerar nova API Key, se já existir uma). Confirme na janela.

4. Copie a chave

   O painel mostra a chave uma única vez, com o aviso "Copie agora". Depois disso só aparecem os 8 primeiros caracteres (o campo API Key (legado)). Se você perder a chave, gere outra.

A chave tem 64 caracteres hexadecimais. A plataforma guarda só o hash dela, então nem a Venddor consegue mostrá-la de novo. Lojas migradas da plataforma antiga podem ter as chaves antigas importadas; nesse caso a chave que o seu ERP já usa continua valendo.

Chamar com HTTP Basic

O cabeçalho é Authorization: Basic seguido de base64("e-mail:chave"). Todas as bibliotecas HTTP fazem isso por você.

curl "$BASE_URL/api/v1.0/products?items_per_page=5" \
  -u "erp@minhaloja.com.br:$API_KEY"

Respostas de autenticação (todas no formato {"status": ..., "message": ...}):

Receber um token pela rota auth_tokens

Se o seu cliente já sabe trocar e-mail e senha por um token, use POST /api/v1.0/auth_tokens. A rota também responde em /api/auth_tokens e é pública, sem autenticação.

Exemplo de requisição

curl -X POST "$BASE_URL/api/v1.0/auth_tokens" \
  -H "Content-Type: application/json" \
  -d '{"email": "integracao@minhaloja.com.br", "password": "sua-senha"}'

Resposta

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "ttl": 107999 }

Esta rota não devolve refresh_token: quando o token vencer, chame-a de novo. Guarde o token e reutilize-o até perto do fim da validade, em vez de pedir um por chamada.

Erros da rota auth_tokens

Esta rota é a única cujos erros não trazem o campo status.

Token de app

Um app de terceiros (um conector de ERP de um fornecedor, uma ferramenta de logística) não deveria receber a senha de um usuário. Para isso existe o token de app: o desenvolvedor registra o aplicativo no portal de desenvolvedores da loja, o administrador aprova a instalação escolhendo os escopos (por exemplo read_orders) e o app recebe um token que começa com vat_live_ (ou vat_test_).

O administrador vê e remove os apps em Apps Instalados no painel (/admin/installed-apps), o que revoga o acesso na hora. O token de app só vale nas rotas /api/admin/... e só dentro dos escopos aprovados; um token de usuário nessas rotas responde 401. As rotas, os escopos e os erros estão em API de apps e em Pedidos por token de app.

Erros comuns

• Mandar a chave de API em Bearer. A chave só funciona em Basic.
• Fazer login a cada chamada. Guarde o token da rota auth_tokens e reutilize-o até vencer.
• Esquecer que a chave foi substituída. Quem gera uma nova chave derruba a antiga.
• Chamar a loja errada. Token e X-Tenant-ID precisam ser da mesma loja.
• Usar uma conta de comprador. As rotas administrativas respondem 403 Forbidden: admin scope required.
• Esperar um refresh_token. A rota auth_tokens não tem renovação: peça um token novo.

Veja também