bling-erp-api 0.1.0

Python SDK for the Bling ERP API with auth, pagination, and helpers.

Bling ERP API SDK

Unofficial Python SDK for the Bling ERP API v3.

Provides typed, idiomatic access to 40+ Bling ERP resources with sync/async transports, OAuth2 authentication, rate limiting, and automatic retry.

Installation

pip install bling-erp-api

Or with uv:

uv add bling-erp-api

Python 3.12+ required.

Quick Start

Set the required environment variables (see Authentication):

export BLING_CLIENT_ID="your_client_id"
export BLING_CLIENT_SECRET="your_client_secret"
export BLING_REFRESH_TOKEN="your_refresh_token"

Then use the SDK:

from bling_erp_api import BlingClient

with BlingClient.from_env() as client:
    # List products
    products = client.produtos.listar(limit=10)
    for product in products.get("data", []):
        print(product.get("nome"))

    # Get a contact
    contact = client.contatos.obter(1)
    print(contact)

Features

• 40+ resource modules covering the full Bling ERP API surface
• OAuth2 authentication via bling-jwt-auth — automatic token refresh
• Rate limiting (3 req/s default) with 429 retry and Retry-After support
• Typed models with Pydantic v2 — snake_case fields, automatic Bling name mapping
• Sync and async transports
• pt-BR canonical API with English compatibility aliases
• OpenAPI contract validation — generated and tested against the spec
• 500+ tests with mocked HTTP

Resources

pt-BR Namespace	EN Alias	Description
client.contatos	client.contacts	Contacts CRUD and status management
client.produtos	client.products	Products CRUD and status
client.produtos_estruturas	client.product_structures	Product structures (BOM)
client.produtos_fornecedores	client.product_suppliers	Product suppliers
client.produtos_lojas	client.product_stores	Product store mappings
client.lotes	client.product_batches	Product batches
client.lotes_lancamentos	client.product_batch_entries	Batch entries
client.produtos_variacoes	client.product_variations	Product variations
client.pedidos_vendas	client.sales_orders	Sales orders
client.pedidos_compras	client.purchase_orders	Purchase orders
client.notas_fiscais	client.invoices	NF-e (electronic invoices)
client.notas_fiscais_consumidor	client.consumer_invoices	NFC-e (consumer invoices)
client.notas_servicos	client.service_invoices	NFS-e (service invoices)
client.anuncios	client.ads	Marketplace ads
client.anuncios_categorias	client.ad_categories	Ad categories
client.caixas_bancos	client.cash_entries	Cash and bank entries
client.borderos	client.payment_bundles	Bordero management
client.categorias_lojas	client.store_categories	Store categories
client.categorias_produtos	client.product_categories	Product categories
client.categorias_receitas_despesas	client.income_expense_categories	Income/expense categories
client.contas_pagar	client.accounts_payable	Accounts payable
client.contas_receber	client.accounts_receivable	Accounts receivable
client.contas_contabeis	client.financial_accounts	Financial/chart of accounts
client.depositos	client.warehouses	Warehouses
client.empresas	client.companies	Company data
client.estoques	client.stock	Stock balances
client.formas_pagamentos	client.payment_methods	Payment methods
client.grupos_produtos	client.product_groups	Product groups
client.homologacao	client.homologation	Test/homologation
client.logisticas	client.logistics	Logistics providers
client.logisticas_servicos	client.logistics_services	Logistics services
client.logisticas_objetos	client.logistics_objects	Logistics objects
client.logisticas_etiquetas	client.logistics_labels	Shipping labels
client.logisticas_remessas	client.logistics_shipments	Logistics shipments
client.naturezas_operacoes	client.natures_of_operations	Tax natures
client.notificacoes	client.notifications	Notifications
client.ordens_producao	client.production_orders	Production orders
client.propostas_comerciais	client.commercial_proposals	Commercial proposals
client.situacoes	client.situations	Status/situations
client.situacoes_modulos	client.situation_modules	Situation modules
client.situacoes_transicoes	client.situation_transitions	Situation transitions
client.vendedores	client.sellers	Sellers
client.usuarios	client.users	User management

Authentication

The SDK uses OAuth2 (authorization code flow) delegated to the bling-jwt-auth package.

The simplest way to get started is with environment variables:

export BLING_CLIENT_ID="your_client_id"
export BLING_CLIENT_SECRET="your_client_secret"
export BLING_REFRESH_TOKEN="your_refresh_token"
export BLING_REDIRECT_URI="your_redirect_uri"  # optional

Then create a client with BlingClient.from_env().

For custom authentication, pass a token_provider implementing get_access_token() -> str or an httpx.Auth instance.

See the Authentication documentation for details.

Documentation

Full documentation is available at:

https://tempont.github.io/bling-erp-api-python/

• Getting Started
• Authentication
• Pagination
• Error Handling
• API Reference

Development

git clone https://github.com/tempont/bling-erp-api-python.git
cd bling-erp-api-python
uv sync --all-groups
make check

See CONTRIBUTING.md for contribution guidelines.

License

MIT — see LICENSE.