OAuth - Lojou Docs

Use OAuth quando o seu app vai ser instalado por outros vendedores, não só operar na sua própria loja — cada um autoriza o acesso à própria loja, sem nunca te dar a senha nem uma API Key permanente da conta dele. Se você só precisa integrar a sua própria loja, uma API Key é mais simples e você pode pular esse guia.

Visão geral do fluxo

0. Registre o seu app

Antes de tudo, você precisa de um client_id e client_secret. Isso é feito no painel da Lojou (não por uma chamada de API) — fale com o suporte ou registre o app em Configurações → Apps/Integrações pra receber as credenciais e cadastrar o(s) redirect_uri autorizado(s).

1. Mande o vendedor autorizar

Redirecione o navegador do vendedor pra tela de autorização da Lojou, com o client_id do seu app e o redirect_uri (precisa bater exatamente com o que foi cadastrado no passo 0):

https://web.lojou.app/oauth/authorize?client_id=SEU_CLIENT_ID&redirect_uri=https://seuapp.com/callback

O vendedor loga na própria conta Lojou (se ainda não estiver logado) e vê uma tela com o nome do seu app e os escopos pedidos, pra aprovar ou recusar.

Confirme a URL exata dessa tela com o time da Lojou ao registrar seu app (passo 0) — o que importa pro seu integração é o par client_id/redirect_uri, que é validado pela API independente de qual página os hospeda.

2. Receba o callback

Se o vendedor aprovar, a Lojou redireciona de volta pro seu redirect_uri com dois parâmetros:

https://seuapp.com/callback?code=eyJ...&state=aB3xY...

code — de uso único, expira em 10 minutos.
state — o mesmo valor que a Lojou gerou nesse fluxo; sirva-se dele pra confirmar que a resposta corresponde a uma autorização que você mesmo iniciou (proteção contra CSRF).

3. Troque o code por um token

curl -X POST https://api.lojou.app/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "code": "eyJ...",
    "client_id": "SEU_CLIENT_ID",
    "client_secret": "SEU_CLIENT_SECRET",
    "redirect_uri": "https://seuapp.com/callback",
    "state": "aB3xY..."
  }'

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "expires_at": "2026-09-30T12:00:00.000000Z",
  "permissions": ["orders.read", "products.read"]
}

Guarde o access_token e o refresh_token associados a esse vendedor (um por loja conectada) — nunca ao seu app como um todo.

4. Chame a API em nome do vendedor

curl https://api.lojou.app/v1/orders \
  -H "Authorization: Bearer <access_token>"

Todo endpoint /v1/* funciona igual, seja o token vindo de OAuth ou de uma API Key — a diferença é só na forma como o token foi emitido.

Erros comuns

Erro	Causa provável
`Código inválido ou expirado`	O `code` já foi usado uma vez, ou passou dos 10 minutos. Reinicie o fluxo a partir do passo 1.
`State inválido`	O `state` enviado na troca não bate com o que veio no callback.
`client_id não confere` / `redirect_uri não confere`	O `code` foi emitido pra um `client_id`/`redirect_uri` diferente do que você está mandando agora.
`Credenciais inválidas`	`client_id`/`client_secret` errados, ou o app está inativo.

Escopos

O vendedor só aprova os escopos que o seu app pediu — e pode ser um subconjunto deles, dependendo do que ele aceitar na tela de autorização. O campo permissions na resposta do token diz exatamente o que foi concedido; chame GET /v1/scopes a qualquer momento pra conferir de novo.

​Visão geral do fluxo

​0. Registre o seu app

​1. Mande o vendedor autorizar

​2. Receba o callback

​3. Troque o code por um token

​4. Chame a API em nome do vendedor

​Erros comuns

​Escopos

Visão geral do fluxo

0. Registre o seu app

1. Mande o vendedor autorizar

2. Receba o callback

3. Troque o code por um token

4. Chame a API em nome do vendedor

Erros comuns

Escopos