Skip to main content
BomControle is a Brazilian cloud ERP for service and product companies: finance (receivables, payables, bank accounts and cash flow), sales and recurring contracts with invoicing, CRM and registers. This connector reads your BomControle account through its integration API and brings every installment of your receivables and payables (open or paid), your financial accounts and categories, sales with their invoices, sales contracts, quotes, the product and service catalog, companies, customers, suppliers, employees, departments, and the CRM’s leads, opportunities, custom fields and activities.
The connector only reads data. It never creates, changes or deletes anything in BomControle.

Configuring BomControle as a Source

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

1. Add account access

The connector signs in with a BomControle API key. In BomControle, click the gear icon (Configurações) in the top right menu and open Configuração de API Key. Click Cadastrar Novo, give the key a name (for example, “Nekt”), choose the company it can access and the modules it may read, and save. Then find the key in the list and click Copiar API Key para o Clipboard to copy it.
The key only reads the company and the modules chosen for it. Give it every module whose tables you want to sync (finance, sales, CRM and registers). If you have more than one company, create one source per company, each with its own key.
The following configurations are available:
  • API Key: The BomControle API key.
  • Start Date: Earliest date read by the Financial Movements table on the first sync and on full syncs: installments created or changed since this date. The other tables are always read in full.
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, 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.
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.

Fields by stream

Dates and times are in BomControle’s local time (Brasília), as BomControle sends them, without a time zone. Money values are exact decimals.

Finance

Installments (parcelas) of every receivable and payable, open or paid, with dates, values, payment method, category, account, company, customer or supplier and invoice numbers.Table: financial_movements · Primary key: id_movimentacao_financeira_parcela · Sync: Incremental (by data_ultima_alteracao)
Bank, cash, credit and payment-means accounts of each company.Table: financial_accounts · Primary key: id_empresa, id · Sync: Full table
Revenue and expense categories of the chart of accounts.Table: financial_categories · Primary key: id · Sync: Full table

Sales

Sales with their company, customer, services and invoices (faturas).Table: sales · Primary key: id · Sync: Full table
Recurring and installment contracts of the sales, with value, billing frequency and price adjustment.Table: sales_contracts · Primary key: id · Sync: Full table
Quotes (orçamentos) with their company, customer and items.Table: quotes · Primary key: id · Sync: Full table
Products and services of the catalog, with price, stock quantity and unit.Table: products_services · Primary key: tipo_item, id · Sync: Full table

Registers

Companies (empresas) the API key may read.Table: companies · Primary key: id · Sync: Full table
Customers, individuals or companies, with address and contacts.Table: customers · Primary key: id · Sync: Full table
Suppliers, individuals or companies, with address and contacts.Table: suppliers · Primary key: id · Sync: Full table
Employees with address, contacts and companies.Table: employees · Primary key: id · Sync: Full table
Departments (cost centers) used in financial movements.Table: departments · Primary key: id · Sync: Full table

CRM

CRM leads with their number of opportunities and contacts.Table: leads · Primary key: id · Sync: Full table
Opportunities of the sales funnel with stage, status, temperature, value and salesperson.Table: opportunities · Primary key: id · Sync: Full table
Custom fields defined for opportunities, with the options of list fields.Table: opportunity_custom_fields · Primary key: id_campo · Sync: Full table
Activities (calls, meetings, tasks) of the opportunities.Table: crm_activities · Primary key: id · Sync: Full table

Implementation notes

  • Financial Movements is the only incremental table. Each sync reads the installments created or changed since the previous sync (re-reading the last four hours), so a payment, a new due date, a discount or a cancellation brings the installment back with its new values. The first sync and full syncs read everything created or changed since the Start Date, 30 days at a time.
  • Deleted records. BomControle does not report deleted records. An installment deleted in BomControle stays in the Financial Movements table until a full sync; the full table tables drop it on the next sync.
  • Full table tables. BomControle’s lists of registers, sales, contracts, quotes, products and CRM data have no “changed since” filter, so they are read in full on every sync. If one that had records suddenly comes back empty, that table fails instead of being emptied, and keeps its data; run a full sync of the source if the data really was removed in BomControle. If one comes back with far fewer records than the previous sync, the sync loads it and shows a warning.
  • Long lists. Some BomControle lists come back in a single answer. When one comes back with a round number of records (a multiple of 50), the connector reads it again page by page to make sure nothing was cut; if BomControle does not allow that, the table fails instead of loading a list that may be incomplete. When a list comes back empty, the sync log says so, so you can check the company and modules of the API key.
  • Lists that change during the sync. When a list changes while it is being read (a record edited between two pages), the connector reads it again so that no record is skipped; if it keeps changing, that table fails and is read on the next sync.
  • Permissions. A table the API key may not read is skipped with a warning that names it, and the other tables still load. To sync it, give the key the module of that table in Configuração de API Key, or deselect the table. If the key cannot read any selected table (or is wrong), the sync stops before loading anything.
  • Invoices of sales. The invoices (faturas) of each sale, with their payment status, are in the faturas column of Sales as JSON. Each invoice’s installment is also a row of Financial Movements (id_fatura).
  • Fields. Lists inside a record (contacts, invoices, services, items) are stored as JSON text. Any field the API returns that is not a column yet is kept in the extra_fields column, as JSON with the original field names.