> ## 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.

# BomControle as a data source

> Bring financial movements (receivables and payables), financial accounts and categories, sales, contracts, quotes, products and services, customers, suppliers, employees and CRM data from the BomControle ERP to Nekt.

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.

> [!NOTE]
>
> The connector only reads data. It never creates, changes or deletes anything in BomControle.

## Configuring BomControle 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 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.

> [!WARNING]
>
> 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](https://docs.nekt.com/runs/scheduling-and-triggers.md), 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.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/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

> [accordion] Financial Movements
>
> 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`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id_movimentacao_financeira_parcela` | String | BomControle ID (GUID) of the installment of the financial movement. |
> | `debito` | Boolean | Whether the movement is a debit (payable) rather than a credit (receivable). |
> | `data_vencimento` | Datetime | Due date of the installment. |
> | `data_competencia` | Datetime | Accrual (competência) date of the installment. |
> | `data_quitacao` | Datetime | Date the installment was paid (settled); empty while open. |
> | `data_conciliacao` | Datetime | Date the installment was reconciled with the bank. |
> | `data_faturamento` | Datetime | Billing date. |
> | `data_criacao_parcela` | Datetime | When the installment was created (BomControle local time). |
> | `data_ultima_alteracao` | Datetime | When the installment was last changed (BomControle local time), used as the incremental replication key. |
> | `valor` | Number | Value of the installment. |
> | `valor_bruto` | Number | Gross value of the installment. |
> | `valor_acrescimo` | Number | Surcharge (interest, fines) added to the installment. |
> | `valor_desconto` | Number | Discount applied to the installment. |
> | `valor_definitivo` | Boolean | Whether the value of the installment is final. |
> | `forma_pagamento` | Integer | Payment method code (1 = cash, 2 = deposit, 3 = check, 5 = bank transfer, 6 = credit card, 7 = debit card, 9 = TED, 12 = internet banking, 13 = boleto, 15 = other, 16 = account debit...). |
> | `nome_forma_pagamento` | String | Name of the payment method. |
> | `tipo_movimentacao` | String | Movement type code (15 = capital contribution, 16 = product revenue, 17 = service revenue, 18 = other revenue, 19 = supplier expense, 20 = employee expense, 21 = tax expense, 22 = profit distribution). |
> | `nome_tipo_movimentacao` | String | Name of the movement type. |
> | `nome` | String | Name (description) of the installment. |
> | `observacao` | String | Notes of the installment. |
> | `numero_parcela` | Integer | Number of the installment within the movement. |
> | `quantidade_parcela` | Integer | Number of installments of the movement. |
> | `numero_documento` | String | Document number informed on the movement. |
> | `etiquetas_movimentacao` | String (JSON) | Tags of the movement, as sent by the API. |
> | `id_categoria_financeira` | Integer | BomControle ID of the financial category (0 when the installment has more than one category). |
> | `nome_categoria_financeira` | String | Name of the financial category (empty when the installment has more than one category). |
> | `icone_categoria_financeira` | String | Icon of the financial category. |
> | `tem_rateio` | Boolean | Whether the installment is split (rateio) across categories or departments. |
> | `id_conta_financeira` | Integer | BomControle ID of the financial (bank or cash) account. |
> | `nome_conta_financeira` | String | Name of the financial account. |
> | `numero_conta` | String | Account number of the financial account. |
> | `digito_conta` | String | Check digit of the account number. |
> | `numero_agencia` | String | Branch number of the financial account. |
> | `digito_agencia` | String | Check digit of the branch number. |
> | `nome_banco` | String | Bank name (Febraban) of the financial account. |
> | `numero_banco` | String | Bank number (Febraban) of the financial account. |
> | `id_empresa` | Integer | BomControle ID of the company of the installment. |
> | `nome_empresa` | String | Name of the company of the installment. |
> | `documento_empresa` | String | CNPJ of the company of the installment. |
> | `id_cliente` | Integer | BomControle ID of the customer (receivables). |
> | `id_fornecedor` | Integer | BomControle ID of the supplier (payables). |
> | `id_funcionario` | Integer | BomControle ID of the employee (payables). |
> | `nome_cliente_fornecedor` | String | Name of the customer, supplier or employee. |
> | `nome_fantasia_cliente_fornecedor` | String | Trade name of the customer or supplier. |
> | `documento_cliente_fornecedor` | String | CPF or CNPJ of the customer, supplier or employee. |
> | `id_departamento` | Integer | BomControle ID of the department (0 when the installment has more than one department). |
> | `nome_departamento` | String | Name of the department (empty when the installment has more than one department). |
> | `tipo_departamento` | Integer | Type of the department (1 = Administrativo, 2 = Produtivo). |
> | `nome_tipo_departamento` | String | Name of the type of the department. |
> | `id_fatura` | Integer | BomControle ID of the invoice (fatura) of the installment. |
> | `link_boleto_bancario` | String | Link to the boleto of the installment. |
> | `link_nota_fiscal_servico` | String | Link to the service invoice (NFS-e) of the installment. |
> | `nota_fiscal_servico_parcela` | String | Number of the service invoice linked to the installment. |
> | `nota_fiscal_servico_venda` | String | Number of the service invoice linked to the sale. |
> | `nota_fiscal_produto` | String | Number of the product invoice (NF-e). |
> | `nota_fiscal_consumidor` | String | Number of the consumer invoice (NFC-e). |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Financial Accounts
>
> Bank, cash, credit and payment-means accounts of each company.
>
> Table: `financial_accounts` · Primary key: `id_empresa`, `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id_empresa` | Integer | BomControle ID of the company the account belongs to. |
> | `id` | Integer | BomControle ID of the financial account. |
> | `nome` | String | Name of the financial account. |
> | `tipo` | Integer | Type of the account (1 = cash, 2 = bank, 3 = credit, 4 = payment means). |
> | `nome_tipo` | String | Name of the type of the account. |
> | `agencia` | String | Branch number. |
> | `digito_agencia` | String | Check digit of the branch number. |
> | `conta` | String | Account number. |
> | `digito_conta` | String | Check digit of the account number. |
> | `nome_banco` | String | Bank name (Febraban). |
> | `numero_banco` | String | Bank number (Febraban). |
> | `permite_recebimento` | Boolean | Whether the account accepts receipts. |
> | `permite_pagamento` | Boolean | Whether the account allows payments. |
> | `emite_boleto` | Boolean | Whether the account can issue boletos. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Financial Categories
>
> Revenue and expense categories of the chart of accounts.
>
> Table: `financial_categories` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the financial category. |
> | `id_categoria_pai` | Integer | BomControle ID of the parent category (BomControle documents it as not used). |
> | `nome` | String | Name of the financial category. |
> | `despesa` | Boolean | Whether it is an expense category (otherwise revenue). |
> | `transferencia` | Boolean | Transfer flag, as sent by the API (documented as not used). |
> | `inicial` | Boolean | Initial-balance flag, as sent by the API (documented as not used). |
> | `icone` | String | Icon of the category. |
> | `codigo_contabil` | String | Accounting code of the category. |
> | `padrao` | Boolean | Default flag, as sent by the API (documented as not used). |
> | `orcamento_mensal` | Number | Monthly budget, as sent by the API (documented as not used). |
> | `orcado_por_valor` | Boolean | Budget-by-value flag, as sent by the API (documented as not used). |
> | `destacar_fluxo_caixa` | Boolean | Highlight-in-cash-flow flag, as sent by the API (documented as not used). |
> | `desconto` | Boolean | Discount flag, as sent by the API (documented as not used). |
> | `acrescimo` | Boolean | Surcharge flag, as sent by the API (documented as not used). |
> | `aporte` | Boolean | Capital-contribution flag, as sent by the API (documented as not used). |
> | `divisao_lucro` | Boolean | Profit-distribution flag, as sent by the API (documented as not used). |
> | `fixa` | Boolean | Fixed-cost flag, as sent by the API (documented as not used). |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

### Sales

> [accordion] Sales
>
> Sales with their company, customer, services and invoices (faturas).
>
> Table: `sales` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the sale. |
> | `cancelado` | Boolean | Whether the sale was cancelled. |
> | `empresa_id` | Integer | BomControle ID of the company (Empresa) of the record. |
> | `empresa_documento` | String | CNPJ of the company of the record. |
> | `empresa_nome` | String | Name of the company of the record. |
> | `empresa_padrao` | Boolean | Whether the company is the main company of the BomControle account. |
> | `cliente_id` | Integer | BomControle ID of the customer. |
> | `cliente_documento` | String | CPF or CNPJ of the customer. |
> | `cliente_nome` | String | Name of the customer (person name, or legal name of a company). |
> | `cliente` | String (JSON) | Full customer record as sent with the document: person data, address and contacts. |
> | `servicos` | String (JSON) | Services of the sale: item id, sale id, service id, quantity and unit value. |
> | `faturas` | String (JSON) | Invoices (faturas) of the sale: due and payment dates, values, installment, paid/reconciled flags, payment method, boleto and invoice links. |
> | `valor` | Number | Total value of the sale. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Sales Contracts
>
> Recurring and installment contracts of the sales, with value, billing frequency and price adjustment.
>
> Table: `sales_contracts` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the contract. |
> | `id_venda` | Integer | BomControle ID of the sale of the contract. |
> | `inicio` | Datetime | Start date of the contract. |
> | `termino` | Datetime | End date of the contract. |
> | `tipo_pagamento` | Integer | Type of the contract (0 = recurring, 1 = installments). |
> | `nome_tipo_pagamento` | String | Name of the type of the contract. |
> | `encerrado` | Boolean | Whether the contract was closed. |
> | `data_encerramento` | Datetime | When the contract was closed. |
> | `empresa_id` | Integer | BomControle ID of the company (Empresa) of the record. |
> | `empresa_documento` | String | CNPJ of the company of the record. |
> | `empresa_nome` | String | Name of the company of the record. |
> | `empresa_padrao` | Boolean | Whether the company is the main company of the BomControle account. |
> | `cliente_id` | Integer | BomControle ID of the customer. |
> | `cliente_documento` | String | CPF or CNPJ of the customer. |
> | `cliente_nome` | String | Name of the customer (person name, or legal name of a company). |
> | `cliente` | String (JSON) | Full customer record as sent with the document: person data, address and contacts. |
> | `valor` | Number | Value of the contract. |
> | `periodicidade` | Integer | Billing frequency (1 = daily, 2 = weekly, 3 = fortnightly, 4 = monthly, 5 = yearly, 6 = quarterly, 7 = half-yearly, 8 = bimonthly). |
> | `proximo_reajuste` | Datetime | Date of the next price adjustment. |
> | `indice_reajuste` | Integer | Price adjustment index (0 = none, 1 = IPCA, 2 = IGPM, 3 = INPC, 4 = IGPDI, 5 = INCC, 6 = other). |
> | `nome_indice_reajuste` | String | Name of the price adjustment index. |
> | `periodo_reajuste` | Integer | Price adjustment period (same codes as periodicidade). |
> | `nome_periodo_reajuste` | String | Name of the price adjustment period. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Quotes
>
> Quotes (orçamentos) with their company, customer and items.
>
> Table: `quotes` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the quote. |
> | `cancelado` | Boolean | Whether the quote was cancelled. |
> | `empresa_id` | Integer | BomControle ID of the company (Empresa) of the record. |
> | `empresa_documento` | String | CNPJ of the company of the record. |
> | `empresa_nome` | String | Name of the company of the record. |
> | `empresa_padrao` | Boolean | Whether the company is the main company of the BomControle account. |
> | `cliente_id` | Integer | BomControle ID of the customer. |
> | `cliente_documento` | String | CPF or CNPJ of the customer. |
> | `cliente_nome` | String | Name of the customer (person name, or legal name of a company). |
> | `cliente` | String (JSON) | Full customer record as sent with the document: person data, address and contacts. |
> | `itens` | String (JSON) | Items of the quote: service id, description, quantity, unit value, discount, external code and name. |
> | `servicos` | String (JSON) | Services of the quote, when sent by the API. |
> | `faturas` | String (JSON) | Invoices of the quote, when sent by the API. |
> | `valor` | Number | Value of the quote. |
> | `valor_definitivo` | Boolean | Whether the value of the quote is final. |
> | `data_previsao_entrega` | Datetime | Date of the quote (expected delivery). |
> | `observacao` | String | Notes of the quote. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Products and Services
>
> Products and services of the catalog, with price, stock quantity and unit.
>
> Table: `products_services` · Primary key: `tipo_item`, `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the product or service. |
> | `tipo_item` | Integer | Type of the item (0 = product, 1 = service); products and services have separate IDs. |
> | `nome_tipo_item` | String | Name of the type of the item (Produto or Serviço). |
> | `nome` | String | Name of the product or service. |
> | `observacao` | String | Notes of the product or service. |
> | `item_de_venda` | Boolean | Whether the item is registered for sale (otherwise for internal use). |
> | `quantidade` | Number | Current quantity of the product in the sales stock. |
> | `valor` | Number | Sale price of the product or service. |
> | `id_tipo_servico` | Integer | BomControle ID of the service type. |
> | `nome_tipo_servico` | String | Name of the service type. |
> | `preco_venda_minimo` | Number | Minimum sale price of the product. |
> | `preco_venda_maximo` | Number | Maximum sale price of the product. |
> | `ncm` | String | NCM code of the product. |
> | `id_unidade` | Integer | BomControle ID of the unit of the product. |
> | `nome_unidade` | String | Name of the unit of the product. |
> | `sigla_unidade` | String | Abbreviation of the unit of the product. |
> | `itens_combo` | String (JSON) | Items of a product of type Combo. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

### Registers

> [accordion] Companies
>
> Companies (empresas) the API key may read.
>
> Table: `companies` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the company. |
> | `documento` | String | CNPJ of the company. |
> | `nome` | String | Trade name of the company. |
> | `padrao` | Boolean | Whether this is the main (default) company of the BomControle account. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Customers
>
> Customers, individuals or companies, with address and contacts.
>
> Table: `customers` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the customer. |
> | `tipo_pessoa` | String | Type of person of the customer (Fisica = individual, Juridica = company). |
> | `pais_origem` | String | Country of origin of the customer. |
> | `pessoa_fisica_documento` | String | CPF of the customer, when an individual. |
> | `pessoa_fisica_nome` | String | Name of the customer, when an individual. |
> | `pessoa_fisica_sexo` | String | Sex of the customer, when an individual (M, F, O). |
> | `pessoa_fisica_data_nascimento` | Datetime | Birth date of the customer, when an individual. |
> | `pessoa_juridica_documento` | String | CNPJ of the customer, when a company. |
> | `pessoa_juridica_nome_fantasia` | String | Trade name of the customer, when a company. |
> | `pessoa_juridica_razao_social` | String | Legal name of the customer, when a company. |
> | `pessoa_juridica_isento_inscricao_estadual` | String | Whether the customer is exempt from the state registration (as sent by BomControle). |
> | `pessoa_juridica_inscricao_estadual` | String | State registration number of the customer. |
> | `pessoa_juridica_uf_inscricao_estadual` | String | State of the state registration of the customer. |
> | `pessoa_juridica_inscricao_municipal` | String | Municipal registration number of the customer. |
> | `pessoa_juridica_ramo_atividade` | String | Line of business of the customer. |
> | `bloqueado` | Boolean | Whether the customer is blocked in BomControle. |
> | `endereco_id` | Integer | BomControle ID of the address of the customer. |
> | `endereco_tipo_logradouro` | String | Street type of the customer's address (Rua, Avenida, Travessa...). |
> | `endereco_logradouro` | String | Street of the customer's address. |
> | `endereco_numero` | String | Street number of the customer's address. |
> | `endereco_complemento` | String | Address complement of the customer. |
> | `endereco_bairro` | String | District of the customer's address. |
> | `endereco_cep` | String | Postal code (CEP) of the customer's address. |
> | `endereco_cidade` | String | City of the customer's address. |
> | `endereco_uf` | String | State (UF) of the customer's address. |
> | `contatos` | String (JSON) | Contacts of the customer: id, name, email, phone, whether it is the main contact and whether it receives billing. |
> | `data_criacao` | Datetime | When the customer was created in BomControle (BomControle local time). |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Suppliers
>
> Suppliers, individuals or companies, with address and contacts.
>
> Table: `suppliers` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the supplier. |
> | `id_pessoa` | Integer | BomControle ID of the person record behind the supplier. |
> | `tipo_pessoa` | String | Type of person of the supplier (Fisica = individual, Juridica = company). |
> | `pais_origem` | String | Country of origin of the supplier. |
> | `pessoa_fisica_documento` | String | CPF of the supplier, when an individual. |
> | `pessoa_fisica_nome` | String | Name of the supplier, when an individual. |
> | `pessoa_fisica_sexo` | String | Sex of the supplier, when an individual (M, F, O). |
> | `pessoa_fisica_data_nascimento` | Datetime | Birth date of the supplier, when an individual. |
> | `pessoa_juridica_documento` | String | CNPJ of the supplier, when a company. |
> | `pessoa_juridica_nome_fantasia` | String | Trade name of the supplier, when a company. |
> | `pessoa_juridica_razao_social` | String | Legal name of the supplier, when a company. |
> | `pessoa_juridica_isento_inscricao_estadual` | String | Whether the supplier is exempt from the state registration (as sent by BomControle). |
> | `pessoa_juridica_inscricao_estadual` | String | State registration number of the supplier. |
> | `pessoa_juridica_uf_inscricao_estadual` | String | State of the state registration of the supplier. |
> | `pessoa_juridica_inscricao_municipal` | String | Municipal registration number of the supplier. |
> | `pessoa_juridica_ramo_atividade` | String | Line of business of the supplier. |
> | `bloqueado` | Boolean | Whether the supplier is blocked in BomControle. |
> | `endereco_id` | Integer | BomControle ID of the address of the supplier. |
> | `endereco_tipo_logradouro` | String | Street type of the supplier's address (Rua, Avenida, Travessa...). |
> | `endereco_logradouro` | String | Street of the supplier's address. |
> | `endereco_numero` | String | Street number of the supplier's address. |
> | `endereco_complemento` | String | Address complement of the supplier. |
> | `endereco_bairro` | String | District of the supplier's address. |
> | `endereco_cep` | String | Postal code (CEP) of the supplier's address. |
> | `endereco_cidade` | String | City of the supplier's address. |
> | `endereco_uf` | String | State (UF) of the supplier's address. |
> | `contatos` | String (JSON) | Contacts of the supplier: id, name, email, phone, whether it is the main contact and whether it receives billing. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Employees
>
> Employees with address, contacts and companies.
>
> Table: `employees` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the employee. |
> | `id_pessoa` | Integer | BomControle ID of the person record behind the employee. |
> | `pessoa_fisica_documento` | String | CPF of the employee, when an individual. |
> | `pessoa_fisica_nome` | String | Name of the employee, when an individual. |
> | `pessoa_fisica_sexo` | String | Sex of the employee, when an individual (M, F, O). |
> | `pessoa_fisica_data_nascimento` | Datetime | Birth date of the employee, when an individual. |
> | `endereco_id` | Integer | BomControle ID of the address of the employee. |
> | `endereco_tipo_logradouro` | String | Street type of the employee's address (Rua, Avenida, Travessa...). |
> | `endereco_logradouro` | String | Street of the employee's address. |
> | `endereco_numero` | String | Street number of the employee's address. |
> | `endereco_complemento` | String | Address complement of the employee. |
> | `endereco_bairro` | String | District of the employee's address. |
> | `endereco_cep` | String | Postal code (CEP) of the employee's address. |
> | `endereco_cidade` | String | City of the employee's address. |
> | `endereco_uf` | String | State (UF) of the employee's address. |
> | `contatos` | String (JSON) | Contacts of the employee: id, name, email, phone, whether it is the main contact. |
> | `empresas` | String (JSON) | Companies the employee works for: company id, name, CNPJ, short name and color. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Departments
>
> Departments (cost centers) used in financial movements.
>
> Table: `departments` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the department. |
> | `nome` | String | Name of the department. |
> | `tipo` | Integer | Type of the department (1 = Administrativo, 2 = Produtivo). |
> | `nome_tipo` | String | Name of the type of the department. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

### CRM

> [accordion] Leads
>
> CRM leads with their number of opportunities and contacts.
>
> Table: `leads` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the person (lead). |
> | `tipo_pessoa` | Integer | Type of person of the lead (0 = company, 1 = individual). |
> | `nome` | String | Name of the lead. |
> | `nome_fantasia` | String | Trade name of the lead. |
> | `documento` | String | CPF or CNPJ of the lead. |
> | `numero_oportunidades` | Integer | Number of opportunities of the lead. |
> | `numero_contatos` | Integer | Number of contacts of the lead. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Opportunities
>
> Opportunities of the sales funnel with stage, status, temperature, value and salesperson.
>
> Table: `opportunities` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the opportunity. |
> | `titulo` | String | Title of the opportunity. |
> | `observacao` | String | Notes of the opportunity. |
> | `tipo_lead` | Integer | Type of person of the lead (0 = company, 1 = individual). |
> | `id_lead` | Integer | BomControle ID of the person (lead) of the opportunity. |
> | `nome_lead` | String | Name of the lead. |
> | `documento_lead` | String | CPF or CNPJ of the lead. |
> | `id_usuario_resposavel` | Integer | BomControle ID of the user responsible for the opportunity (field name as spelled by the API). |
> | `nome_usuario_responsavel` | String | Name of the user responsible for the opportunity. |
> | `login_usuario` | String | Login of the user responsible for the opportunity. |
> | `usuario` | String (JSON) | User object of the opportunity, as sent by the API. |
> | `id_vendedor` | Integer | BomControle ID of the salesperson. |
> | `nome_vendedor` | String | Name of the salesperson. |
> | `link_imagem_vendedor` | String | Link to the salesperson's picture. |
> | `documento_vendedor` | String | Document of the salesperson. |
> | `data_criacao` | Datetime | When the opportunity was created (BomControle local time). |
> | `data_prevista` | Datetime | Expected closing date of the opportunity. |
> | `status` | Integer | Status of the opportunity (0 = open, 1 = won, 2 = lost). |
> | `temperatura_da_oportunidade` | Integer | Temperature of the opportunity (0 = frozen, 1 = warm, 2 = hot, 3 = very hot). |
> | `nome_temperatura_da_oportunidade` | String | Name of the temperature of the opportunity. |
> | `valor` | Number | Value of the opportunity. |
> | `id_etapa` | Integer | BomControle ID of the funnel stage of the opportunity. |
> | `nome_etapa` | String | Name of the funnel stage of the opportunity. |
> | `icone_etapa` | String | Icon of the funnel stage. |
> | `id_funil_venda` | Integer | BomControle ID of the sales funnel. |
> | `funil_venda` | String (JSON) | Sales funnel of the opportunity, as sent by the API. |
> | `data_ultima_troca_etapa` | Datetime | When the opportunity last changed stage (BomControle local time). |
> | `valor_intervalo` | String | Interval value of the opportunity, as sent by the API. |
> | `tipo_intervalo` | Integer | Interval type of the opportunity, as sent by the API. |
> | `quantidade_atividade` | Integer | Number of activities of the opportunity. |
> | `quantidade_atividade_atrasada` | Integer | Number of overdue activities of the opportunity. |
> | `quantidade_atividades_futuras` | Integer | Number of future activities of the opportunity. |
> | `formulario` | String (JSON) | Custom form answers of the opportunity, as sent by the API. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] Opportunity Custom Fields
>
> Custom fields defined for opportunities, with the options of list fields.
>
> Table: `opportunity_custom_fields` · Primary key: `id_campo` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id_campo` | Integer | BomControle ID of the custom field. |
> | `nome_campo` | String | Title of the custom field. |
> | `tipo_campo_formulario` | Integer | ID of the field type. |
> | `nome_tipo_campo_formulario` | String | Name of the field type (Texto, TextoMultilinha, Lista, Entidade...). |
> | `tipo_entidade_campo_formulario` | Integer | ID of the linked entity, for fields of type Entidade. |
> | `nome_tipo_entidade_campo_formulario` | String | Name of the linked entity, for fields of type Entidade. |
> | `obrigatorio` | Boolean | Whether the field is required when an opportunity is created. |
> | `itens_lista` | String (JSON) | Options of a field of type Lista: id, whether it is the default and its title. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

> [accordion] CRM Activities
>
> Activities (calls, meetings, tasks) of the opportunities.
>
> Table: `crm_activities` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | BomControle ID of the activity. |
> | `descricao` | String | Description of the activity. |
> | `titulo` | String | Title of the opportunity of the activity. |
> | `data` | Datetime | Start date of the activity. |
> | `data_fim` | Datetime | End date of the activity. |
> | `hora_inicio` | String | Start time of the activity. |
> | `hora_fim` | String | End time of the activity. |
> | `tipo_lead` | Integer | Type of person of the lead (0 = company, 1 = individual). |
> | `id_lead` | Integer | BomControle ID of the lead. |
> | `nome_lead` | String | Name of the lead. |
> | `documento_lead` | String | CPF or CNPJ of the lead. |
> | `id_tipo_atividade` | Integer | BomControle ID of the activity type. |
> | `nome_tipo_atividade` | String | Name of the activity type. |
> | `icone_tipo_atividade` | String | Icon of the activity type. |
> | `realizada` | Boolean | Whether the activity was done. |
> | `atrasado` | Boolean | Whether the activity is overdue (start date before today and not done). |
> | `id_usuario` | Integer | BomControle ID of the salesperson of the opportunity. |
> | `login_usuario` | String | Login of the salesperson of the opportunity. |
> | `nome_usuario_responsavel` | String | Name of the user responsible for the activity. |
> | `extra_fields` | String (JSON) | Fields the API returned that this connector does not map to a column yet, keyed by their original names. |

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.