VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Primeiros passos

Autenticação

Como se autenticar na API: login com JWT, renovação do token, token de app para terceiros e chave da vitrine.

Toda rota administrativa exige uma credencial. Na API, ela é um JWT: um token assinado que você troca por e-mail e senha e que identifica um usuário da loja. As permissões vêm desse usuário. Para aplicativos de terceiros existe ainda o token de app, com escopos limitados.

Pontos-chave
  • POST /api/v1/auth/login devolve access_token (curto) e refresh_token (longo). Envie Authorization: Bearer <access_token>.
  • Renove o par com POST /api/v1/auth/refresh antes de expires_at. O refresh_token é de uso único.
  • Para acesso restrito de terceiros, existe o token de app (vat_...) com escopos, sem usuário administrador.
  • A chave da vitrine (sfk_...) serve só para a API pública da vitrine, não para as rotas administrativas.
  • O login tem limite de 5 tentativas por minuto por endereço IP. Guarde o token e renove em vez de fazer login a cada chamada.

As formas de entrar

CredencialComo é enviadaOnde valeQuem usa
JWT (access_token)Authorization: Bearer eyJ...API (/api/v1/...)Integrações, o painel.
Token de app (vat_live_...)Authorization: Bearer vat_live_...Rotas que aceitam token de appApps de terceiros com escopos.
Chave da vitrine (sfk_...)X-API-Key: sfk_...API da vitrine (/api/v1/storefront/...)Lojas headless e apps do comprador.

Login com JWT

Fazer login

POST/api/v1/auth/loginPública

Troca e-mail e senha por um par de tokens

O usuário precisa ser do tipo administrador para chamar as rotas /api/v1/admin/.... Um usuário comprador consegue fazer login, mas recebe 403 nas rotas administrativas.

Cabeçalhos

Content-Typestringobrigatório
application/json.
X-Tenant-IDstring
Identificador da loja. Dispensável quando você chama o endereço da loja (Endereço e ambientes).

Corpo da requisição

emailstring
E-mail do usuário. Informe email ou identifier.
identifierstring
E-mail, CPF ou CNPJ do usuário. Tem prioridade sobre email.
passwordstringobrigatório
Senha do usuário.

Exemplo de requisição

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

Resposta

200Login feito
json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ2ZW5kZG9yIiwic3ViIjoiZDQ2MTNk...",
  "refresh_token": "dd91ff76a32a3cff844cf1e702256e780a5caa1ffa5363db0fa7bf65a62463f3",
  "expires_at": "2026-10-11T21:04:43.591479365Z"
}

Campos da resposta

access_tokenstring
JWT de acesso. Vai no cabeçalho Authorization: Bearer. Vale por pouco tempo: use expires_at para saber quando.
refresh_tokenstring
Token opaco de longa duração, usado só em /api/v1/auth/refresh. Trate como uma senha.
expires_atstring
Quando o access_token expira, em RFC 3339 e UTC. O tempo de vida é uma configuração da plataforma; não o assuma, leia este campo.

Erros do login

StatusQuandoCorpo de exemplo
400Falta o identificador ou a senha, ou o JSON é inválido.{"error":"password is required"}
401E-mail ou senha incorretos.{"error":"invalid credentials"}
403A senha está certa, mas a conta não pode entrar: e-mail não verificado, conta desativada, aguardando aprovação, ou conta de plataforma tentando entrar numa loja (wrong_panel).{"error":"email_not_verified","message":"please verify your email address before logging in"}
409CPF, CNPJ ou telefone pertence a mais de uma conta. Entre com o e-mail.{"error":"multiple_accounts_cpf","message":"Multiple accounts are associated with this CPF. Please login with your email address instead."}
429Limite de requisições (rate limit exceeded) ou conta bloqueada por tentativas erradas (account_locked). O cabeçalho Retry-After diz quantos segundos esperar.{"error":"rate limit exceeded","detail":"too many requests, please try again later"}
Verificação em duas etapas

Se o usuário ativou 2FA, o login não devolve os tokens. Ele devolve {"requires_2fa": true, "temp_token": "..."}, e você conclui com POST /api/v1/auth/verify-2fa, enviando temp_token e code (o código do aplicativo autenticador). Para uma conta de integração, o mais simples é um usuário administrador sem 2FA e com senha longa; a especificação completa está nos fundamentos.

Usar o token

Envie o access_token em todas as chamadas:

bash
curl "$BASE_URL/api/v1/admin/products?per_page=5" \
  -H "Authorization: Bearer $TOKEN"

Respostas de autenticação nas rotas administrativas:

StatusCorpoCausa
401{"error":"missing authorization header"}Faltou o cabeçalho Authorization.
401{"error":"invalid authorization format"}O cabeçalho não está no formato Bearer <token>.
401{"error":"invalid or expired token"}Token malformado, adulterado ou vencido. Renove ou faça login de novo.
401error começa com token revoked (o texto segue pedindo um novo login)O token foi revogado (por exemplo, "sair de todos os aparelhos"). Faça login de novo.
403{"error":"token not valid for this storefront"}O token é de outra loja.
403{"error":"insufficient privileges","required":"manage_orders"}O usuário não tem o privilégio pedido. Ajuste os privilégios do usuário (ou do grupo dele) no painel.

Renovar o token

Antes de o access_token vencer (ou ao receber 401 invalid or expired token), troque o refresh_token por um par novo. O refresh_token é de uso único: a resposta traz um novo, e o anterior deixa de valer.

POST/api/v1/auth/refreshPública

Troca o refresh token por um novo par de tokens

Corpo da requisição

refresh_tokenstringobrigatório
O refresh_token recebido no login ou na renovação anterior.
bash
curl -X POST "$BASE_URL/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d "{\"refresh_token\": \"$REFRESH_TOKEN\"}"
200Par de tokens novo
json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "5b0c1e7c9d8f4a3e8f6a2d1c0b9e8d7c6a5f4e3d2c1b0a99887766554433221",
  "expires_at": "2026-10-11T21:19:43.100200300Z"
}

Erros: 400 com {"error":"refresh_token is required"} se o campo faltar e 401 com {"error":"invalid refresh token", "detail": "..."} se o token já foi usado, expirou ou foi encerrado. Nesse caso, faça login de novo.

Renovações em paralelo

Como o refresh_token é de uso único, dois processos que renovam ao mesmo tempo com o mesmo token fazem um deles falhar. Centralize a renovação num único ponto do seu sistema e compartilhe o par novo com os demais.

Encerrar a sessão

POST /api/v1/auth/logout com {"refresh_token": "..."} encerra a sessão daquele aparelho e responde {"message":"logged out"}. Os detalhes de logout, 2FA e demais rotas de conta estão nos fundamentos.

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, o administrador da loja aprova a instalação escolhendo os escopos (por exemplo read_orders), e o app troca o código de autorização por um token que começa com vat_live_ (ou vat_test_).

bash
curl -X POST "$BASE_URL/api/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"authorization_code","client_id":"...","client_secret":"...","code":"..."}'

A resposta traz access_token, refresh_token, token_type, expires_in (segundos) e scopes. Para renovar, use grant_type: "refresh_token" com refresh_token. 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 que o aceitam e só dentro dos escopos aprovados; um JWT de usuário nessas rotas responde 401. A lista de escopos e de rotas está em Tokens e escopos.

Chave da vitrine

A tela Chaves de API da Loja (/admin/api-keys) cria chaves que começam com sfk_, para a API da vitrine e o GraphQL (lojas headless, apps de compra). Cada chave tem escopos (como storefront:read) e um limite de requisições por minuto. Envie em X-API-Key: sfk_... (ou Authorization: Bearer sfk_...). Elas não abrem as rotas administrativas deste guia. Erros: 401 invalid_api_key, 403 missing_scope e 429 rate_limit_exceeded.

Erros comuns

  • Usar o refresh_token como Bearer. Só access_token vai no cabeçalho.
  • Fazer login a cada chamada. O limite é de 5 logins por minuto por IP; guarde o token e renove.
  • Usar a chave da vitrine (sfk_...) numa rota administrativa. Ela só abre a API pública da vitrine.
  • Compartilhar o refresh_token entre processos. Ele é de uso único: o segundo a usá-lo recebe 401.
  • Chamar a loja errada. Token e X-Tenant-ID precisam ser da mesma loja.
  • Usar uma conta de comprador. Rotas administrativas respondem 403.

Veja também

Sua primeira requisição
Use a credencial num fluxo completo.
Erros
Todos os formatos de erro.
Fundamentos da API
Logout, 2FA, recuperação de senha e demais rotas de conta.
Anterior
Endereço e ambientes
Próxima
Sua primeira requisição
Nesta página
  • As formas de entrar
  • Login com JWT
  • Fazer login
  • Exemplo de requisição
  • Resposta
  • Erros do login
  • Usar o token
  • Renovar o token
  • Encerrar a sessão
  • Token de app
  • Chave da vitrine
  • Erros comuns
  • Veja também