> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lojou.app/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

> Como conectar seu app a lojas de outros vendedores.

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](/pt/authentication#api-key) é mais simples e você pode pular esse guia.

## Visão geral do fluxo

```mermaid theme={null}
sequenceDiagram
    participant V as Vendedor
    participant L as Lojou
    participant A as Seu app

    A->>L: 1. Redireciona o vendedor pra tela de autorização (client_id, redirect_uri)
    V->>L: 2. Faz login e aprova o acesso
    L->>A: 3. Redireciona de volta com ?code=...&state=...
    A->>L: 4. POST /v1/oauth/token (code + client_secret)
    L->>A: 5. access_token + refresh_token
    A->>L: 6. Usa o access_token em qualquer endpoint /v1/*
```

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

<Note>
  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.
</Note>

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

```bash theme={null}
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..."
  }'
```

```json theme={null}
{
  "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

```bash theme={null}
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.