> ## 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.
# VHSYS as a data source
> Bring data from VHSYS to your Lakehouse.
VHSYS is a Brazilian cloud ERP for small and medium businesses, covering sales, invoicing (NF-e, NFC-e and NFS-e), finance, purchasing, services and inventory in a single system. Nekt extracts this data through the VHSYS API v2.
## Configuring VHSYS 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 VHSYS option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
The API is enabled through the **Integração via API** app of your VHSYS account. If you don't have it yet: open the **Loja de Integração** inside VHSYS, search for "API", subscribe to the app, then click **Abrir aplicativo** to view your keys.
The following configurations are required:
* **Access Token**: The access token shown in the Integração via API app.
* **Secret Access Token**: The secret access token paired with the access token.
Optionally, under advanced settings:
* **Start Date**: The earliest date from which records will be synced for incremental streams. When omitted, the first sync fetches the full history.
* **Account Timezone**: IANA timezone used to render date filters in store-local time (defaults to America/Sao\_Paulo).
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/get-started/core-concepts/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).
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 VHSYS and their corresponding fields. Most streams sync incrementally, filtered by the records' last-change date; reference streams (finance categories, service list and service invoices) are extracted as full tables. Order and invoice items/installments are fetched per parent record processed in the current run.
Customer registrations, incrementally synced by their last-change date.
**Key Fields:**
* `id_cliente` - Unique ID of the customer
* `tipo_pessoa` - Person type (PJ = company, PF = individual)
* `cnpj_cliente` - CNPJ/CPF tax ID of the customer
* `razao_cliente` - Legal name of the customer
* `fantasia_cliente` - Trade name of the customer
* `email_cliente` - Email address of the customer
* `cidade_cliente` / `uf_cliente` - City and state of the customer
* `situacao_cliente` - Status of the customer
* `vendedor_cliente_id` - ID of the linked salesperson
* `limite_credito` - Credit limit
* `data_cad_cliente` / `data_mod_cliente` - Registration and last-modification dates
* `veiculos` - Vehicles of the customer (JSON)
Customer categories, incrementally synced by their last-change date.
**Key Fields:**
* `id_categoria` - Unique ID of the category
* `nome_categoria` - Name of the category
* `status_categoria` - Status of the category
* `data_cad_categoria` / `data_mod_categoria` - Registration and last-modification dates
Salespeople registrations, incrementally synced by their last-change date.
**Key Fields:**
* `id_vendedor` - Unique ID of the salesperson
* `cnpj_vendedor` - CNPJ/CPF tax ID
* `razao_vendedor` - Legal name or full name
* `email_vendedor` - Email address
* `comissao_usuario` / `comissao_regra` - Commission value and rule
* `situacao_vendedor` - Status of the salesperson
Carrier registrations, incrementally synced by their last-change date.
**Key Fields:**
* `id_transportadora` - Unique ID of the carrier
* `desc_transportadora` - Name of the carrier
* `cnpj_transportadora` - CNPJ/CPF tax ID
* `cidade_transportadora` / `estado_transportadora` - City and state
* `rntc_transportadora` - RNTC registry number
Product catalog, incrementally synced by their last-change date.
**Key Fields:**
* `id_produto` - Unique ID of the product
* `cod_produto` - Code (SKU) of the product
* `desc_produto` - Description (name) of the product
* `id_categoria` - ID of the product category
* `valor_produto` / `valor_custo_produto` - Sale and cost prices
* `estoque_produto` - Current stock quantity
* `ncm_produto` / `cest_produto` - Tax classification codes
* `codigo_barra_produto` - Barcode (EAN)
* `status_produto` - Status of the product
* `grades` / `variacoes` / `imagens` - Grids, variations and images (JSON)
Product categories, incrementally synced by their last-change date.
**Key Fields:**
* `id_categoria` - Unique ID of the category
* `nome_categoria` - Name of the category
* `status_categoria` - Status of the category
* `subcategorias` - Subcategories of the category (JSON)
Product subcategories, incrementally synced by their last-change date.
**Key Fields:**
* `id_subcategoria` - Unique ID of the subcategory
* `id_categoria` - ID of the parent category
* `nome_subcategoria` - Name of the subcategory
* `status_subcategoria` - Status of the subcategory
Sales orders, incrementally synced by their last-change date.
**Key Fields:**
* `id_ped` - Unique ID of the order
* `id_cliente` / `nome_cliente` - Customer of the order
* `vendedor_pedido_id` - ID of the salesperson
* `valor_total_produtos` - Total product amount
* `desconto_pedido` / `frete_pedido` - Discount and freight amounts
* `valor_total_nota` - Total order amount
* `status_pedido` - Status of the order
* `data_pedido` - Date of the order
* `data_cad_pedido` / `data_mod_pedido` - Registration and last-modification dates
Line items of each sales order processed in the current run.
**Key Fields:**
* `id_ped_produto` - Unique ID of the line item
* `id_pedido` - ID of the sales order
* `id_produto` / `desc_produto` - Product of the line item
* `qtde_produto` - Quantity
* `valor_unit_produto` / `valor_total_produto` - Unit and total amounts
* `desconto_produto` - Discount amount
Installments of each sales order processed in the current run.
**Key Fields:**
* `id_parcela` - Unique ID of the installment
* `id_pedido` - ID of the sales order
* `data_parcela` - Due date of the installment
* `valor_parcela` - Amount of the installment
* `forma_pagamento` - Payment method
Sales quotes, incrementally synced by their last-change date.
**Key Fields:**
* `id_orcamento` - Unique ID of the quote
* `id_cliente` / `nome_cliente` - Customer of the quote
* `valor_total_nota` - Total quote amount
* `validade_orcamento` - Validity date
* `status_pedido` - Status of the quote
* `pedido_emitido` / `nota_emitida` - Whether an order/invoice was generated from the quote
Point-of-sale (counter) sales, incrementally synced by their last-change date.
**Key Fields:**
* `id_frente` - Unique ID of the counter sale
* `id_cliente` / `nome_cliente` - Customer of the sale
* `valor_total_nota` - Total sale amount
* `forma_pagamento` - Payment method
* `valor_recebido` / `troco_pedido` - Amount received and change
* `nfce_emitido` - Whether an NFC-e was issued
Product invoices, incrementally synced by their last-change date.
**Key Fields:**
* `id_venda` - Unique ID of the invoice
* `id_cliente` / `nome_cliente` - Customer of the invoice
* `valor_total_produtos` / `valor_total_nota` - Product and total amounts
* `valor_icms` / `valor_ipi` / `valor_st` - Tax amounts
* `natureza_pedido` - Nature of the operation
* `nota_chave` - Access key of the NF-e
* `nota_data_autorizacao` - Authorization date
* `status_pedido` - Status of the invoice
* `data_emissao` - Issue date
Line items of each product invoice processed in the current run.
**Key Fields:**
* `id_ped_produto` - Unique ID of the line item
* `id_venda` - ID of the invoice
* `id_produto` / `desc_produto` - Product of the line item
* `qtde_produto` - Quantity
* `valor_unit_produto` / `valor_total_produto` - Unit and total amounts
* `cfop_produto` / `ncm_produto` - Tax classification codes
* `v_bc_produto` / `v_icms_produto` / `v_ipi_produto` - Tax base and tax amounts
Consumer receipts, incrementally synced by their last-change date.
**Key Fields:**
* `id_nfc` - Unique ID of the receipt
* `id_cliente` / `nome_cliente` - Customer of the receipt
* `valor_total_nota` - Total amount
* `valor_icms` - ICMS tax amount
* `nota_chave` - Access key of the NFC-e
* `url_qr_code` - QR code URL
* `status_pedido` - Status of the receipt
Service invoices, extracted as a full table.
**Key Fields:**
* `id_servico` - Unique ID of the service invoice
* `id_cliente` / `nome_cliente` - Customer of the invoice
* `desc_servicos` - Description of the service
* `valor_total_servicos` / `valor_total_nota` - Service and total amounts
* `valor_imposto` - Tax amount
* `nota_numero_nfse` - Number of the NFS-e
* `status_pedido` - Status of the invoice
* `lista_servico` - Economic activity of the service (JSON)
Service orders, incrementally synced by their last-change date.
**Key Fields:**
* `id_ordem` - Unique ID of the service order
* `id_cliente` / `nome_cliente` - Customer of the order
* `id_tecnico` / `nome_tecnico` - Technician assigned
* `valor_total_servicos` / `valor_total_pecas` / `valor_total_os` - Services, parts and total amounts
* `data_pedido` / `data_realizacao` - Order and execution dates
* `equipamento_ordem` / `problema_ordem` / `laudo_ordem` - Equipment, problem and report details
* `status_pedido` - Status of the service order
Service list (economic activities), extracted as a full table.
**Key Fields:**
* `id_lista` - Unique ID of the service
* `codigo` - Service code
* `descricao` - Description of the service
* `imposto_nacional` / `imposto_municipal` - Tax rates
Purchase orders, incrementally synced by their last-change date.
**Key Fields:**
* `id_ordem` - Unique ID of the purchase order
* `id_cliente` / `nome_cliente` - Supplier of the order
* `valor_total_produtos` / `valor_total_nota` - Product and total amounts
* `data_pedido` - Date of the purchase order
* `status_pedido` - Status of the purchase order
* `entrada_emitida` - Whether a goods receipt was issued
Goods receipts, incrementally synced by their last-change date.
**Key Fields:**
* `id_entrada` - Unique ID of the goods receipt
* `id_cliente` / `nome_cliente` - Supplier of the receipt
* `valor_total_produtos` / `valor_total_nota` - Product and total amounts
* `nota_numero` / `nota_chave` - Supplier invoice number and access key
* `data_pedido` - Date of the receipt
* `status_pedido` - Status of the receipt
Expenses, incrementally synced by their last-change date.
**Key Fields:**
* `id_conta_pag` - Unique ID of the payable
* `nome_conta` - Name of the payable
* `id_fornecedor` / `nome_fornecedor` - Supplier of the payable
* `categoria_pag` / `centro_custos_pag` - Finance category and cost center
* `vencimento_pag` - Due date
* `valor_pag` / `valor_pago` - Amount and amount paid
* `liquidado_pag` - Whether the payable is settled
* `data_pagamento` - Payment date
* `parciais` - Partial payments (JSON)
Income entries, incrementally synced by their last-change date.
**Key Fields:**
* `id_conta_rec` - Unique ID of the receivable
* `nome_conta` - Name of the receivable
* `id_cliente` / `nome_cliente` - Customer of the receivable
* `categoria_rec` / `centro_custos_rec` - Finance category and cost center
* `vencimento_rec` - Due date
* `valor_rec` / `valor_pago` - Amount and amount received
* `liquidado_rec` - Whether the receivable is settled
* `link_boleto` / `brcode` - Boleto URL and Pix BR Code
Bank statement (cash-flow) entries, incrementally synced by their last-change date.
**Key Fields:**
* `id_fluxo` - Unique ID of the entry
* `id_banco` / `nome_conta` - Bank account of the entry
* `data_fluxo` - Date of the entry
* `valor_fluxo` - Amount of the entry
* `tipo_fluxo` - Type of the entry (income or expense)
* `categoria_fluxo` / `centro_custos_fluxo` - Finance category and cost center
Bank account registrations, incrementally synced by their last-change date.
**Key Fields:**
* `id_banco_cad` - Unique ID of the bank account
* `nome_banco_cad` - Name of the account
* `numero_banco` - Bank number (e.g. 001 = Banco do Brasil, 341 = Itaú)
* `agencia_banco` / `conta_banco` - Branch and account numbers
* `saldo_atual` - Current balance
* `status_banco` - Status of the account
Cost centers, incrementally synced by their last-change date.
**Key Fields:**
* `id_centro_custos` - Unique ID of the cost center
* `desc_centro_custos` - Name of the cost center
* `status_centro_custos` - Status of the cost center
Finance categories, extracted as a full table.
**Key Fields:**
* `id_categoria` - Unique ID of the category
* `tipo_categoria` - Type of the category (income or expense)
* `desc_categoria` - Description of the category
* `grupo_financeiro` - Finance group
* `visivel_dre` - Whether the category is visible in the DRE (income statement)
## What can you do with VHSYS data?
* **Sales analytics**: track orders, POS sales, quotes conversion and salesperson performance across time.
* **Revenue and tax reporting**: combine NF-e, NFC-e and NFS-e invoices with their line items for detailed revenue and tax analysis.
* **Cash-flow management**: monitor accounts payable, accounts receivable and bank statements to understand your financial position.
* **Inventory and purchasing**: cross product stock levels with purchase orders and goods receipts to optimize replenishment.