Metadata-Version: 2.4
Name: bling-erp-api
Version: 0.1.0
Summary: Python SDK for the Bling ERP API with auth, pagination, and helpers.
Project-URL: Homepage, https://github.com/tempont/bling-erp-api-python
Project-URL: Documentation, https://tempont.github.io/bling-erp-api-python/
Project-URL: Repository, https://github.com/tempont/bling-erp-api-python
Project-URL: Issues, https://github.com/tempont/bling-erp-api-python/issues
Author-email: tempont <bragaramonsantana@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,bling,contabilidade,e-commerce,erp,estoque,nfce,nfe,nfse,nota-fiscal,produtos,python,sdk,vendas
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: bling-jwt-auth<1.0.0,>=0.4.0
Requires-Dist: httpx<1.0.0,>=0.28.1
Requires-Dist: pydantic-settings<3.0.0,>=2.14.1
Requires-Dist: pydantic<3.0.0,>=2.13.4
Requires-Dist: python-dotenv<2.0.0,>=1.2.2
Provides-Extra: codegen
Requires-Dist: datamodel-code-generator>=0.36.0; extra == 'codegen'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.6.23; extra == 'docs'
Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26.0; extra == 'docs'
Description-Content-Type: text/markdown

# Bling ERP API SDK

[![PyPI](https://img.shields.io/pypi/v/bling-erp-api)](https://pypi.org/project/bling-erp-api/)
[![Python Versions](https://img.shields.io/pypi/pyversions/bling-erp-api)](https://pypi.org/project/bling-erp-api/)
[![License](https://img.shields.io/pypi/l/bling-erp-api)](LICENSE)
[![CI](https://github.com/tempont/bling-erp-api-python/actions/workflows/ci.yml/badge.svg)](https://github.com/tempont/bling-erp-api-python/actions)

Unofficial Python SDK for the [Bling ERP API v3](https://lerosa.atlassian.net/wiki/spaces/JSON/pages/25362471/API+v3).

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

## Installation

```bash
pip install bling-erp-api
```

Or with `uv`:

```bash
uv add bling-erp-api
```

Python 3.12+ required.

## Quick Start

Set the required environment variables (see [Authentication](#authentication)):

```bash
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:

```python
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`](https://pypi.org/project/bling-jwt-auth/) package.

The simplest way to get started is with environment variables:

```bash
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](https://tempont.github.io/bling-erp-api-python/authentication/)
for details.

## Documentation

Full documentation is available at:

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

- [Getting Started](https://tempont.github.io/bling-erp-api-python/getting-started/)
- [Authentication](https://tempont.github.io/bling-erp-api-python/authentication/)
- [Pagination](https://tempont.github.io/bling-erp-api-python/pagination/)
- [Error Handling](https://tempont.github.io/bling-erp-api-python/errors/)
- [API Reference](https://tempont.github.io/bling-erp-api-python/api-reference/)

## Development

```bash
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](CONTRIBUTING.md) for contribution guidelines.

## License

MIT — see [LICENSE](LICENSE).
