OAuth 2.0

Com OAuth 2.0, o teu software pode aceder à API Brutlers em nome de um fornecedor. O fornecedor autoriza o acesso uma única vez — depois o teu software sincroniza automaticamente.

Authorization Code Flow

O Brutlers implementa o OAuth 2.0 Authorization Code Flow com PKCE (RFC 7636). Assim funciona o processo:


┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Your App   │     │   Brutlers   │     │   Vendor    │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │  1. Redirect      │                   │
       │──────────────────>│                   │
       │                   │  2. Login/Consent │
       │                   │<─────────────────>│
       │                   │                   │
       │  3. code + state  │  3. Allow         │
       │<──────────────────│<──────────────────│
       │                   │                   │
       │  4. Exchange code │                   │
       │──────────────────>│                   │
       │                   │                   │
       │  5. Tokens        │                   │
       │<──────────────────│                   │
       │                   │                   │
       │  6. API calls     │                   │
       │──────────────────>│                   │

1. Registar aplicação

Regista a tua aplicação no Vendor Dashboard em Integrações. Receberás um Client ID e um Client Secret.

Ir para o Vendor Dashboard

2. Authorization Request

Redireciona o fornecedor para o nosso endpoint de autorização. O fornecedor inicia sessão e concede a permissão.

http

GET /api/oauth/authorize?
  response_type=code
  &client_id=brut_app_...
  &redirect_uri=https://app.example.com/callback
  &scope=orders:read orders:write
  &state=random_csrf_token
  &code_challenge=BASE64URL_SHA256_HASH
  &code_challenge_method=S256

Parameter	Required	Description
response_type	Yes	Deve ser "code"
client_id	Yes	O teu Client ID
redirect_uri	Yes	Deve corresponder exatamente a um URI registado
scope	Yes	Lista de scopes separada por espaços
state	Recomendado	String aleatória para proteção contra CSRF
code_challenge	Recomendado	Hash SHA-256 do Code Verifier codificado em Base64url
code_challenge_method	Recomendado	Deve ser "S256"

3. Token Exchange

Após a autorização, receberás um Authorization Code. Troca-o por um Access Token e um Refresh Token.

bash

curl -X POST https://brutlers.com/api/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=brut_app_..." \
  -d "client_secret=brut_secret_..." \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "code_verifier=ORIGINAL_RANDOM_STRING"

Resposta

json

{
  "access_token": "brut_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "brut_rt_...",
  "scope": "orders:read orders:write"
}

4. Chamadas à API

Usa o Access Token como Bearer Token no cabeçalho Authorization dos teus pedidos à API.

http

GET /api/vendor/orders HTTP/1.1
Host: brutlers.com
Authorization: Bearer brut_at_...

5. Renovar token

Os Access Tokens são válidos por 1 hora. Usa o Refresh Token para obter um novo Access Token. Os Refresh Tokens são válidos por 30 dias e são rotacionados a cada utilização.

bash

curl -X POST https://brutlers.com/api/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=brut_rt_..." \
  -d "client_id=brut_app_..." \
  -d "client_secret=brut_secret_..."

Scopes disponíveis

Scope	Description
orders:read	Ler encomendas
orders:write	Criar encomendas e alterar estado
customers:read	Ler dados de clientes
profile:read	Ler perfil de fornecedor

Revogar token

Invalida um Access Token ou Refresh Token. O endpoint devolve sempre HTTP 200 (RFC 7009).

bash

curl -X POST https://brutlers.com/api/oauth/revoke \
  -d "token=brut_at_..." \
  -d "client_id=brut_app_..." \
  -d "client_secret=brut_secret_..."

Notas de segurança

• Guarda o Client Secret em segurança — é mostrado apenas uma vez.
• Usa PKCE (S256) para clientes públicos (ex.: Single-Page Apps).
• Os Authorization Codes são válidos por 10 minutos e só podem ser utilizados uma vez.
• Os Redirect URIs têm de corresponder exatamente ao URI registado.
• Usa o parâmetro state para proteção contra CSRF.