> ## Documentation Index > Fetch the complete documentation index at: https://docs.nekt.com/llms.txt > Use this file to discover all available pages before exploring further. # Bling as a data source > Bring data from Bling to Nekt. 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](https://app.nekt.ai/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](https://docs.nekt.com/runs/scheduling-and-triggers), 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](https://docs.nekt.com/get-started/core-concepts/resource-control). * Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#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](https://app.nekt.ai/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](https://app.nekt.ai/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:** 1. Start with a minimal set of streams and add more as needed 2. Use incremental sync when available to reduce the number of records fetched 3. Schedule full syncs during off-peak hours if you have large datasets 4. 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 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) | 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 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 | 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 | 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 | 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 | 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") | 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") | 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 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) | 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 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) | 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 | Stream for managing product categories. | Field | Type | Description | | ----------------- | ------- | ------------------------ | | `id` | Integer | The category ID | | `descricao` | String | The category description | | `categoriaPai.id` | Integer | Parent category ID | 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 | 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 | 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 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 | 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 | 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 | 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 | 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) | 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 | 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* | 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) | 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) | 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 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 | 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 | 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 | 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. ```mermaid theme={null} graph TD; subgraph "Sales & Orders" SalesOrders("Sales Orders"); SalesOrderDetails("Sales Order Details"); PurchaseOrders("Purchase Orders"); PurchaseOrderDetails("Purchase Order Details"); Contracts("Contracts"); ContractDetails("Contract Details"); end subgraph "Contacts & CRM" Contacts("Contacts"); ContactDetails("Contact Details"); end subgraph "Invoices & Fiscal" NFe("NFe"); NFeDetails("NFe Details"); NFeDocument("NFe Document"); NFSe("NFSe"); NFCe("NFCe"); NFCeDetails("NFCe Details"); NFeSituation("NFe Situation"); NFSeSituation("NFSe Situation"); OperationTypes("Operation Types"); end subgraph "Products & Inventory" Products("Products"); ProductDetails("Product Details"); ProductCategories("Product Categories"); StockBalances("Stock Balances"); ProductStores("Product Stores"); ProductStoreDetails("Product Store Details"); end subgraph "Financial" AccountsReceivable("Accounts Receivable"); AccountsReceivableDetails("Accounts Receivable Details"); AccountsPayable("Accounts Payable"); AccountsPayableDetails("Accounts Payable Details"); Boleto("Boleto"); CashRegisters("Cash Registers"); AccountingAccounts("Accounting Accounts"); RevenueExpenseCategories("Revenue/Expense Categories"); RevenueExpenseCategoryDetails("Revenue/Expense Category Details"); end subgraph "Configuration" StoreCategories("Store Categories"); StoreCategoryDetails("Store Category Details"); SituationModules("Situation Modules"); Situations("Situations"); end %% CRM relationships Contacts -- "id" --> ContactDetails; %% Products relationships Products -- "id" --> ProductDetails; Products -- "id" --> StockBalances; Products -- "categoria.id" --> ProductCategories; ProductStores -- "id" --> ProductStoreDetails; ProductStores -- "produto.id" --> Products; %% Sales relationships SalesOrders -- "id" --> SalesOrderDetails; SalesOrders -- "contato.id" --> Contacts; SalesOrderDetails -- "notaFiscal.id" --> NFe; PurchaseOrders -- "id" --> PurchaseOrderDetails; Contracts -- "id" --> ContractDetails; %% Invoice relationships NFe -- "id" --> NFeDetails; NFe -- "chaveAcesso" --> NFeDocument; NFe -- "situacao" --> NFeSituation; NFSe -- "situacao" --> NFSeSituation; NFCe -- "id" --> NFCeDetails; NFeDetails -- "naturezaOperacao.id" --> OperationTypes; NFeDetails -- "itens.codigo" --> Products; %% Financial relationships AccountsReceivable -- "id" --> AccountsReceivableDetails; AccountsReceivable -- "id" --> Boleto; AccountsReceivable -- "contaContabil.id" --> AccountingAccounts; AccountsReceivableDetails -- "borderos" --> Borderos; AccountsPayable -- "id" --> AccountsPayableDetails; RevenueExpenseCategories -- "id" --> RevenueExpenseCategoryDetails; %% Configuration relationships StoreCategories -- "id" --> StoreCategoryDetails; StoreCategories -- "categoriaProduto.id" --> ProductCategories; SituationModules -- "id" --> Situations; ``` ## 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 Bling connector documentation as plain markdown, for use in AI agent contexts.