Vhsys ERP connector: sync sales, invoices, and financial data into your data warehouse
Sync Vhsys ERP sales, invoices, customers, products, and financial data to BigQuery, Redshift, or PostgreSQL with Erathos.
Vhsys ERP connector: sync sales, invoices, and financial data into your data warehouse
The Erathos connector for Vhsys syncs orders, invoices, customers, products, service orders, and financial data from the Vhsys ERP straight into your data warehouse. BigQuery, Redshift, PostgreSQL, and more, with zero pipeline code to write or maintain.
Vhsys is the ERP used by over a million Brazilian micro and small businesses to run sales, tax invoices (NF-e, NFC-e, NFS-e), inventory, point of sale, and financial management. It exposes an authenticated REST API v2 that, in theory, makes a custom extraction possible. In practice, that means building and maintaining an ETL pipeline to handle dozens of endpoints, incremental cursors spread across different timestamp fields, parent-child entity structures, and Portuguese-language tax fields, work most data teams discover too late they cannot sustain. The Erathos connector solves this integration as a managed service, without requiring your team to write or maintain that code.
Every data team supporting a business that runs on Vhsys reaches the same bottleneck: orders, invoices, and receivables live inside the ERP, the rest of the analytics stack lives in the warehouse, and joining the two becomes an engineering project nobody planned for. What starts as a Python script on a cron job turns, three months later, into a pipeline nobody understands, that fails silently, and that no engineer wants to inherit.
The problem with hand-built Vhsys pipelines
The Vhsys API v2 is authenticated with an access token and a secret access token sent on every request, and its read endpoints return large document sets: sales orders with line items, installments, and status histories; invoices with dozens of tax fields; customers with vehicle and price-list details. The surface is simple enough to convince any engineer to build an integration in an afternoon. The real cost shows up later, and it is predictable.
Incremental cursors that differ per entity. Every updatable endpoint in Vhsys carries its own modification timestamp: data_mod_cliente for customers, data_mod_pedido for orders and invoices, data_mod_produto for products, data_mod_rec and data_mod_pag for receivables and payables. Get one cursor wrong and the pipeline stops picking up changed records without raising any error. It keeps running green with stale data.
Parent-child structures that break silently. Invoices, orders, service orders, purchase orders, quotes, and counter sales are all parents of line-item, installment, and status tables. A hand-built pipeline that reprocesses a parent without its children, or that loses the linkage key during a rewrite, leaves the warehouse with orphaned items that only surface when revenue by product does not add up to revenue by order.
Tax fields that evolve. Vhsys sits at the center of Brazilian tax compliance, with fields like valor_baseICMS, valor_ST, cfop, ncm, beneficio_fiscal, and a wave of monofásico ICMS fields that keep growing as tax reform progresses. When Vhsys adds or renames a field, your downstream dbt models either fail in production or keep running over a missing column with a coalesce, and the inconsistency reaches the dashboard before it reaches your monitoring.
Backfills that never happen. Counter sales and orders change status after the fact, invoices get cancelled, receivables get liquidated late. Capturing that history requires a reprocessing strategy most homegrown pipelines do not have, so the warehouse slowly diverges from the ERP and nobody knows since when.
Observability that does not exist. A 200 OK on the HTTP call does not mean the data arrived complete. Without record counts per endpoint per run, without comparison against the previous window, without volume-drop alerts, you are flying blind. The pipeline that ran successfully may have synced half the orders because one API token expired mid-extraction.
The worst case is not the pipeline that breaks and sends an alert. It is the pipeline that executes successfully and delivers wrong data, and the DRE and sales dashboards are already calculated on an incomplete base.
What you can do once Vhsys data reaches your warehouse
Before detailing the connector, it is worth documenting what you actually gain when orders, invoices, customers, and financial records leave the ERP and land modeled next to the rest of your stack.
A complete DRE and cash flow picture
With contas_pagar, contas_receber, extratos, saldo_bancos, and categorias_financeiras in the warehouse, you build your own managerial income statement and cash flow, with the dimensionality the ERP's built-in reports do not offer: by cost center, by seller, by financial category, by period, or any combination. The visivel_dre flag on financial categories and the full category hierarchy make it possible to reproduce and audit the ERP's DRE while adding custom views.
Sales performance by channel, seller, and product
Vhsys records sales through multiple channels: pedidos (orders), vendas_balcao (point of sale), orcamentos (quotes), and ordens_servico (service orders). Once all of them are in the warehouse joined by produto and vendedores, you measure revenue per channel, conversion from quote to order, seller commission against the comissao_regra and comissao_usuario fields, and margin per product line using cost fields recorded at the time of sale. This cross-channel view is only possible when every sales surface lands in the same database.
Inventory turnover and purchasing planning
With produtos, produtos_estoque, entradas_mercadoria, and ordens_compra synced continuously, you can calculate turnover by warehouse, detect slow-moving stock, compare purchase lead times against prazo_entrega, and build reorder models on top of actual sales velocity instead of gut feeling. The ERP shows current stock; the warehouse lets you model the history of how that stock moved.
Customer 360 joined with your CRM and support stack
The clientes table carries registration, tax, credit limit, and seller assignment for every customer, with vehicles attached via clientes_veiculos. Crossed with your CRM, e-commerce platform, or support tool on a shared business key, you answer: which ERP customers opened support tickets, which accounts with high credit limits stopped buying, how purchasing frequency moved after a campaign. Only possible with ERP and CRM data in the same warehouse.
Tax audit trail over time
notas_fiscais, notas_consumidor, notas_servico, their respective inutilizadas and cartas_correcao tables, plus the status history of every document, give you a historical fiscal trail that point queries against the API do not deliver. When an auditor or accountant asks why a series of invoices was cancelled or when a carta de correção was issued, the warehouse has the answer with dates, users, and reasons, year over year.
Service operation metrics for repair shops and service businesses
For segments that run on service orders, ordens_servico with its produtos, servicos, parcelas, and status children records technician, vehicle, labor hours, parts, and each status transition with timestamps. In the warehouse, you measure turnaround time per service type, rework rates, parts rejection via id_motivo_rejeicao, and technician productivity, none of which the ERP's standard reports expose at record granularity.
What's available in the connector
The Vhsys connector delivers dozens of endpoints ready to be materialized in your destination warehouse:
Endpoint | What it contains |
|---|---|
clientes | Customer master records with tax IDs, address, contact, credit limit, price list, seller assignment, and freight terms |
clientes_detalhe | Extended customer details including registration category and full tax registration fields |
clientes_veiculos | Vehicles registered per customer: plate, renavam, brand, model, fuel, year, mileage, and chassis |
categorias | Product categories with subcategories |
categorias_clientes | Customer categories used for segmentation |
categorias_financeiras | Financial categories with DRE visibility flag, financial group, and parent category |
centros_custo | Cost centers used across financial and sales records |
subcategorias | Product subcategories linked to parent categories |
produtos | Product catalog with pricing, cost, tax fields (NCM, CEST, ICMS, IPI), variations, kits, and images |
produtos_estoque | Stock movements per product, warehouse, and lot with quantities and values |
pedidos | Sales orders with totals, taxes, freight, payment terms, transport, and status |
pedidos_produtos | Line items of each sales order with quantities, prices, discounts, and warehouse allocation |
pedidos_parcelas | Installment records for each sales order |
pedidos_status | Status history of each order with timestamps and users |
orcamentos | Quotes with validity, delivery terms, and conversion flags |
orcamentos_produtos | Line items of each quote |
orcamentos_parcelas | Installment records for each quote |
orcamentos_status | Status history of each quote |
vendas_balcao | Point-of-sale (counter) sales with payment type, change, and PDV metadata |
vendas_balcao_produtos | Line items of each counter sale, including exchange quantities |
vendas_balcao_parcelas | Payment records of each counter sale, linked to receivables |
vendas_balcao_status | Status history of each counter sale |
notas_fiscais | NF-e electronic invoices with full tax breakdown, authorization and cancellation metadata |
notas_fiscais_produtos | Line items of each NF-e with item-level tax fields and lot data |
notas_fiscais_parcelas | Installments of each NF-e |
notas_fiscais_status | Status history of each NF-e |
notas_fiscais_cartas_correcao | Correction letters (CC-e) issued per invoice, with sequence, protocol, and content |
notas_fiscais_inutilizadas | Records of unused invoice number ranges, with reason and protocol |
notas_consumidor | NFC-e consumer invoices with sales tax breakdown and cancellation metadata |
notas_consumidor_produtos | Line items of each NFC-e with item-level tax fields |
notas_consumidor_parcelas | Installments of each NFC-e |
notas_consumidor_status | Status history of each NFC-e |
notas_consumidor_inutilizadas | Records of unused NFC-e number ranges |
notas_servico | NFS-e service invoices with service list codes, tax withholding, and municipal tax breakdown |
lista_servicos | Service list reference codes with national, international, and municipal tax rates |
ordens_compra | Purchase orders with supplier, totals, and delivery terms |
ordens_compra_produtos | Line items of each purchase order |
ordens_compra_parcelas | Installments of each purchase order |
ordens_compra_status | Status history of each purchase order |
ordens_servico | Service orders with technician, equipment, warranty, labor, parts, and payment totals |
ordens_servico_produtos | Parts used in each service order, with rejection reasons |
ordens_servico_servicos | Services executed in each order with hours, rates, and assigned technicians |
ordens_servico_parcelas | Installments of each service order |
ordens_servico_status | Status history of each service order |
entradas_mercadoria | Goods receipt entries with totals, taxes, and invoice references |
entradas_produtos | Line items of each goods receipt with lot and warehouse allocation |
entradas_parcelas | Installments of each goods receipt |
entradas_status | Status history of each goods receipt |
contas_pagar | Accounts payable with supplier, due dates, amounts, payments, and Open Finance references |
contas_receber | Accounts receivable with customer, due dates, payments, boleto and Pix QR code references |
extratos | Bank statement entries with account, category, cost center, and payment method |
saldo_bancos | Bank account balances with inflow and outflow totals |
contas_bancarias | Bank account configuration with boleto parameters, wallets, and integration flags |
transportadoras | Carriers with tax IDs, addresses, and contact details |
vendedores | Salespeople with commission rules, bank details, and status |
autoshop_dados_veiculos | Vehicle reference data: fuels, colors, brands, models, and types |
webhooks | Webhook configurations registered in the Vhsys account |
Most core entities sync incrementally, using each entity's own modification timestamp as cursor: clientes, produtos, pedidos, orcamentos, ordens_compra, ordens_servico, vendas_balcao, notas_fiscais, notas_consumidor, contas_pagar, contas_receber, extratos, saldo_bancos, and the remaining configuration tables. Line-item, installment, and status children sync in full refresh, which is the right behavior for records that only exist attached to a parent. Entity relationships are preserved in the destination: orders as parents of items, installments, and statuses; products as parents of stock records and line items across every sales surface; customers as parents of details and vehicles.
How to authenticate
Authentication requires two fields:
- Access token: your Vhsys API access token, sent in the access-token header of every request
- Secret access token: your Vhsys API secret access token, sent in the secret-access-token header of every request
- Where to find them: log in to your Vhsys account and go to Configurações → API (Settings → API). There you will find the access token and the secret access token for the API v2 endpoints. Copy both values and paste them into the corresponding fields on the Erathos platform
Click Save and close to complete the setup. The full process, step by step, is documented at https://docs.erathos.com/connectors/apis/vhsys.
Why outsource ingestion to Erathos
The premise of the connector is direct: the engineering effort of maintaining ingestion should not be your data team's responsibility. Cursor management, parent-child consistency, schema evolution, retry with backoff, failure alerts, volume-drop alerts, backfill. All of it is the responsibility of whoever operates the ingestion platform. With the connector configured, the platform delivers:
End-to-end visibility into every run
Extraction time per endpoint, record counts per window, which windows were processed, where retries happened. When a metric moves on a dashboard and a team opens a ticket, you have the full trail to find the root cause.
Alerts configured out of the box
Run failures, volume drops per endpoint, and delayed windows are detected and routed through the alerting integrations your team already uses, like Slack and email. You do not write that code.
Reprocessing as a supported operation
When you need to reprocess a window, for example to pick up cancelled invoices after changing a model's logic or to correct a period affected by a token issue, that is a platform operation, not an improvised DELETE + INSERT sequence in the warehouse.
Correct cursors, parent-child consistency, schema evolution handling, and backfill are the platform's responsibility. Your data team focuses on the model, not the plumbing.
Available pipelines
The Vhsys connector is available with the following destinations:
- Vhsys → Azure SQL Server: https://www.erathos.com/pipelines/vhsys-azure-sql-server
- Vhsys → Azure Synapse: https://www.erathos.com/pipelines/vhsys-azure-synapse
- Vhsys → BigQuery: https://www.erathos.com/pipelines/vhsys-bigquery
- Vhsys → ClickHouse: https://www.erathos.com/pipelines/vhsys-clickhouse
- Vhsys → Databricks: https://www.erathos.com/pipelines/vhsys-databricks
- Vhsys → PostgreSQL: https://www.erathos.com/pipelines/vhsys-postgresql
- Vhsys → Redshift: https://www.erathos.com/pipelines/vhsys-redshift
- Vhsys → S3 Iceberg: https://www.erathos.com/pipelines/vhsys-amazon-s3
- Vhsys → Snowflake: https://www.erathos.com/pipelines/vhsys-snowflake
- Vhsys → Supabase: https://www.erathos.com/pipelines/vhsys-supabase
Get started
Create your Erathos account at https://app.erathos.com/signup?slug=blog&button=cta&utm_campaign=vhsys_release and connect Vhsys to your warehouse in minutes. With your access token and secret access token, your first data lands at the destination with zero pipeline code to write, maintain, or monitor.
Sales, invoicing, and financial data generated every day shouldn't stay locked inside an ERP, disconnected from the rest of your analytics model. Or worse: stuck in a homegrown pipeline that will keep costing your team's attention every month, forever.
See the connector's full documentation at https://docs.erathos.com/connectors/apis/vhsys.