OAuth 2.0 — Referência Técnica

Guia completo para integrar sua aplicação com o Bunto ERP usando OAuth 2.0 Authorization Code Grant. Permite que usuários autorizem acesso granular aos seus dados sem compartilhar credenciais.

Visão Geral

---

Base URLs

---

1. Registrar um Aplicativo

Antes de iniciar o fluxo OAuth, registre seu aplicativo no Bunto ERP:

1. Acesse o painel do Bunto ERP
2. Navegue até Integrações → Aplicativos OAuth
3. Clique em Novo Aplicativo
4. Preencha:
   • Nome: Nome exibido na tela de consentimento
   • Descrição: O que sua aplicação faz (exibido ao usuário)
   • Redirect URIs: URLs de callback (HTTPS obrigatório em produção)
   • Escopos: Permissões máximas que o app pode solicitar
5. Copie o client_id e client_secret gerados

Você receberá:

code
client_id: bnt_app_A1b2C3d4E5f6G7h8I9j0K1l2
client_secret: bnt_secret_X9y8Z7w6V5u4T3s2R1q0P9o8N7m6L5k4J3i2H1g0

---

2. Fluxo de Autorização

Passo 1: Redirecionar o Usuário

Redirecione o usuário para a tela de autorização do Bunto ERP:

code
https://erp.bunto.com.br/oauth/autorizar/
  ?client_id=bnt_app_xxx
  &redirect_uri=https://seuapp.com/callback
  &scope=produtos:read,vendas:read,vendas:write
  &state=random_csrf_string_123
  &response_type=code

Parâmetros:

Passo 2: Usuário Autoriza

O Bunto ERP exibirá uma tela de consentimento mostrando:

• Nome e descrição do seu aplicativo
• Escopos solicitados (ex: "Produtos - Leitura", "Vendas - Leitura e Escrita")
• Usuário e empresa conectados

O usuário pode Autorizar ou Negar o acesso.

Passo 3: Receber o Código

Após autorização, o usuário é redirecionado para sua redirect_uri:

https://seuapp.com/callback?code=bnt_code_xxx&state=random_csrf_string_123

Se o usuário negar:

https://seuapp.com/callback?error=access_denied&error_description=O+usu%C3%A1rio+negou+o+acesso&state=random_csrf_string_123

Passo 4: Trocar Código por Token

Faça um POST server-side (nunca do frontend!) para trocar o código por tokens:

bash
curl -X POST https://api-backend.bunto.com.br/integracoes/oauth/token/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=bnt_code_xxx' \
  -d 'client_id=bnt_app_xxx' \
  -d 'client_secret=bnt_secret_xxx' \
  -d 'redirect_uri=https://seuapp.com/callback'

Resposta (200 OK):

json
{
  "access_token": "bnt_oat_A1b2C3d4E5f6G7h8...",
  "token_type": "Bearer",
  "expires_in": 14400,
  "refresh_token": "bnt_ort_X9y8Z7w6V5u4T3s2...",
  "scope": "produtos:read,vendas:read,vendas:write"
}

---

3. Usando o Access Token

Use o access_token para acessar a API v1:

bash
curl https://api-backend.bunto.com.br/v1/produtos/ \
  -H 'Authorization: Bearer bnt_oat_A1b2C3d4E5f6G7h8...' \
  -H 'Content-Type: application/json'

O access token funciona exatamente como um Token de API, mas com escopos granulares:

• Requisições fora do escopo retornam 403 Forbidden
• Módulos fora do plano da empresa retornam 403 Forbidden

---

4. Renovando o Access Token

Quando o access token expirar (4h), use o refresh token para obter um novo:

bash
curl -X POST https://api-backend.bunto.com.br/integracoes/oauth/token/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token' \
  -d 'refresh_token=bnt_ort_X9y8Z7w6V5u4T3s2...' \
  -d 'client_id=bnt_app_xxx' \
  -d 'client_secret=bnt_secret_xxx'

Resposta (200 OK):

json
{
  "access_token": "bnt_oat_novo_token_aqui...",
  "token_type": "Bearer",
  "expires_in": 14400,
  "scope": "produtos:read,vendas:read,vendas:write"
}

---

5. Revogando Tokens

Para revogar um token (logout, desconexão):

bash
curl -X POST https://api-backend.bunto.com.br/integracoes/oauth/revoke/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=bnt_oat_A1b2C3d4E5f6G7h8...' \
  -d 'client_id=bnt_app_xxx' \
  -d 'client_secret=bnt_secret_xxx' \
  -d 'token_type_hint=access_token'

Este endpoint sempre retorna 200 OK (mesmo se o token não existir), conforme RFC 7009.

---

Formato de Escopos

Escopos seguem o formato modulo:acao, separados por vírgula:

produtos:read,vendas:read,vendas:write,clientes:read

Ações disponíveis:

Módulos disponíveis:

Consulte o endpoint de escopos para ver os módulos disponíveis no plano da empresa:

bash
curl https://api-backend.bunto.com.br/integracoes/aplicativos/escopos/ \
  -H 'Cookie: access_token=...'

---

Tratamento de Erros

Erros no Endpoint de Autorização

Redirecionados para redirect_uri (exceto erros de redirect_uri):

Erros no Endpoint de Token

Retornados como JSON com status HTTP 400 ou 401:

json
{
  "error": "invalid_grant",
  "error_description": "Código de autorização inválido ou expirado"
}

---

Segurança

Boas Práticas

1. Nunca exponha o client_secret no código frontend ou repositórios públicos
2. Sempre valide o state para prevenir CSRF
3. Troque o código imediatamente (expira em 10 minutos, uso único)
4. Armazene tokens com segurança (banco de dados criptografado, nunca em localStorage)
5. Use HTTPS em todas as redirect_uris (obrigatório em produção)
6. Solicite apenas os escopos necessários (princípio do menor privilégio)
7. Implemente refresh para manter acesso sem re-autorizar o usuário

Limites

Revogação pelo Usuário

Usuários podem revogar o acesso do seu aplicativo a qualquer momento em Integrações → Aplicativos no painel do Bunto ERP. Quando revogado, todos os tokens associados são invalidados imediatamente.