Bling is a comprehensive business management platform that provides tools for invoicing (NFe, NFCe, NFSe), inventory control, sales management, financial operations (accounts payable/receivable), and CRM. It helps businesses streamline their operations with integrated solutions for e-commerce, accounting, and logistics.

Configuring Bling as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Bling option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

You’ll need OAuth credentials to connect to Bling. Log in with your Bling account to generate the access token. Make sure you use an account with sufficient privileges to access your Bling data. The following configurations are available: The following configurations are available:

Start Date: Records created or updated after this date will be extracted from the source.
Lookback Window: The number of days to look back when re-fetching records based on the replication key (default: 30 days).

Once you’re done, click Next.

2. Select streams

Choose which data streams you want to sync - you can select all streams or pick specific ones that matter most to you. The available streams include invoices (NFe, NFSe), products, sales orders, accounts payable/receivable, cash registers, stock balances, contacts, and more.

Tip: The stream can be found more easily by typing its name.

Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
- Incremental: every time the extraction happens, we’ll get only the new data - which is good if, for example, you want to keep every record ever fetched.
- Full table: every time the extraction happens, we’ll get the current state of the data - which is good if, for example, you don’t want to have deleted data in your catalog.

Bling API only allows fetching historical data from 2025-01-01.

Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:

Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

Once you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

For you to be able to see it on your Catalog, you need at least one successful source run.

API Limitations & Performance

Important: Bling has strict API rate limits that affect extraction performance:

~3 requests per second (rate limited to 1 request per 0.35 seconds to prevent burst rejections)
120,000 requests per day (daily quota). If this limit is reached during a run, the extraction will stop gracefully, save its state, and resume from where it left off in the next scheduled run.

Understanding Sync Times

Bling uses a parent-child stream architecture for detailed data. For each parent record (e.g., a Product or Sales Order), an additional API request is made to fetch the detailed information. This means:

Products + Product Details: 1 request for the list + 1 request per product
Product Stores + Product Store Details: 1 request for the list + 1 request per product-store link
Sales Orders + Sales Order Details: 1 request for the list + 1 request per order
Purchase Orders + Purchase Order Details: 1 request for the list + 1 request per order
Contracts + Contract Details: 1 request for the list + 1 request per contract
NFe + NFe Details: 1 request for the list + 1 request per invoice
NFCe + NFCe Details: 1 request for the list + 1 request per invoice
Contacts + Contact Details: 1 request for the list + 1 request per contact
Stock Balances: Batch requests for multiple products to optimize API usage

Tip for faster syncs: If you don’t need the detailed information, consider syncing only the parent streams (e.g., Products without Product Details). This significantly reduces the number of API calls and sync time.

For example, if you have 10,000 products and select both Products and Product Details streams:

At 3 requests/second, fetching all product details alone would take approximately 55 minutes
With 120,000 daily requests, you’re limited to syncing approximately 120,000 detailed records per day
If you have more than 120,000 detailed records in your account, an initial sync might hit the daily limit. The connector handles this by gracefully pausing the extraction when the limit is reached and automatically resuming during the next run until all historical data is fetched.

Recommendations:

Start with a minimal set of streams and add more as needed
Use incremental sync when available to reduce the number of records fetched
Schedule full syncs during off-peak hours if you have large datasets
Consider syncing only parent streams if detailed data isn’t required

Stream to Endpoint Mapping

Stream	API Endpoint	Sync Type	Notes
NFe	`/nfe`	Incremental	Uses `dataEmissao` as replication key
NFe Details	`/nfe/{id}`	Incremental	Child stream - 1 request per NFe
NFe Document	`/nfe/documento/{nfe_chave_acesso}`	Incremental	Child stream - 1 request per NFe
NFSe	`/nfse`	Incremental	Uses `dataEmissao` as replication key
NFe Situation	Static	Full Table	Reference data
NFSe Situation	Static	Full Table	Reference data
Operation Types	`/naturezas-operacoes`	Full Table
Products	`/produtos`	Incremental	Uses `dataFiltroAlteracao` as replication key
Product Details	`/produtos/{id}`	Incremental	Child stream - 1 request per product
Product Categories	`/categorias/produtos`	Full Table
Product Stores	`/produtos/lojas`	Full Table
Product Store Details	`/produtos/lojas/{id}`	Full Table	Child stream - 1 request per product-store link
Sales Orders	`/pedidos/vendas`	Incremental	Uses `dataFiltroAlteracao` as replication key
Sales Order Details	`/pedidos/vendas/{id}`	Incremental	Child stream - 1 request per order
Accounts Receivable	`/contas/receber`	Incremental	Uses `dataEmissao` as replication key
Accounts Receivable Details	`/contas/receber/{id}`	Incremental	Child stream - 1 request per receivable
Borderos	`/borderos/{bordero_id}`	Incremental	Child stream - 1 request per bordero
Accounts Payable	`/contas/pagar`	Incremental	Uses `dataFiltro` as replication key
Accounts Payable Details	`/contas/pagar/{id}`	Incremental	Child stream - 1 request per payable
Boleto	`/contas/receber/{id}`	Incremental	Uses `dataEmissaoNfe` as replication key
Cash Registers	`/caixas`	Incremental	Uses `data` as replication key
Accounting Accounts	`/contas-contabeis`	Full Table
Revenue Expense Categories	`/categorias/receitas-despesas`	Full Table
Revenue Expense Category Details	`/categorias/receitas-despesas/{id}`	Full Table	Child stream
Store Categories	`/categorias/lojas`	Full Table
Store Category Details	`/categorias/lojas/{id}`	Full Table	Child stream
Situation Modules	`/situacoes/modulos`	Full Table
Situations	`/situacoes/modulos/{module_id}`	Full Table	Child stream - 1 request per module
Stock Balances	`/estoques/saldos`	Incremental	Child stream - batch requests for multiple products
Contacts	`/contatos`	Incremental	Uses `dataFiltroAlteracao` as replication key
Contact Details	`/contatos/{id}`	Incremental	Child stream - 1 request per contact

Streams and Fields

Below you’ll find all available data streams from Bling and their corresponding fields:

Invoices & Fiscal Documents

Contacts & CRM

Contacts

Stream for managing contacts (customers, suppliers, partners). Supports incremental sync using modification date filter.

Field	Type	Description
`id`	Integer	The contact ID
`nome`	String	The contact name
`codigo`	String	The contact code
`situacao`	String	The contact status (A = Active, I = Inactive, S = Without movement)
`numeroDocumento`	String	The contact document number (CPF/CNPJ)
`telefone`	String	The contact phone number
`celular`	String	The contact mobile number
`dataFiltroAlteracao`	DateTime	The filter date used for incremental sync (YYYY-MM-DD HH:mm:ss format)

Contact Details

Stream for detailed contact information (child of Contacts).

Field	Type	Description
`id`	Integer	The contact ID
`pessoasContato`	Array	Contact persons associated with this contact
`data`	String	The contact creation/update date
`dataFiltroAlteracao`	DateTime	The filter date (YYYY-MM-DD HH:mm:ss format)
(Additional fields)	Various	Inherits comprehensive structure (address, financial details, documentation) from Bling’s detailed contact API

Invoices & Fiscal Documents

NFe (Notas Fiscais Eletrônicas)

Stream for managing electronic invoices (NFe) for products.

Field	Type	Description
`id`	Integer	The NFe ID
`tipo`	Integer	The NFe type
`situacao`	Integer	The NFe status
`numero`	String	The NFe number
`dataEmissao`	DateTime	The emission date (YYYY-MM-DD HH:MM:SS format)
`dataOperacao`	String	The operation date (YYYY-MM-DD HH:MM:SS format)
`chaveAcesso`	String	The access key
`contato.id`	Integer	The contact ID
`contato.nome`	String	The contact name
`contato.numeroDocumento`	String	The document number
`contato.ie`	String	State registration
`contato.rg`	String	RG number
`contato.telefone`	String	Phone number
`contato.email`	String	Email address
`contato.endereco.endereco`	String	Street address
`contato.endereco.numero`	String	Address number
`contato.endereco.complemento`	String	Address complement
`contato.endereco.bairro`	String	Neighborhood
`contato.endereco.cep`	String	ZIP code
`contato.endereco.municipio`	String	City
`contato.endereco.uf`	String	State
`contato.endereco.pais`	String	Country
`naturezaOperacao.id`	Integer	The nature of operation ID
`loja.id`	Integer	The store ID

NFe Details

Stream for detailed NFe information (child of NFe stream).

Field	Type	Description
`id`	Integer	The NFe ID
`tipo`	Integer	The NFe type
`situacao`	Integer	The NFe status
`numero`	String	The NFe number
`dataEmissao`	String	The emission date
`dataOperacao`	String	The operation date
`chaveAcesso`	String	The access key
`serie`	Integer	The NFe series
`valorNota`	Number	The invoice value
`valorFrete`	Number	The freight value
`xml`	String	The XML content
`linkDanfe`	String	The DANFE link
`linkPDF`	String	The PDF link
`optanteSimplesNacional`	Boolean	Simple National taxpayer flag
`numeroPedidoLoja`	String	Store order number
`contato.id`	Integer	The contact ID
`contato.nome`	String	The contact name
`contato.numeroDocumento`	String	The document number
`contato.ie`	String	State registration
`contato.rg`	String	RG number
`contato.telefone`	String	Phone number
`contato.email`	String	Email address
`contato.endereco.endereco`	String	Street address
`contato.endereco.numero`	String	Address number
`contato.endereco.complemento`	String	Address complement
`contato.endereco.bairro`	String	Neighborhood
`contato.endereco.cep`	String	ZIP code
`contato.endereco.municipio`	String	City
`contato.endereco.uf`	String	State
`contato.endereco.pais`	String	Country
`naturezaOperacao.id`	Integer	The nature of operation ID
`loja.id`	Integer	The store ID
`transporte.fretePorConta`	Integer	Freight responsibility
`transporte.transportador.nome`	String	Transporter name
`transporte.transportador.numeroDocumento`	String	Transporter document number
`transporte.volumes[].id`	Integer	Volume ID
`transporte.etiqueta.nome`	String	Label name
`transporte.etiqueta.endereco`	String	Label street address
`transporte.etiqueta.numero`	String	Label address number
`transporte.etiqueta.complemento`	String	Label address complement
`transporte.etiqueta.municipio`	String	Label city
`transporte.etiqueta.uf`	String	Label state
`transporte.etiqueta.cep`	String	Label ZIP code
`transporte.etiqueta.bairro`	String	Label neighborhood
`vendedor.id`	Integer	The seller ID
`itens[].codigo`	String	Item code
`itens[].descricao`	String	Item description
`itens[].unidade`	String	Item unit
`itens[].quantidade`	Number	Item quantity
`itens[].valor`	Number	Item value
`itens[].valorTotal`	Number	Item total value
`itens[].tipo`	String	Item type
`itens[].pesoBruto`	Number	Item gross weight
`itens[].pesoLiquido`	Number	Item net weight
`itens[].numeroPedidoCompra`	String	Purchase order number
`itens[].classificacaoFiscal`	String	Fiscal classification
`itens[].cest`	String	CEST code
`itens[].codigoServico`	String	Service code
`itens[].origem`	Integer	Origin
`itens[].informacoesAdicionais`	String	Additional information
`itens[].gtin`	String	GTIN code
`itens[].cfop`	String	CFOP code
`itens[].documentoReferenciado.chaveAcesso`	String	Referenced document access key
`itens[].documentoReferenciado.numero`	String	Referenced document number
`itens[].documentoReferenciado.serie`	String	Referenced document series
`itens[].documentoReferenciado.numeroItem`	String	Referenced item number
`itens[].impostos.valorAproximadoTotalTributos`	Number	Approximate total tax value
`itens[].impostos.icms.st`	Number	ICMS ST
`itens[].impostos.icms.origem`	Integer	ICMS origin
`itens[].impostos.icms.modalidade`	Integer	ICMS modality
`itens[].impostos.icms.aliquota`	Number	ICMS rate
`itens[].impostos.icms.valor`	Number	ICMS value
`parcelas[].data`	String	Installment date
`parcelas[].valor`	Number	Installment value
`parcelas[].observacoes`	String	Installment observations
`parcelas[].caut`	String	CAUT code
`parcelas[].formaPagamento.id`	Integer	Payment method ID

NFe Document

Stream for retrieving the XML document content of an NFe (child of NFe stream). Supports incremental sync.

Field	Type	Description
`nome`	String	The name of the NFe document
`conteudo`	String	The content of the NFe document
`dataEmissaoNfe`	DateTime	The emission date of the NFe

NFSe (Notas Fiscais de Serviço Eletrônicas)

Stream for managing electronic service invoices (NFSe). Unlike NFe which is for products, NFSe is specifically for service-based transactions.

Field	Type	Description
`id`	Integer	Unique identifier for the NFSe
`numero`	String	The NFSe number
`numeroRPS`	String	The RPS (Recibo Provisório de Serviços) number
`serie`	String	The NFSe series
`situacao`	Integer	The NFSe status
`dataEmissao`	String	The emission date (YYYY-MM-DD format)
`valor`	Number	The service value
`contato.id`	Integer	The contact ID
`contato.nome`	String	The contact name
`contato.numeroDocumento`	String	The document number
`contato.email`	String	Email address

NFe Situation

Static stream providing a mapping of NFe situation IDs to their descriptions.

Field	Type	Description
`id`	Integer	The NFe situation ID
`situacao`	String	The NFe situation status description (e.g., “Pendente”, “Autorizada”, “Cancelada”)

NFSe Situation

Static stream providing a mapping of NFSe situation IDs to their descriptions.

Field	Type	Description
`id`	Integer	The NFSe situation ID
`situacao`	String	The NFSe situation status description (e.g., “Pendente”, “Emitida”, “Cancelada”)

Operation Types

Stream for managing different types of business operations (nature of operations for invoices).

Field	Type	Description
`id`	Integer	The operation type ID
`descricao`	String	The operation type description
`situacao`	Integer	The operation type status (1 = Active, 0 = Inactive)
`padrao`	Boolean	Indicates if this is the default operation type

Sales & Orders

Sales Orders

Stream for managing sales orders. Supports incremental sync using modification date filter.

Field	Type	Description
`id`	Integer	The sales order ID
`numero`	Integer	The sales order number
`numeroLoja`	String	The store order number
`data`	Date	The order date (YYYY-MM-DD format)
`dataSaida`	Date	The departure date (YYYY-MM-DD format)
`dataPrevista`	Date	The expected delivery date (YYYY-MM-DD format)
`totalProdutos`	Number	The total products value
`total`	Number	The total order value
`contato.id`	Integer	The contact ID
`contato.nome`	String	The contact name
`contato.tipoPessoa`	String	Person type (F = Individual, J = Legal Entity)
`contato.numeroDocumento`	String	The document number
`situacao.id`	Integer	The status ID
`situacao.valor`	Integer	The status value
`loja.id`	Integer	The store ID
`dataFiltroAlteracao`	DateTime	The filter date used for incremental sync (replication key)

Sales Order Details

Stream for detailed sales order information (child of Sales Orders).

Field	Type	Description
`id`	Integer	The sales order ID
`numero`	Integer	The sales order number
`numeroLoja`	String	The store order number
`data`	Date	The order date (YYYY-MM-DD format)
`dataSaida`	Date	The departure date (YYYY-MM-DD format)
`dataPrevista`	Date	The expected delivery date (YYYY-MM-DD format)
`totalProdutos`	Number	The total products value
`total`	Number	The total order value
`numeroPedidoCompra`	String	Purchase order number
`outrasDespesas`	Number	Other expenses
`observacoes`	String	Order observations
`observacoesInternas`	String	Internal observations
`contato.id`	Integer	The contact ID
`contato.nome`	String	The contact name
`contato.tipoPessoa`	String	Person type (F = Individual, J = Legal Entity)
`contato.numeroDocumento`	String	The document number
`situacao.id`	Integer	The status ID
`situacao.valor`	Integer	The status value
`loja.id`	Integer	The store ID
`desconto.valor`	Number	Discount value
`desconto.unidade`	String	Discount unit (REAL, PERCENTUAL)
`categoria.id`	Integer	The category ID
`notaFiscal.id`	Integer	The invoice ID
`tributacao.totalICMS`	Number	Total ICMS tax
`tributacao.totalIPI`	Number	Total IPI tax
`itens[].id`	Integer	Item ID
`itens[].codigo`	String	Item code
`itens[].unidade`	String	Item unit
`itens[].quantidade`	Number	Item quantity
`itens[].desconto`	Number	Item discount
`itens[].valor`	Number	Item value
`itens[].aliquotaIPI`	Number	IPI rate
`itens[].descricao`	String	Item description
`itens[].descricaoDetalhada`	String	Detailed description
`itens[].produto.id`	Integer	Product ID
`itens[].comissao.base`	Number	Commission base
`itens[].comissao.aliquota`	Number	Commission rate
`itens[].comissao.valor`	Number	Commission value
`itens[].naturezaOperacao.id`	Integer	Natureza Operação ID
`parcelas[].id`	Integer	Installment ID
`parcelas[].dataVencimento`	Date	Due date
`parcelas[].valor`	Number	Installment value
`parcelas[].observacoes`	String	Installment observations
`parcelas[].caut`	String	CAUT code
`parcelas[].formaPagamento.id`	Integer	Payment method ID
`transporte.fretePorConta`	Integer	Freight responsibility
`transporte.frete`	Number	Freight value
`transporte.quantidadeVolumes`	Integer	Number of volumes
`transporte.pesoBruto`	Number	Gross weight
`transporte.prazoEntrega`	Integer	Delivery term
`transporte.contato.id`	Integer	Transporter contact ID
`transporte.contato.nome`	String	Transporter name
`transporte.etiqueta.nome`	String	Label name
`transporte.etiqueta.endereco`	String	Label address
`transporte.etiqueta.numero`	String	Label address number
`transporte.etiqueta.complemento`	String	Label address complement
`transporte.etiqueta.municipio`	String	Label city
`transporte.etiqueta.uf`	String	Label state
`transporte.etiqueta.cep`	String	Label ZIP code
`transporte.etiqueta.bairro`	String	Label neighborhood
`transporte.etiqueta.nomePais`	String	Label country name
`transporte.volumes[].id`	Integer	Volume ID
`transporte.volumes[].servico`	String	Service
`transporte.volumes[].codigoRastreamento`	String	Tracking code
`vendedor.id`	Integer	The seller ID
`intermediador.cnpj`	String	Intermediator CNPJ
`intermediador.nomeUsuario`	String	Username
`taxas.taxaComissao`	Number	Commission rate
`taxas.custoFrete`	Number	Freight cost
`taxas.valorBase`	Number	Base value

Products & Inventory

Products

Stream for managing product catalog. Supports incremental sync using modification date filter.

Field	Type	Description
`id`	Integer	The product ID
`idProdutoPai`	Integer	The parent product ID (for variations)
`nome`	String	The product name
`codigo`	String	The product code/SKU
`preco`	Number	The product price
`precoCusto`	Number	The product cost price
`estoque.saldoVirtualTotal`	Number	Total virtual stock balance
`tipo`	String	The product type (P = Product, S = Service)
`situacao`	String	The product status (A = Active, I = Inactive)
`formato`	String	The product format (S = Simple, V = Variable)
`descricaoCurta`	String	Short product description
`imagemURL`	String	Product image URL
`dataFiltroAlteracao`	Date	The filter date used for incremental sync (replication key)

Product Details

Stream for detailed product information (child of Products).

Field	Type	Description
`id`	Integer	The product ID
`nome`	String	The product name
`codigo`	String	The product code
`preco`	Number	The product price
`tipo`	String	The product type (P = Product, S = Service)
`situacao`	String	The product status (A = Active, I = Inactive)
`formato`	String	The product format (S = Simple, V = Variable)
`descricaoCurta`	String	Short product description
`imagemURL`	String	Product image URL
`dataValidade`	String	Product validity date
`unidade`	String	Product unit
`pesoLiquido`	Number	Net weight
`pesoBruto`	Number	Gross weight
`volumes`	Number	Number of volumes
`itensPorCaixa`	Number	Items per box
`gtin`	String	GTIN code
`gtinEmbalagem`	String	Package GTIN code
`tipoProducao`	String	Production type
`condicao`	Integer	Product condition
`freteGratis`	Boolean	Free shipping flag
`marca`	String	Product brand
`descricaoComplementar`	String	Complementary description
`linkExterno`	String	External link
`observacoes`	String	Product observations
`descricaoEmbalagemDiscreta`	String	Discrete packaging description
`actionEstoque`	String	Stock action
`categoria.id`	Integer	The category ID
`estoque.minimo`	Number	Minimum stock
`estoque.maximo`	Number	Maximum stock
`estoque.crossdocking`	Number	Crossdocking quantity
`estoque.localizacao`	String	Stock location
`estoque.saldoVirtualTotal`	Number	Total virtual stock balance
`fornecedor.id`	Integer	The supplier ID
`fornecedor.contato.id`	Integer	Supplier contact ID
`fornecedor.contato.nome`	String	Supplier contact name
`fornecedor.codigo`	String	Supplier code
`fornecedor.precoCusto`	Number	Cost price
`fornecedor.precoCompra`	Number	Purchase price
`dimensoes.largura`	Number	Width
`dimensoes.altura`	Number	Height
`dimensoes.profundidade`	Number	Depth
`dimensoes.unidadeMedida`	Integer	Measurement unit
`tributacao.origem`	Integer	Origin
`tributacao.nFCI`	String	NFCI code
`tributacao.ncm`	String	NCM code
`tributacao.cest`	String	CEST code
`tributacao.codigoListaServicos`	String	Service list code
`tributacao.spedTipoItem`	String	SPED item type
`tributacao.codigoItem`	String	Item code
`tributacao.percentualTributos`	Number	Tax percentage
`tributacao.valorBaseStRetencao`	Number	ST retention base value
`tributacao.valorStRetencao`	Number	ST retention value
`tributacao.valorICMSSubstituto`	Number	ICMS substitute value
`tributacao.codigoExcecaoTipi`	String	TIPI exception code
`tributacao.classeEnquadramentoIpi`	String	IPI classification class
`tributacao.valorIpiFixo`	Number	Fixed IPI value
`tributacao.codigoSeloIpi`	String	IPI seal code
`tributacao.valorPisFixo`	Number	Fixed PIS value
`tributacao.valorCofinsFixo`	Number	Fixed COFINS value
`tributacao.codigoANP`	String	ANP code
`tributacao.descricaoANP`	String	ANP description
`tributacao.percentualGLP`	Number	GLP percentage
`tributacao.percentualGasNacional`	Number	National gas percentage
`tributacao.percentualGasImportado`	Number	Imported gas percentage
`tributacao.valorPartida`	Number	Starting value
`tributacao.tipoArmamento`	Integer	Armament type
`tributacao.descricaoCompletaArmamento`	String	Complete armament description
`tributacao.dadosAdicionais`	String	Additional data
`tributacao.grupoProduto.id`	Integer	The product group ID
`midia.video.url`	String	Video URL
`midia.imagens.imagensURL`	Array	Images URL
`midia.imagens.externas[].link`	String	External image link
`midia.imagens.internas[].link`	String	Internal image link
`midia.imagens.internas[].linkMiniatura`	String	Thumbnail link
`midia.imagens.internas[].validade`	String	Image validity
`midia.imagens.internas[].ordem`	Integer	Image order
`midia.imagens.internas[].anexo.id`	Integer	Attachment ID
`midia.imagens.internas[].anexoVinculo.id`	Integer	Attachment link ID
`linhaProduto.id`	Integer	The product line ID
`estrutura.tipoEstoque`	String	Stock type
`estrutura.lancamentoEstoque`	String	Stock release type
`estrutura.componentes[].produto.id`	Integer	Component product ID
`estrutura.componentes[].quantidade`	Number	Component quantity
`camposCustomizados[].idCampoCustomizado`	Integer	Custom field ID
`camposCustomizados[].idVinculo`	String	Link ID for updating
`camposCustomizados[].valor`	String	Custom field value
`camposCustomizados[].item`	String	Custom field item
`variacoes[]`	Array	Product variations (contains same fields as parent product)
`product_id`	Integer	Parent product ID from parent stream

Product Categories

Stream for managing product categories.

Field	Type	Description
`id`	Integer	The category ID
`descricao`	String	The category description
`categoriaPai.id`	Integer	Parent category ID

Product Stores

Stream for managing product-store links (produtos lojas).

Field	Type	Description
`id`	Integer	The product-store link ID
`codigo`	String	The product code in this store
`preco`	Number	The product price in this store
`precoPromocional`	Number	The promotional price in this store
`produto.id`	Integer	The product ID
`loja.id`	Integer	The store ID
`fornecedorLoja.id`	Integer	The store supplier ID
`marcaLoja.id`	Integer	The store brand ID
`categoriasProdutos[].id`	Integer	The product category ID

Product Store Details

Stream for detailed product-store link information (child of Product Stores).

Field	Type	Description
`id`	Integer	The product-store link ID
`codigo`	String	The product code in this store
`preco`	Number	The product price in this store
`precoPromocional`	Number	The promotional price in this store
`produto.id`	Integer	The product ID
`loja.id`	Integer	The store ID
`fornecedorLoja.id`	Integer	The store supplier ID
`marcaLoja.id`	Integer	The store brand ID
`categoriasProdutos[].id`	Integer	The product category ID

Stock Balances

Stream for retrieving current stock balances by product and deposit. This stream provides real-time inventory information across different warehouses and locations.

Field	Type	Description
`idProduto`	Integer	The product ID
`produto.id`	Integer	The product ID (nested object)
`produto.nome`	String	The product name
`produto.codigo`	String	The product code/SKU
`saldos[].deposito.id`	Integer	The deposit/warehouse ID
`saldos[].deposito.nome`	String	The deposit/warehouse name
`saldos[].saldoFisico`	Number	Physical stock balance
`saldos[].saldoVirtual`	Number	Virtual stock balance (physical - reserved)
`dataFiltroAlteracao`	Date	The filter date inherited from the parent product stream

Financial

Accounts Receivable

Stream for managing accounts receivable (amounts to be received).

Field	Type	Description
`id`	Integer	The account receivable ID
`situacao`	Integer	The account receivable status
`vencimento`	Date	The due date (YYYY-MM-DD format)
`valor`	Number	The amount to be received
`idTransacao`	String	The transaction ID
`linkQRCodePix`	String	The PIX QR code link
`linkBoleto`	String	The boleto (payment slip) link
`dataEmissao`	Date	The emission date (YYYY-MM-DD format)
`contato.id`	Integer	The contact ID
`contato.nome`	String	The contact name
`contato.numeroDocumento`	String	The contact document number
`contato.tipo`	String	The contact type (F = Person, J = Company)
`formaPagamento.id`	Integer	The payment method ID
`formaPagamento.codigoFiscal`	Integer	The fiscal code
`contaContabil.id`	Integer	The accounting account ID
`contaContabil.descricao`	String	The accounting account description
`origem.id`	Integer	The origin ID
`origem.tipoOrigem`	String	The origin type (e.g., ‘venda’)
`origem.numero`	String	The origin number
`origem.dataEmissao`	Date	The origin emission date
`origem.valor`	Number	The origin value
`origem.situacao`	Integer	The origin status
`origem.url`	String	The origin URL

Accounts Receivable Details

Stream for detailed accounts receivable information (child of Accounts Receivable).

Field	Type	Description
`id`	Integer	The account receivable ID
`situacao`	Integer	The account receivable status
`vencimento`	Date	The due date (YYYY-MM-DD format)
`valor`	Number	The amount to be received
`idTransacao`	String	The transaction ID
`linkQRCodePix`	String	The PIX QR code link
`linkBoleto`	String	The boleto link
`dataEmissao`	Date	The emission date (YYYY-MM-DD format)
`contato.id`	Integer	The contact ID
`contato.nome`	String	The contact name
`contato.numeroDocumento`	String	The contact document number
`contato.tipo`	String	The contact type (F = Person, J = Company)
`formaPagamento.id`	Integer	The payment method ID
`formaPagamento.codigoFiscal`	Integer	The fiscal code
`contaContabil.id`	Integer	The accounting account ID
`contaContabil.descricao`	String	The accounting account description
`origem.id`	Integer	The origin ID
`origem.tipoOrigem`	String	The origin type
`origem.numero`	String	The origin number
`origem.dataEmissao`	String	The origin emission date
`origem.valor`	Number	The origin value
`origem.situacao`	Integer	The origin status
`origem.url`	String	The origin URL
`saldo`	Number	The balance for the account receivable
`vencimentoOriginal`	String	The original due date (YYYY-MM-DD format)
`numeroDocumento`	String	The document number
`competencia`	String	The competence date (YYYY-MM-DD format)
`historico`	String	The history of the receivable
`numeroBanco`	String	The bank number
`portador.id`	Integer	The portador ID
`categoria.id`	Integer	The category ID
`vendedor.id`	Integer	The salesperson ID
`borderos`	Array	List of borderos IDs
`ocorrencia.tipo`	Integer	The occurrence type

Borderos

Stream for managing borderos (settlement batches with the actual receipt/payment date). This is a child stream of Accounts Receivable Details.

Field	Type	Description
`id`	Integer	The bordero ID
`data`	Date	The settlement date (YYYY-MM-DD format)
`historico`	String	The bordero description
`portador.id`	Integer	The portador ID
`categoria.id`	Integer	The category ID
`pagamentos[].contato.id`	Integer	The contact ID
`pagamentos[].numeroDocumento`	String	The document number
`pagamentos[].valorPago`	Number	The paid amount
`pagamentos[].juros`	Number	Interest amount
`pagamentos[].desconto`	Number	Discount amount
`pagamentos[].acrescimo`	Number	Surcharge amount
`pagamentos[].tarifa`	Number	Payment method fee

Boleto

Stream for managing payment slips (boletos) associated with accounts receivable.

Field	Type	Description
`origemId`	Integer	The origin ID (links to sale/invoice)
`dataEmissaoNfe`	String	The NFe emission date
`venda.numero`	String	Sale number
`notaFiscal.numero`	String	Invoice number
`valorTotal`	Number	Total value
`contas[].id`	Integer	Account ID
`contas[].numeroExterno`	String	External number
`contas[].vencimento`	String	Due date
`contas[].valor`	Number	Value
`contas[].situacao`	Integer	Status

Accounts Payable

Stream for managing accounts payable (amounts to be paid).

Field	Type	Description
`id`	Integer	The account payable ID
`situacao`	Integer	The account payable status
`vencimento`	Date	The due date (YYYY-MM-DD format)
`valor`	Number	The amount to be paid
`dataEmissao`	String	The emission date (YYYY-MM-DD format)
`contato.id`	Integer	The contact ID
`contato.nome`	String	The contact name
`contato.numeroDocumento`	String	The contact document number
`contato.tipo`	String	The contact type (F = Person, J = Company)
`formaPagamento.id`	Integer	The payment method ID
`formaPagamento.codigoFiscal`	Integer	The fiscal code
`dataFiltro`	Date	The filter date (YYYY-MM-DD format)

Accounts Payable Details

Stream for detailed accounts payable information (child of Accounts Payable).

Field	Type	Description
`id`	Integer	The account payable ID
`situacao`	Integer	The account payable status
`vencimento`	Date	The due date (YYYY-MM-DD format)
`valor`	Number	The amount to be paid
`dataEmissao`	Date	The emission date (YYYY-MM-DD format)
`contato.id`	Integer	The contact ID
`contato.nome`	String	The contact name
`contato.numeroDocumento`	String	The contact document number
`contato.tipo`	String	The contact type
`formaPagamento.id`	Integer	The payment method ID
`formaPagamento.codigoFiscal`	Integer	The fiscal code
`contaContabil.id`	Integer	The accounting account ID
`contaContabil.descricao`	String	The accounting account description
`saldo`	Number	The balance
`vencimentoOriginal`	Date	The original due date
`numeroDocumento`	String	The document number
`competencia`	Date	The competence date
`historico`	String	The history
`numeroBanco`	String	The bank number
`portador.id`	Integer	The portador ID
`categoria.id`	Integer	The category ID
`ocorrencia.tipo`	Integer	The occurrence type

Cash Registers

Stream for managing cash register entries. Supports incremental sync using date filter.

Field	Type	Description
`id`	String	The cash register entry ID
`data`	String	The date of the cash register entry (used as replication key)
(Additional fields)	Various	Inherits structure from Bling’s cash registers API

Accounting Accounts

Stream for managing accounting accounts (bank accounts, payment integrations).

Field	Type	Description
`id`	Integer	The accounting account ID
`descricao`	String	The account description
`tipo`	String	The account type (e.g., ‘integracao-pagamento’)
`aliasIntegracao`	String	The integration alias (e.g., ‘BlingPagamentos’)
`saldoInicial`	Number	The initial balance
`dataInicioTransacoes`	String	The start date for transactions (YYYY-MM-DD format)

Revenue Expense Categories

Stream for managing revenue and expense categories.

Field	Type	Description
`id`	Integer	The category ID
`idCategoriaPai`	Integer	The parent category ID (0 if no parent)
`descricao`	String	The category description
`tipo`	Integer	The category type (1 = Revenue, 2 = Expense)

Revenue Expense Category Details

Stream for detailed revenue/expense category information (child of Revenue Expense Categories).

Field	Type	Description
`id`	Integer	The category ID
`idCategoriaPai`	Integer	The parent category ID
`descricao`	String	The category description
`tipo`	Integer	The category type (1 = Revenue, 2 = Expense)
`situacao`	Integer	The category status

Configuration

Store Categories

Stream for managing store categories (for e-commerce integrations).

Field	Type	Description
`id`	Integer	The store category ID
`descricao`	String	The category description
`codigo`	String	The category code
`loja.id`	Integer	Store ID
`categoriaProduto.id`	Integer	Product category mapping ID

Store Category Details

Stream for detailed store category information (child of Store Categories).

Field	Type	Description
`id`	Integer	The store category ID
`descricao`	String	The category description
`codigo`	String	The category code
`loja.id`	Integer	Store ID
`categoriaProduto.id`	Integer	Product category mapping ID

Situation Modules

Stream for retrieving situation modules (situações módulos).

Field	Type	Description
`id`	Integer	The module ID
`nome`	String	The module name
`descricao`	String	The module description
`criarSituacoes`	Boolean	Whether the module allows creating situations

Situations

Stream for retrieving situations per module (situações por módulo). Child stream of Situation Modules.

Field	Type	Description
`id`	Integer	The situation ID
`nome`	String	The situation name
`idHerdado`	Integer	The inherited situation ID
`cor`	String	The situation color

Data Model

The following diagram illustrates the relationships between the core data streams in Bling. The arrows indicate the join keys that link the different entities.

Implementation Notes

API Rate Limits

Rate Limit: ~3 requests per second (enforced as 1 request per 0.35 seconds)
Daily Quota: 120,000 requests per day. The connector gracefully handles daily limit exceptions by saving its state and resuming in subsequent runs.
Historical Data Limit: Bling API only allows fetching data from 2025-01-01 onwards

Pagination Behavior

Variable Page Sizes: The Bling API occasionally returns pages with fewer records than requested (e.g., 85 or 50 records instead of 100) even when more data is available. The connector correctly handles this by continuing to paginate until an empty page is received, preventing silent data truncation.
Pagination Safety Cap: To protect against API misbehavior, a hard limit of 1,000 pages per 1-year time window (up to 100,000 records) is enforced. If this limit is hit, the connector logs a warning and gracefully advances to the next time window.

Data Quality

Portuguese Field Names: Field names use Portuguese terminology (e.g., contato for contact, situacao for status, vencimento for due date)
Date Formats: Dates are typically in YYYY-MM-DD format, datetimes in YYYY-MM-DD HH:MM:SS format
Status Values: Many entities use numeric status values - refer to the Situation streams for human-readable descriptions

Incremental Sync Support

The following streams support incremental sync:

Invoice streams (NFe, NFe Details, NFe Document, NFSe): Use dataEmissao or dataEmissaoNfe as replication key
Product streams (Products, Product Details): Use dataFiltroAlteracao (modification filter date) as replication key
Sales streams (Sales Orders, Sales Order Details): Use dataFiltroAlteracao as replication key
Contact streams (Contacts, Contact Details): Use dataFiltroAlteracao as replication key
Financial streams (Accounts Receivable, Accounts Payable, Boleto, Cash Registers): Use dataEmissao, dataFiltro, or data as replication key
Stock Balances: Inherits dataFiltroAlteracao from parent products for incremental sync

Child Streams & Performance

Parent-Child Architecture: Detail streams (e.g., Product Details, Product Store Details, Sales Order Details, Purchase Order Details, Contract Details, NFe Details, NFe Document, NFCe Details, Contact Details, Situations) make one additional API request per parent record using single-resource fetching
Performance Impact: With 3 requests/second rate limit, fetching 10,000 detailed records takes approximately 55 minutes
Batch Processing: Stock Balances uses batch requests to optimize API usage by fetching multiple products at once
Optimization: If you don’t need detailed data, sync only parent streams to significantly reduce API calls and sync time
Lookback Window: Use the lookback window configuration to re-fetch recently modified records and ensure data consistency

Brazilian Context

NFe/NFCe/NFSe: Brazilian electronic invoice types
- NFe: Product invoices
- NFCe: Consumer invoices (retail)
- NFSe: Service invoices
Document Numbers: numeroDocumento typically refers to CPF (individuals) or CNPJ (companies)
ICMS/IPI: Brazilian tax codes included in invoice details

Skills for agents

Download Bling skills file

Bling connector documentation as plain markdown, for use in AI agent contexts.

Documentation

Get started

Using Nekt

Workspace

Resources

Bling as a data source

Configuring Bling as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

API Limitations & Performance

Understanding Sync Times

Stream to Endpoint Mapping

Streams and Fields

Invoices & Fiscal Documents

Contacts & CRM

Invoices & Fiscal Documents

Sales & Orders

Products & Inventory

Financial

Configuration

Data Model

Implementation Notes

API Rate Limits

Data Quality

Incremental Sync Support

Child Streams & Performance

Brazilian Context

Skills for agents

Download Bling skills file

​Configuring Bling as a Source

​1. Add account access

​2. Select streams

​3. Configure data streams

​4. Configure data source

​5. Check your new source

​API Limitations & Performance

​Understanding Sync Times

​Stream to Endpoint Mapping

​Streams and Fields

​Invoices & Fiscal Documents

​Contacts & CRM

​Invoices & Fiscal Documents

​Sales & Orders

​Products & Inventory

​Financial

​Configuration

​Data Model

​Implementation Notes

​API Rate Limits

​Pagination Behavior

​Data Quality

​Incremental Sync Support

​Child Streams & Performance

​Brazilian Context

​Skills for agents

Download Bling skills file

Configuring Bling as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

API Limitations & Performance

Understanding Sync Times

Stream to Endpoint Mapping

Streams and Fields

Invoices & Fiscal Documents

Contacts & CRM

Invoices & Fiscal Documents

Sales & Orders

Products & Inventory

Financial

Configuration

Data Model

Implementation Notes

API Rate Limits

Pagination Behavior

Data Quality

Incremental Sync Support

Child Streams & Performance

Brazilian Context

Skills for agents