Estrutura da Autenticação com o Bling

Esta seção descreve o fluxo de autenticação e o gerenciamento de tokens utilizado na integração com o Bling.

Visão Geral

A autenticação com o Bling utiliza o protocolo OAuth 2.0, permitindo ao sistema obter e renovar automaticamente os tokens de acesso necessários para realizar requisições à API.

O fluxo é composto por duas etapas principais:

1. Autorização inicial: o usuário concede acesso ao sistema via redirecionamento e callback.
2. Renovação automática: o sistema mantém o access_token atualizado usando o refresh_token salvo.

---

Componentes Principais da Implementação

• app/Integrations/Bling/BlingAPI.php Classe central da integração. Gerencia as requisições HTTP autenticadas, controla o rate limit e contém o método refreshToken() para renovar o access_token usando o refresh_token armazenado.

• app/Http/Controllers/BlingController.php Controla o fluxo OAuth 2.0:

  • Redireciona o usuário para a página de autorização do Bling.
  • Recebe o callback com o code de autorização.
  • Usa a BlingAPI para trocar o código por access_token e refresh_token.
  • Armazena os tokens no banco via Setting::setValue().

• app/Console/Commands/BlingRefreshTokenCommand.php Comando Artisan responsável por renovar o token periodicamente. É agendado via cron, garantindo que o sistema mantenha o acesso contínuo à API sem necessidade de reautenticação manual.

• app/Enums/SettingKeys.php Enum que define as chaves usadas para armazenar os tokens e outras configurações relacionadas ao Bling.

---

Relação entre os Componentes

Componente	Responsabilidade
BlingController	Executa o fluxo OAuth 2.0 (autorização e callback).
BlingAPI	Gerencia o token atual e executa a renovação.
Setting	Persiste os tokens de acesso e atualização.
SettingKeys	Centraliza as chaves de configuração.
BlingRefreshTokenCommand	Automatiza a renovação do access_token.

---

Fluxo de Autenticação

1. O usuário inicia o processo de autorização pelo painel administrativo.
2. O BlingController redireciona o usuário para a página de autorização do Bling.
3. O Bling redireciona de volta para o sistema com o code de autorização.
4. O BlingController utiliza a BlingAPI para trocar o code por access_token e refresh_token.
5. Os tokens são armazenados via Setting::setValue() utilizando as chaves de SettingKeys.
6. A BlingAPI inclui o access_token em todas as requisições autenticadas.
7. Quando o token expira, o comando app:bling-refresh-token renova o acesso automaticamente.

---

Armazenamento dos Tokens

• Variáveis de ambiente (.env):

  • BLING_CLIENT_ID
  • BLING_CLIENT_SECRET
  • BLING_REDIRECT_URI

• Banco de dados (settings table):

  • bling_access_token (SettingKeys::BLING_ACCESS_TOKEN)
  • bling_refresh_token (SettingKeys::BLING_REFRESH_TOKEN)
  • bling_token_expires_at

Essas informações permitem que o sistema mantenha o estado de autenticação sem necessidade de repetição do fluxo inicial.

---

Segurança e Logs

• As credenciais de cliente (CLIENT_ID, CLIENT_SECRET) nunca são registradas em logs.
• O sistema usa Http::withBasicAuth() apenas durante a primeira troca de código por tokens.
• Operações sensíveis são registradas em storage/logs/bling.log, com dados sigilosos mascarados.
• O RateLimiter (Illuminate\Support\Facades\RateLimiter) limita as chamadas à API para evitar bloqueios.