bling-jwt-auth 0.1.0

OAuth 2.0 / JWT authentication helpers for the Bling API v3

bling-jwt-auth-python

Repositório: github.com/tempont/bling-jwt-auth-python · PyPI: bling-jwt-auth

Biblioteca Python simples para autenticar na API v3 do Bling usando OAuth 2.0 e tokens JWT.

Ela ajuda a:

• gerar a URL de autorização do Bling;
• trocar o code recebido por tokens;
• salvar os tokens em arquivo ou SQLite;
• renovar o access token automaticamente quando necessário;
• montar os headers corretos para chamar a API do Bling.

Versão em inglês: docs/README.en.md

Requisitos

• Python 3.14 ou superior
• Uma aplicação OAuth cadastrada no Bling

Instalação

Instale pelo pip:

pip install bling-jwt-auth

Ou instale direto do GitHub:

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

Para desenvolvimento local neste repositório, use:

uv sync --extra dev

Configuração

Copie o arquivo de exemplo:

cp .env.example .env

Edite o .env com os dados da sua aplicação no Bling:

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. Se quiser salvar em JSON:

BLING_TOKEN_STORE=file
BLING_TOKEN_STORE_PATH=./token.json

Como usar

1. Autorizar a conta Bling

Rode o exemplo de OAuth:

uv run python examples/oauth_flow.py

O script vai mostrar uma URL. Abra essa URL no navegador, autorize o acesso no Bling e cole no terminal o code recebido no callback.

Se quiser que o script tente abrir o navegador automaticamente:

uv run python examples/oauth_flow.py --open

2. Testar uma chamada autenticada

Depois de salvar o token, rode:

uv run python examples/authenticated_request.py

Esse exemplo usa o token salvo, renova se necessário e chama um endpoint de homologação do Bling.

3. Usar no seu código

import httpx
from bling_jwt_auth import (
    BlingAuthSettings,
    OAuthClient,
    TokenManager,
    bling_api_headers,
    create_token_store,
)

settings = BlingAuthSettings()
store = create_token_store(settings)

with OAuthClient(settings) as oauth:
    manager = TokenManager(oauth, store, settings)
    access_token = manager.get_access_token()

headers = bling_api_headers(access_token)

response = httpx.get(
    "https://api.bling.com.br/Api/v3/produtos",
    headers=headers,
)
response.raise_for_status()
print(response.json())

Comandos úteis para desenvolvimento

Rodar lint, checagem de tipos e testes:

make check

Ou:

bash scripts/check.sh

Rodar apenas os testes:

uv run --extra dev pytest

Licença

MIT. Veja LICENSE.