> ## 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. # BSoft TMS as a data source > Bring data from BSoft TMS to Nekt. BSoft TMS is a Transport Management System that provides financial and operational data for logistics and fleet operations. The connector extracts data from the BSoft TMS API (financeiro module), including companies, receivables, payables, payments, receipts, transfers, cost centers, chart of accounts, and related master data. ## Configuring BSoft TMS 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 BSoft TMS option from the list of connectors. Click **Next** and you'll be prompted to add your access. ### 1. Add account access You'll need to provide credentials for the BSoft TMS API. The integration uses HTTP Basic Authentication with a user that has the integration profile in BSoft TMS. The following configurations are available: * **Domain**: Your BSoft TMS domain name (e.g. `yourdomain.bsoft.app`). The connector will request data from `https://{domain}/services/index.php`. * **Username**: Username with integration profile in BSoft TMS. * **Password**: Password for the BSoft TMS integration user. Once you're done, click **Next**. ### 2. Select streams Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones. > 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 — used for streams that have a replication key (e.g. titulos\_receber, titulos\_pagar, pagamentos, recebimentos, transferencias). * Full table: every time the extraction happens, we'll get the current state of the data — used for master/reference streams (empresas, centros de custo, formas de pagamento, etc.). 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. # Streams and Fields Below you'll find all available data streams from BSoft TMS and their corresponding fields: Stream containing companies (empresas) registered in BSoft TMS. **Key Fields:** * `id` - Company identifier (primary key) * `descricao` - Company name * `cnpj` - Brazilian company tax registration number (CNPJ) Stream for cost centers (centros de custo) used for allocation and reporting. **Key Fields:** * `cod_cc` - Cost center identifier code (primary key) * `cod_estendido` - Extended hierarchical code of the cost center * `descricao` - Cost center name or description * `status` - Status of the cost center (e.g. Aberto, Fechado) Stream for payment conditions (e.g. 15 dias, 30 dias). **Key Fields:** * `id` - Payment condition identifier (primary key) * `descricao` - Payment condition description * `ativo` - Indicates whether the payment condition is active Stream for financial accounts (bank accounts and similar). **Key Fields:** * `id` - Financial account identifier (primary key) * `descricao` - Financial account description (including bank name and number) * `codBanco` - Bank code Stream for product and service families used to group services/products. **Key Fields:** * `id` - Product/service family identifier (primary key) * `descricao` - Product/service family description * `cod_estendido` - Extended hierarchical code of the family * `nome_interno` - Internal name used for system identification * `familiaServicos` - Indicates if this family is a service family (S/N) * `familiaProdutos` - Indicates if this family is a product family (S/N) * `irrestrito` - Indicates if access is unrestricted (S/N) Stream for payment methods (e.g. boleto, PIX). **Key Fields:** * `id` - Payment method identifier (primary key) * `descricao` - Payment method description * `tipoCobranca` - Billing type code (e.g. BLO for boleto) Stream for invoice models (modelos de notas fiscais). **Key Fields:** * `id` - Invoice model identifier (primary key) * `descricao` - Invoice model description * `serie` - Invoice series number * `empresa` - Company name associated with the invoice model Stream for document type codes and their descriptions (e.g. NF, BOL, CTR). The API returns a key-value map; each entry is exposed as one record. **Key Fields:** * `codigo` - Document type code (primary key) * `descricao` - Full document type description Stream for payment types and their settings. **Key Fields:** * `id` - Payment type identifier (primary key) * `descricao` - Payment type description * `leContaDeposito` - Indicates if this payment type reads a deposit account (S/N) * `obrigaContaDeposito` - Indicates if a deposit account is required (S/N) * `contas_financeiras_id` - Associated financial account identifier * `nome_interno` - Internal name used for system identification Stream for transaction types (e.g. TED, DOC, Cheque). **Key Fields:** * `id` - Transaction type identifier (primary key) * `descricao` - Transaction type description * `visivel` - Contexts where this transaction type is available (e.g. Pagamento - Recebimento) Stream for billing suspension types (contract/item suspension, upgrade/downgrade, etc.). **Key Fields:** * `id` - Suspension type identifier (primary key) * `ativo` - Indicates whether the suspension type is active (S/N) * `descricao` - Suspension type description * `periodoIndeterminado` - Indicates if the suspension has an indefinite period (S/N) * `validoParaContrato` - Indicates if applicable to contracts (S/N) * `validoParaItensContrato` - Indicates if applicable to contract items (S/N) * `upgradeDowngrade` - Indicates if this type represents an upgrade or downgrade (S/N) * `disponivelParaRevisaoFaturamento` - Indicates if available for billing review (S/N) Stream for the management chart of accounts (plano de contas gerencial). Some records are category headers without a management code. **Key Fields:** * `descricao` - Account description including hierarchical code and name (primary key) * `codGerencial` - Management account code (absent for category headers) Stream for the fiscal chart of accounts (plano de contas fiscal). **Key Fields:** * `cod_fiscal` - Fiscal account code (primary key) * `cod_fiscal_ext` - Extended hierarchical fiscal account code * `nome` - Fiscal account name * `ativo` - Indicates whether the account is active (S/N) Stream for cost apportionment codes (rateios) used in allocations. **Key Fields:** * `codRateio` - Apportionment code identifier (primary key) * `codEstendido` - Extended hierarchical code of the apportionment * `descricao` - Apportionment description Stream for services and products (serviços) with pricing and family. **Key Fields:** * `id` - Service/product identifier (primary key) * `familia` - Product/service family name * `descricao` - Service or product description * `valorCompra` - Purchase price * `valorVenda` - Sale price * `codigo` - Service or product code * `valorComissao` - Commission value for the service or product Stream for receivables (titulos a receber). Records are built from the API response: base data is flattened from `dados_basicos`, and nested arrays (gerencias, rateios, duplicatas, etc.) are kept. Supports incremental sync by `data_ultimaModificacao`. **Key Fields (dados\_basicos):** * `codFatura` - Invoice (fatura) identifier (primary key) * `cod_cliente` - Customer identifier code * `cliente` - Customer name * `tipo` - Document type code (e.g. ADT, AMV, BOL) * `numero` - Document number * `valor` - Total invoice amount * `data_emissao` - Invoice issue date * `data_entrada` - Invoice entry date in the system * `forma_pagamento` - Payment method description * `nro_parcelas` - Number of installments * `historico` - Invoice description or payment history * `previsao` - Indicates if this is a forecast entry (S/N) * `data_ultimaModificacao` - Last modification timestamp (replication key) * `data_criacao` - Record creation timestamp * `empresaId`, `empresa` - Company identifier and name * `acrescimos`, `abatimentos` - Additional charges and discounts * `status` - Invoice status (e.g. Aberto, Quitação total, Quitação parcial) * `referencia` - Reference period (e.g. 05/2022) * `observacao` - Additional notes **Nested arrays:** * `gerencias` - Management account allocations (grupo, cod\_gerencial, descricao, percentual, valor) * `rateios` - Cost apportionment allocations (grupo, cod\_rateio, descricao, percentual, valor) * `gerencias_acrescimos_abatimentos` - Allocations for surcharges and discounts * `duplicatas` - Installment schedule (parcela, loteId, data\_vencimento, data\_previsao\_pagamento, valor, saldo) Stream for payables (titulos a pagar). Same structure as Títulos a Receber: base data from `dados_basicos` plus nested arrays. Supports incremental sync by `data_ultimaModificacao`. **Key Fields (dados\_basicos):** * `codFatura` - Invoice (fatura) identifier (primary key) * `cod_fornecedor` - Supplier identifier code * `fornecedor` - Supplier name * `tipo` - Document type code (e.g. NF, FAT, CF) * `numero` - Document number * `valor` - Total invoice amount * `data_emissao` - Invoice issue date * `data_entrada` - Invoice entry date in the system * `nro_parcelas` - Number of installments * `historico` - Invoice description or payment history * `previsao` - Indicates if this is a forecast entry (S/N) * `data_ultimaModificacao` - Last modification timestamp (replication key) * `data_criacao` - Record creation timestamp * `empresaId`, `empresa` - Company identifier and name * `acrescimos`, `abatimentos` - Additional charges and discounts * `status` - Invoice status (e.g. Aberto, Quitação total) * `observacao` - Additional notes **Nested arrays:** * `gerencias` - Management account allocations * `rateios` - Cost apportionment allocations * `duplicatas` - Installment schedule (parcela, loteId, data\_vencimento, valor, saldo, nroDoc) Stream for payments (pagamentos) registered in the system. Supports incremental sync by `modificado`. **Key Fields:** * `id` - Payment identifier (primary key) * `codigo` - Payment code reference * `lancamento` - Payment posting date * `conciliado` - Bank reconciliation date * `conta` - Account name associated with the payment * `valor` - Payment amount * `numeroTransacao` - Transaction number * `usuario` - User who registered the payment * `modificado` - Last modification timestamp (replication key) * `historico` - Payment history or description Stream for receipts (recebimentos) registered in the system. Supports incremental sync by `modificado`. **Key Fields:** * `id` - Receipt identifier (primary key) * `codigo` - Receipt code reference * `lancamento` - Receipt posting date * `conciliado` - Bank reconciliation date * `conta` - Account name associated with the receipt * `valor` - Receipt amount * `numeroTransacao` - Transaction number * `usuario` - User who registered the receipt * `modificado` - Last modification timestamp (replication key) * `historico` - Receipt history or description Stream for transfers (transferências) between accounts. Supports incremental sync by `modificado`. **Key Fields:** * `id` - Transfer identifier (primary key) * `lancamento` - Transfer posting date * `conciliado` - Bank reconciliation date * `conta` - Account name associated with the transfer * `valor` - Transfer amount * `numeroTransacao` - Transaction number * `usuario` - User who registered the transfer * `modificado` - Last modification timestamp (replication key) * `historico` - Transfer history or description # Data Model The following diagram illustrates the relationships between the main data streams in BSoft TMS. The arrows indicate the join keys that link the different entities. ```mermaid theme={null} graph TD; subgraph "Master & Reference" Empresas("Empresas"); CentrosCusto("Centros de Custo"); ContasFinanceiras("Contas Financeiras"); FormasPagamento("Formas de Pagamento"); PlanoContasGerencial("Plano Contas Gerencial"); PlanoContasFiscal("Plano Contas Fiscal"); Rateios("Rateios"); Servicos("Serviços"); FamiliaProdutos("Família Produtos e Serviços"); end subgraph "Receivables & Payables" TitulosReceber("Títulos a Receber"); TitulosPagar("Títulos a Pagar"); end subgraph "Movements" Pagamentos("Pagamentos"); Recebimentos("Recebimentos"); Transferencias("Transferências"); end TitulosReceber -- "empresaId" --> Empresas; TitulosPagar -- "empresaId" --> Empresas; Servicos -- "familia" --> FamiliaProdutos; TitulosReceber -- "gerencias.cod_gerencial / rateios.cod_rateio" --> PlanoContasGerencial; TitulosReceber -- "gerencias.cod_gerencial / rateios.cod_rateio" --> Rateios; TitulosPagar -- "gerencias / rateios" --> PlanoContasGerencial; TitulosPagar -- "gerencias / rateios" --> Rateios; ``` # Use Cases for Data Analysis This section outlines useful analyses when consolidating BSoft TMS data, with example SQL you can run on [Explorer](https://app.nekt.ai/explorer). ### 1. Receivables by status and company Summarize receivables (títulos a receber) by status and company to monitor open and paid amounts. **Business value:** * Track open receivables per company * Compare totals by status (Aberto, Quitação total, Quitação parcial) * Support cash flow and aging analysis ```sql theme={null} SELECT empresa, empresaId, status, COUNT(*) AS qtd_titulos, SUM(TRY_CAST(valor AS DECIMAL(20, 2))) AS valor_total FROM nekt_raw.bsoft_tms_titulos_receber GROUP BY empresa, empresaId, status ORDER BY empresa, status ``` ```sql theme={null} SELECT empresa, empresaId, status, COUNT(*) AS qtd_titulos, SUM(SAFE_CAST(valor AS FLOAT64)) AS valor_total FROM `nekt_raw.bsoft_tms_titulos_receber` GROUP BY empresa, empresaId, status ORDER BY empresa, status ``` ### 2. Payments and receipts summary Aggregate payments and receipts by posting date for a cash flow view. **Business value:** * Daily cash in and out * Compare payments vs receipts over time * Support reconciliation and reporting ```sql theme={null} SELECT lancamento AS data_lancamento, SUM(TRY_CAST(valor AS DECIMAL(20, 2))) AS total_pagamentos FROM nekt_raw.bsoft_tms_pagamentos GROUP BY lancamento ORDER BY lancamento DESC LIMIT 30 ``` ```sql theme={null} SELECT lancamento AS data_lancamento, SUM(SAFE_CAST(valor AS FLOAT64)) AS total_pagamentos FROM `nekt_raw.bsoft_tms_pagamentos` GROUP BY lancamento ORDER BY lancamento DESC LIMIT 30 ``` ## Implementation Notes ### Authentication * The connector uses **HTTP Basic Authentication** (username and password). Ensure the user has the integration profile in BSoft TMS and that the domain is reachable from the Nekt environment. ### Pagination * The BSoft TMS API uses limit-based pagination in the form `limit=offset,count`. The tap requests pages of a fixed size and stops when a partial page is returned. ### Incremental sync * Streams with a replication key support incremental sync: **titulos\_receber** (`data_ultimaModificacao`), **titulos\_pagar** (`data_ultimaModificacao`), **pagamentos** (`modificado`), **recebimentos** (`modificado`), **transferencias** (`modificado`). The tap uses bookmarking only (no date filter is sent to the API). On the first run, all records are synced; on subsequent runs, only new or updated records are emitted based on the replication key. ### Data types * Monetary and numeric values are often returned as strings by the API. Use casting in SQL (e.g. `TRY_CAST(valor AS DECIMAL(20,2))` or `SAFE_CAST(valor AS FLOAT64)`) for aggregations and calculations. ## Skills for agents BSoft TMS connector documentation as plain markdown, for use in AI agent contexts.