Skip to content

Cliente

bling_erp_api.client.BlingClient 

BlingClient(
    *,
    token_provider: AccessTokenProvider | None = None,
    auth: Auth | None = None,
    base_url: str = DEFAULT_API_BASE_URL,
    timeout: float = DEFAULT_TIMEOUT_SECONDS,
    http_client: Client | None = None,
    rate_limit_max_requests: int | None = DEFAULT_RATE_LIMIT_MAX_REQUESTS,
    rate_limit_period_seconds: float = DEFAULT_RATE_LIMIT_PERIOD_SECONDS,
    rate_limit_max_retries: int = DEFAULT_RATE_LIMIT_MAX_RETRIES,
)

Synchronous client for the Bling ERP REST API.

The client exposes resource namespaces that map to Bling API endpoints. Canonical method names are in Portuguese (pt-BR); English compatibility aliases are available for backwards compatibility.

Usage

Create a client from environment variables with from_env(), or instantiate directly with a token provider or auth adapter::

with BlingClient.from_env() as client:
    produtos = client.produtos.listar()
Namespaces
  • client.produtos / client.products — produtos
  • client.contatos / client.contacts — contatos
  • client.pedidos_vendas / client.sales_orders — pedidos de venda
  • client.pedidos_compras / client.purchase_orders — pedidos de compra
  • client.notas_fiscais / client.invoices — NF-e
  • client.notas_fiscais_consumidor / client.consumer_invoices — NFC-e
  • client.notas_servicos / client.service_invoices — NFS-e
  • client.anuncios / client.ads — anúncios
  • client.contas_pagar / client.accounts_payable — contas a pagar
  • client.contas_receber / client.accounts_receivable — contas a receber
  • client.estoques / client.stock — estoques
  • client.ordens_producao / client.production_orders — ordens de produção
  • client.logisticas / client.logistics — logísticas
  • client.situacoes / client.situations — situações
  • client.usuarios / client.users — usuários
Rate limiting

A local rate limiter (3 requests/second by default) is enabled automatically. HTTP 429 responses are retried with Retry-After support.

Create a client and attach resource namespaces.

Source code in src/bling_erp_api/client.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
def __init__(  # noqa: PLR0913
    self,
    *,
    token_provider: AccessTokenProvider | None = None,
    auth: httpx.Auth | None = None,
    base_url: str = DEFAULT_API_BASE_URL,
    timeout: float = DEFAULT_TIMEOUT_SECONDS,
    http_client: httpx.Client | None = None,
    rate_limit_max_requests: int | None = DEFAULT_RATE_LIMIT_MAX_REQUESTS,
    rate_limit_period_seconds: float = DEFAULT_RATE_LIMIT_PERIOD_SECONDS,
    rate_limit_max_retries: int = DEFAULT_RATE_LIMIT_MAX_RETRIES,
) -> None:
    """Create a client and attach resource namespaces."""
    load_env()
    resolved_auth = auth or _auth_from_token_provider(token_provider)
    self._transport = SyncTransport(
        auth=resolved_auth,
        base_url=base_url,
        timeout=timeout,
        client=http_client,
        rate_limit_max_requests=rate_limit_max_requests,
        rate_limit_period_seconds=rate_limit_period_seconds,
        rate_limit_max_retries=rate_limit_max_retries,
    )

    self._contacts = ContactsResource(self._transport)
    self._products = ProductsResource(self._transport)
    self._produtos_estruturas = ProductStructuresResource(self._transport)
    self._produtos_fornecedores = ProductSuppliersResource(self._transport)
    self._produtos_lojas = ProductStoresResource(self._transport)
    self._lotes = ProductBatchesResource(self._transport)
    self._lotes_lancamentos = ProductBatchEntriesResource(self._transport)
    self._produtos_variacoes = ProductVariationsResource(self._transport)
    self._sales_orders = SalesOrdersResource(self._transport)
    self._purchase_orders = PurchaseOrdersResource(self._transport)
    self._nfe = NfeResource(self._transport)
    self._nfce = NfceResource(self._transport)
    self._nfse = NfseResource(self._transport)
    self._anuncios = AdsResource(self._transport)
    self._anuncios_categorias = AdCategoriesResource(self._transport)
    self._caixas_bancos = CaixasBancosResource(self._transport)
    self._borderos = BorderosResource(self._transport)
    self._store_categories = StoreCategoriesResource(self._transport)
    self._product_categories = ProductCategoriesResource(self._transport)
    self._income_expense_categories = IncomeExpenseCategoriesResource(self._transport)

    self._contas_pagar = ContasPagarResource(self._transport)
    self._contas_receber = ContasReceberResource(self._transport)
    self._contas_contabeis = ContasContabeisResource(self._transport)

    self._depositos = DepositosResource(self._transport)
    self._empresas = EmpresasResource(self._transport)
    self._estoques = EstoquesResource(self._transport)

    self._payment_methods = PaymentMethodsResource(self._transport)
    self._product_groups = ProductGroupsResource(self._transport)
    self._homologation = HomologationResource(self._transport)

    self._logisticas = LogisticasResource(self._transport)
    self._logisticas_servicos = LogisticasServicosResource(self._transport)
    self._logisticas_objetos = LogisticasObjetosResource(self._transport)
    self._logisticas_etiquetas = LogisticasEtiquetasResource(self._transport)
    self._logisticas_remessas = LogisticasRemessasResource(self._transport)
    self._naturezas_operacoes = NaturezasOperacoesResource(self._transport)

    self._notificacoes = NotificacoesResource(self._transport)
    self._ordens_producao = OrdensProducaoResource(self._transport)

    self._commercial_proposals = CommercialProposalsResource(self._transport)

    self._situacoes = SituacoesResource(self._transport)
    self._situacoes_modulos = SituacoesModulosResource(self._transport)
    self._situacoes_transicoes = SituacoesTransicoesResource(self._transport)

    self._vendedores = VendedoresResource(self._transport)
    self._usuarios = UsuariosResource(self._transport)

contacts property 

contacts: ContactsResource

Alias em inglês para contatos. Contact operations on /contatos.

contatos property 

contatos: ContactsResource

Operações de contatos (/contatos).

products property 

products: ProductsResource

Alias em inglês para produtos. Product operations on /produtos.

produtos property 

produtos: ProductsResource

Operações de produtos (/produtos). Bling API v3.

produtos_estruturas property 

produtos_estruturas: ProductStructuresResource

Operações de estruturas de produtos (/produtos/estruturas).

product_structures property 

product_structures: ProductStructuresResource

Alias em inglês para produtos_estruturas. Product structures (/produtos/estruturas).

produtos_fornecedores property 

produtos_fornecedores: ProductSuppliersResource

Operações de fornecedores de produtos (/produtos/fornecedores).

product_suppliers property 

product_suppliers: ProductSuppliersResource

Alias em inglês para produtos_fornecedores. Product suppliers (/produtos/fornecedores).

produtos_lojas property 

produtos_lojas: ProductStoresResource

Operações de lojas de produtos (/produtos/lojas).

product_stores property 

product_stores: ProductStoresResource

Alias em inglês para produtos_lojas. Product stores (/produtos/lojas).

lotes property 

lotes: ProductBatchesResource

Operações de lotes de produtos (/produtos/lotes).

product_batches property 

product_batches: ProductBatchesResource

Alias em inglês para lotes. Product batches (/produtos/lotes).

lotes_lancamentos property 

lotes_lancamentos: ProductBatchEntriesResource

Operações de lançamentos de lotes (/produtos/lotes/lancamentos).

product_batch_entries property 

product_batch_entries: ProductBatchEntriesResource

Alias em inglês para lotes_lancamentos. Product batch entries (/produtos/lotes/lancamentos).

produtos_variacoes property 

produtos_variacoes: ProductVariationsResource

Operações de variações de produtos (/produtos/variacoes).

product_variations property 

product_variations: ProductVariationsResource

Alias em inglês para produtos_variacoes. Product variations (/produtos/variacoes).

sales_orders property 

sales_orders: SalesOrdersResource

Alias em inglês para pedidos_vendas. Sales order operations on /pedidos/vendas.

pedidos_vendas property 

pedidos_vendas: SalesOrdersResource

Operações de pedidos de venda (/pedidos/vendas). Bling API v3.

pedidos_compras property 

pedidos_compras: PurchaseOrdersResource

Pedidos de compra — operações em /pedidos/compras.

purchase_orders property 

purchase_orders: PurchaseOrdersResource

Alias for pedidos_compras. Purchase order operations on /pedidos/compras.

notas_fiscais property 

notas_fiscais: NfeResource

Operações de notas fiscais eletrônicas (/nfe).

invoices property 

invoices: NfeResource

Alias em inglês para notas_fiscais. NF-e (/nfe).

notas_fiscais_consumidor property 

notas_fiscais_consumidor: NfceResource

Operações de notas fiscais do consumidor (/nfce).

consumer_invoices property 

consumer_invoices: NfceResource

Alias em inglês para notas_fiscais_consumidor. NFC-e (/nfce).

notas_servicos property 

notas_servicos: NfseResource

Operações de notas fiscais de serviço (/nfse).

service_invoices property 

service_invoices: NfseResource

Alias em inglês para notas_servicos. NFS-e (/nfse).

anuncios property 

anuncios: AdsResource

Anúncios (Ads) — operações em /anuncios.

ads property 

ads: AdsResource

Alias for anuncios. Ads operations on /anuncios.

anuncios_categorias property 

anuncios_categorias: AdCategoriesResource

Categorias de anúncios — operações em /anuncios/categorias.

ad_categories property 

ad_categories: AdCategoriesResource

Alias for anuncios_categorias. Ad category operations on /anuncios/categorias.

caixas_bancos property 

caixas_bancos: CaixasBancosResource

Lançamentos de caixas e bancos — operações em /caixas.

cash_entries property 

cash_entries: CaixasBancosResource

Alias for caixas_bancos. Cash/bank entry operations on /caixas.

borderos property 

borderos: BorderosResource

Borderôs — operações em /borderos.

categorias_lojas property 

categorias_lojas: StoreCategoriesResource

Categorias de lojas — operações em /categorias/lojas.

store_categories property 

store_categories: StoreCategoriesResource

Alias for categorias_lojas. Store category operations on /categorias/lojas.

categorias_produtos property 

categorias_produtos: ProductCategoriesResource

Categorias de produtos — operações em /categorias/produtos.

product_categories property 

product_categories: ProductCategoriesResource

Alias for categorias_produtos. Product category operations on /categorias/produtos.

categorias_receitas_despesas property 

categorias_receitas_despesas: IncomeExpenseCategoriesResource

Categorias de receitas e despesas — operações em /categorias/receitas-despesas.

income_expense_categories property 

income_expense_categories: IncomeExpenseCategoriesResource

Alias for categorias_receitas_despesas. Income/expense category operations on /categorias/receitas-despesas.

contas_pagar property 

contas_pagar: ContasPagarResource

Contas a pagar — operações em /contas/pagar.

accounts_payable property 

accounts_payable: ContasPagarResource

Alias for contas_pagar. Accounts payable operations on /contas/pagar.

contas_receber property 

contas_receber: ContasReceberResource

Contas a receber — operações em /contas/receber.

accounts_receivable property 

accounts_receivable: ContasReceberResource

Alias for contas_receber. Accounts receivable operations on /contas/receber.

contas_contabeis property 

contas_contabeis: ContasContabeisResource

Contas financeiras — operações em /contas-contabeis.

financial_accounts property 

financial_accounts: ContasContabeisResource

Alias for contas_contabeis. Financial accounts operations on /contas-contabeis.

depositos property 

depositos: DepositosResource

Depósitos — operações em /depositos.

warehouses property 

warehouses: DepositosResource

Alias for depositos. Warehouse operations on /depositos.

empresas property 

empresas: EmpresasResource

Empresas — operações em /empresas.

companies property 

companies: EmpresasResource

Alias for empresas. Company operations on /empresas.

estoques property 

estoques: EstoquesResource

Estoques — operações em /estoques.

stock property 

stock: EstoquesResource

Alias for estoques. Stock operations on /estoques.

formas_pagamentos property 

formas_pagamentos: PaymentMethodsResource

Formas de pagamentos — operações em /formas-pagamentos.

payment_methods property 

payment_methods: PaymentMethodsResource

Alias for formas_pagamentos. Payment method operations on /formas-pagamentos.

grupos_produtos property 

grupos_produtos: ProductGroupsResource

Grupos de produtos — operações em /grupos-produtos.

product_groups property 

product_groups: ProductGroupsResource

Alias for grupos_produtos. Product group operations on /grupos-produtos.

homologacao property 

homologacao: HomologationResource

Homologação — operações em /homologacao/produtos.

homologation property 

homologation: HomologationResource

Alias for homologacao. Homologation operations on /homologacao/produtos.

logisticas property 

logisticas: LogisticasResource

Logísticas — operações em /logisticas.

logistics property 

logistics: LogisticasResource

Alias for logisticas. Logistics operations on /logisticas.

logisticas_servicos property 

logisticas_servicos: LogisticasServicosResource

Serviços de logísticas — operações em /logisticas/servicos.

logistics_services property 

logistics_services: LogisticasServicosResource

Alias for logisticas_servicos. Logistics service operations on /logisticas/servicos.

logisticas_objetos property 

logisticas_objetos: LogisticasObjetosResource

Objetos de logísticas — operações em /logisticas/objetos.

logistics_objects property 

logistics_objects: LogisticasObjetosResource

Alias for logisticas_objetos. Logistics object operations on /logisticas/objetos.

logisticas_etiquetas property 

logisticas_etiquetas: LogisticasEtiquetasResource

Etiquetas de logísticas — operações em /logisticas/etiquetas.

logistics_labels property 

logistics_labels: LogisticasEtiquetasResource

Alias for logisticas_etiquetas. Logistics label operations on /logisticas/etiquetas.

logisticas_remessas property 

logisticas_remessas: LogisticasRemessasResource

Remessas de logísticas — operações em /logisticas/remessas.

logistics_shipments property 

logistics_shipments: LogisticasRemessasResource

Alias for logisticas_remessas. Logistics shipment operations on /logisticas/remessas.

naturezas_operacoes property 

naturezas_operacoes: NaturezasOperacoesResource

Naturezas de Operações — operações em /naturezas-operacoes.

natures_of_operations property 

natures_of_operations: NaturezasOperacoesResource

Alias for naturezas_operacoes. Tax nature operations on /naturezas-operacoes.

notificacoes property 

notificacoes: NotificacoesResource

Notificações — operações em /notificacoes.

notifications property 

notifications: NotificacoesResource

Alias for notificacoes. Notification operations on /notificacoes.

ordens_producao property 

ordens_producao: OrdensProducaoResource

Ordens de Produção — operações em /ordens-producao.

production_orders property 

production_orders: OrdensProducaoResource

Alias for ordens_producao. Production order operations on /ordens-producao.

propostas_comerciais property 

propostas_comerciais: CommercialProposalsResource

Propostas Comerciais — operações em /propostas-comerciais.

commercial_proposals property 

commercial_proposals: CommercialProposalsResource

Alias for propostas_comerciais. Commercial proposals on /propostas-comerciais.

situacoes property 

situacoes: SituacoesResource

Situações — operações em /situacoes.

situations property 

situations: SituacoesResource

Alias for situacoes. Situation operations on /situacoes.

situacoes_modulos property 

situacoes_modulos: SituacoesModulosResource

Módulos de Situações — operações em /situacoes/modulos.

situation_modules property 

situation_modules: SituacoesModulosResource

Alias for situacoes_modulos. Situation module operations on /situacoes/modulos.

situacoes_transicoes property 

situacoes_transicoes: SituacoesTransicoesResource

Transições de Situações — operações em /situacoes/transicoes.

situation_transitions property 

situation_transitions: SituacoesTransicoesResource

Alias for situacoes_transicoes. Situation transition operations on /situacoes/transicoes.

vendedores property 

vendedores: VendedoresResource

Vendedores — operações em /vendedores.

sellers property 

sellers: VendedoresResource

Alias for vendedores. Seller operations on /vendedores.

usuarios property 

usuarios: UsuariosResource

Usuários — operações em /usuarios.

users property 

users: UsuariosResource

Alias for usuarios. User operations on /usuarios.

from_env classmethod 

from_env(
    *,
    base_url: str = DEFAULT_API_BASE_URL,
    timeout: float = DEFAULT_TIMEOUT_SECONDS,
    http_client: Client | None = None,
    rate_limit_max_requests: int | None = DEFAULT_RATE_LIMIT_MAX_REQUESTS,
    rate_limit_period_seconds: float = DEFAULT_RATE_LIMIT_PERIOD_SECONDS,
    rate_limit_max_retries: int = DEFAULT_RATE_LIMIT_MAX_RETRIES,
) -> Self

Create a client using BLING_* settings from bling-jwt-auth.

Rate limiting is enabled by default (3 requests/second). Pass rate_limit_max_requests=None to disable it (not recommended for production use).

Source code in src/bling_erp_api/client.py 
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
@classmethod
def from_env(  # noqa: PLR0913
    cls,
    *,
    base_url: str = DEFAULT_API_BASE_URL,
    timeout: float = DEFAULT_TIMEOUT_SECONDS,
    http_client: httpx.Client | None = None,
    rate_limit_max_requests: int | None = DEFAULT_RATE_LIMIT_MAX_REQUESTS,
    rate_limit_period_seconds: float = DEFAULT_RATE_LIMIT_PERIOD_SECONDS,
    rate_limit_max_retries: int = DEFAULT_RATE_LIMIT_MAX_RETRIES,
) -> Self:
    """Create a client using ``BLING_*`` settings from ``bling-jwt-auth``.

    Rate limiting is enabled by default (3 requests/second).
    Pass ``rate_limit_max_requests=None`` to disable it
    (not recommended for production use).
    """
    load_env()
    return cls(
        auth=BlingAuthAdapter.from_env(),
        base_url=base_url,
        timeout=timeout,
        http_client=http_client,
        rate_limit_max_requests=rate_limit_max_requests,
        rate_limit_period_seconds=rate_limit_period_seconds,
        rate_limit_max_retries=rate_limit_max_retries,
    )

close 

close() -> None

Close owned resources.

Source code in src/bling_erp_api/client.py 
650
651
652
def close(self) -> None:
    """Close owned resources."""
    self._transport.close()

__enter__ 

__enter__() -> Self

Return this client for context manager usage.

Source code in src/bling_erp_api/client.py 
659
660
661
def __enter__(self) -> Self:
    """Return this client for context manager usage."""
    return self

__exit__ 

__exit__(
    exc_type: type[BaseException] | None,
    exc: BaseException | None,
    traceback: TracebackType | None,
) -> None

Close resources when leaving a context manager.

Source code in src/bling_erp_api/client.py 
663
664
665
666
667
668
669
670
def __exit__(
    self,
    exc_type: type[BaseException] | None,
    exc: BaseException | None,
    traceback: TracebackType | None,
) -> None:
    """Close resources when leaving a context manager."""
    self.close()