bling-jwt-auth-python

Biblioteca Python para autenticação OAuth 2.0 na API v3 do Bling, com suporte ao modo JWT exigido pelos endpoints atuais da plataforma.

Use este pacote quando sua aplicação precisa obter, persistir e renovar tokens do Bling sem reimplementar o fluxo OAuth. Ele cobre o caminho mais comum de integração:

• gerar a URL de autorização para o usuário conectar a conta Bling;
• trocar o code do callback por access_token e refresh_token;
• salvar o token localmente em SQLite ou JSON;
• renovar automaticamente o access_token antes da expiração;
• montar os headers necessários para chamadas autenticadas à API v3.
• fazer chamadas autenticadas com connect(), BlingClient ou BlingAuth sem montar manualmente cliente OAuth, store, manager e headers.

Requisitos

• Python 3.12 ou superior
• Uma aplicação OAuth cadastrada no Bling
• client_id, client_secret e redirect_uri da aplicação OAuth

Estrutura

├── 📁 docs
│   └── 📝 README.en.md
├── 📁 examples
│   ├── 🐍 __init__.py
│   ├── 🐍 authenticated_request.py
│   ├── 🐍 client_request.py
│   ├── 🐍 httpx_auth_request.py
│   └── 🐍 oauth_flow.py
├── 📁 scripts
│   ├── 🐍 __init__.py
│   ├── 📄 check.sh
│   └── 🐍 package_version.py
├── 📁 src
│   └── 📁 bling_jwt_auth
│       ├── 📁 models
│       │   ├── 🐍 __init__.py
│       │   └── 🐍 token.py
│       ├── 📁 oauth
│       │   ├── 🐍 __init__.py
│       │   └── 🐍 client.py
│       ├── 📁 storage
│       │   ├── 🐍 __init__.py
│       │   ├── 🐍 base.py
│       │   ├── 🐍 factory.py
│       │   ├── 🐍 file.py
│       │   └── 🐍 sqlite.py
│       ├── 🐍 __init__.py
│       ├── 🐍 auth.py
│       ├── 🐍 client.py
│       ├── 🐍 config.py
│       ├── 🐍 constants.py
│       ├── 🐍 exceptions.py
│       ├── 🐍 headers.py
│       ├── 🐍 manager.py
│       └── 📄 py.typed
├── 📁 tests
│   ├── 🐍 __init__.py
│   ├── 🐍 conftest.py
│   ├── 🐍 test_auth.py
│   ├── 🐍 test_client.py
│   ├── 🐍 test_headers.py
│   ├── 🐍 test_oauth_client.py
│   ├── 🐍 test_storage_factory.py
│   ├── 🐍 test_storage_file.py
│   ├── 🐍 test_storage_sqlite.py
│   ├── 🐍 test_token_manager.py
│   └── 🐍 url_utils.py
├── ⚙️ .env.example
├── ⚙️ .gitignore
├── ⚙️ .pre-commit-config.yaml
├── 📄 LICENSE
├── 📄 Makefile
├── 📝 README.md
├── ⚙️ pyproject.toml
└── 📄 uv.lock

Instalação

pip install bling-jwt-auth

Instalação direta do repositório:

pip install "git+https://github.com/tempont/bling-jwt-auth-python.git"

Configuração

Copie o arquivo de exemplo e preencha as credenciais da sua aplicação no Bling:

cp .env.example .env

BLING_CLIENT_ID=seu_client_id
BLING_CLIENT_SECRET=seu_client_secret
BLING_REDIRECT_URI=https://seu-dominio.com/oauth/callback

Por padrão, os tokens são salvos em SQLite em ~/.config/bling_jwt_auth/tokens.db.

Para salvar em um arquivo JSON:

BLING_TOKEN_STORE=file
BLING_TOKEN_STORE_PATH=./token.json

Para salvar SQLite em um caminho específico:

BLING_TOKEN_STORE=sqlite
BLING_TOKEN_STORE_PATH=./bling-tokens.db

Fluxo OAuth

1. Gere a URL de autorização

from bling_jwt_auth import BlingAuthSettings, OAuthClient

settings = BlingAuthSettings.load()

with OAuthClient(settings) as oauth:
    url = oauth.build_authorization_url(state="valor-aleatorio-seguro")
    print(url)

Abra a URL no navegador, autorize a aplicação no Bling e capture o parâmetro code recebido no callback configurado em BLING_REDIRECT_URI.

2. Troque o code por tokens e persista

from bling_jwt_auth import BlingAuthSettings, OAuthClient, TokenManager, create_token_store

settings = BlingAuthSettings.load()
store = create_token_store(settings)

with OAuthClient(settings) as oauth:
    manager = TokenManager(oauth, store, settings)
    manager.save_from_code("code-recebido-no-callback")

3. Faça chamadas autenticadas

from bling_jwt_auth import connect

with connect() as bling:
    response = bling.get("/Api/v3/produtos")

response.raise_for_status()
print(response.json())

connect() carrega a configuração, abre o token store configurado, injeta os headers Authorization/enable-jwt e renova o token automaticamente quando necessário.

Para um estilo de SDK explícito:

from bling_jwt_auth import BlingClient

with BlingClient.from_env() as bling:
    response = bling.get("/Api/v3/produtos")

Para usar seu próprio cliente HTTP:

import httpx

from bling_jwt_auth import BlingAuth

with BlingAuth.from_env() as auth:
    with httpx.Client(auth=auth, base_url="https://api.bling.com.br") as client:
        response = client.get("/Api/v3/produtos")

Exemplos executáveis

Fluxo manual de OAuth:

uv run python examples/oauth_flow.py

O script imprime a URL de autorização. Depois de autorizar no Bling, cole no terminal o code recebido no callback.

Para tentar abrir o navegador automaticamente:

uv run python examples/oauth_flow.py --open

Teste de chamada autenticada:

uv run python examples/authenticated_request.py

Esse exemplo usa o mesmo token salvo pelo fluxo OAuth, renova se necessário e chama o endpoint de homologação de produtos do Bling.

As variações da nova API também estão disponíveis:

uv run python examples/client_request.py
uv run python examples/httpx_auth_request.py

API principal

Variáveis de ambiente

Tratamento de erros

• TokenNotFoundError: nenhum token foi salvo ainda. Execute o fluxo OAuth ou chame TokenManager.save_from_code().
• OAuthRequestError: o Bling retornou erro HTTP em troca, refresh ou revogação. A exceção preserva status_code e response_body.
• ValueError: argumentos obrigatórios vazios, como state, code ou refresh_token.

Segurança

• Não versione .env, token.json ou bancos SQLite com tokens.
• Use um state aleatório e valide-o no callback OAuth da sua aplicação.
• Configure BLING_REDIRECT_URI exatamente igual ao callback cadastrado no Bling.
• Em produção, prefira guardar credenciais em variáveis de ambiente ou secret manager.
• O backend JSON aplica permissão 0600 em sistemas POSIX depois da escrita.

Desenvolvimento

Rodar lint, checagem de tipos e testes:

make check

Ou:

bash scripts/check.sh

Rodar apenas testes:

uv run --extra dev pytest

Gerar artefatos de distribuição local:

uv run --extra dev python -m build
uv run --extra dev python -m twine check dist/*

Licença

MIT. Veja LICENSE.