Conector Vhsys ERP: sincronize vendas, notas fiscais e dados financeiros no seu data warehouse
Sincronize vendas, notas fiscais, clientes, produtos e dados financeiros do Vhsys ERP com BigQuery, Redshift ou PostgreSQL usando a Erathos.
Conector Vhsys ERP: sincronize vendas, notas fiscais e dados financeiros no seu data warehouse
O conector Erathos para Vhsys sincroniza pedidos, notas fiscais, clientes, produtos, ordens de serviço e dados financeiros do ERP Vhsys direto para o seu data warehouse. BigQuery, Redshift, PostgreSQL e mais, sem nenhum código de pipeline para escrever ou manter.
O Vhsys é o ERP usado por mais de um milhão de micro e pequenas empresas brasileiras para gerenciar vendas, notas fiscais (NF-e, NFC-e, NFS-e), estoque, ponto de venda e gestão financeira. Ele expõe uma API REST v2 autenticada que, em teoria, torna possível uma extração customizada. Na prática, isso significa construir e manter um pipeline de ETL para lidar com dezenas de endpoints, cursores incrementais espalhados por diferentes campos de timestamp, estruturas de entidades pai-filho e campos fiscais em português, um trabalho que a maioria dos times de dados descobre tarde demais que não consegue sustentar. O conector Erathos resolve essa integração como um serviço gerenciado, sem exigir que seu time escreva ou mantenha esse código.
Todo time de dados que dá suporte a um negócio que roda no Vhsys chega ao mesmo gargalo: pedidos, notas fiscais e recebíveis vivem dentro do ERP, o restante do stack de analytics vive no warehouse, e unir os dois se torna um projeto de engenharia que ninguém planejou. O que começa como um script Python em um cron job se transforma, três meses depois, em um pipeline que ninguém entende, que falha silenciosamente e que nenhum engenheiro quer herdar.
O problema de pipelines Vhsys feitos à mão
A API v2 do Vhsys é autenticada com um access token e um secret access token enviados em toda requisição, e seus endpoints de leitura retornam conjuntos grandes de documentos: pedidos de venda com itens, parcelas e histórico de status; notas fiscais com dezenas de campos fiscais; clientes com detalhes de veículos e tabela de preços. A superfície é simples o suficiente para convencer qualquer engenheiro a construir uma integração em uma tarde. O custo real aparece depois, e é previsível.
Cursores incrementais que diferem por entidade. Todo endpoint atualizável no Vhsys carrega seu próprio timestamp de modificação: data_mod_cliente para clientes, data_mod_pedido para pedidos e notas fiscais, data_mod_produto para produtos, data_mod_rec e data_mod_pag para contas a receber e a pagar. Errar um cursor e o pipeline para de capturar registros alterados sem levantar nenhum erro. Ele continua rodando verde com dados desatualizados.
Estruturas pai-filho que quebram silenciosamente. Notas fiscais, pedidos, ordens de serviço, ordens de compra, orçamentos e vendas balcão são todos pais de tabelas de itens, parcelas e status. Um pipeline feito à mão que reprocessa um pai sem seus filhos, ou que perde a chave de ligação durante uma reescrita, deixa o warehouse com itens órfãos que só aparecem quando a receita por produto não bate com a receita por pedido.
Campos fiscais que evoluem. O Vhsys está no centro da conformidade tributária brasileira, com campos como valor_baseICMS, valor_ST, cfop, ncm, beneficio_fiscal e uma onda de campos de ICMS monofásico que continuam crescendo conforme a reforma tributária avança. Quando o Vhsys adiciona ou renomeia um campo, seus modelos dbt downstream ou falham em produção ou continuam rodando sobre uma coluna ausente com um coalesce, e a inconsistência chega ao dashboard antes de chegar ao seu monitoramento.
Backfills que nunca acontecem. Vendas balcão e pedidos mudam de status depois do fato, notas fiscais são canceladas, recebíveis são liquidados com atraso. Capturar esse histórico exige uma estratégia de reprocessamento que a maioria dos pipelines caseiros não tem, então o warehouse diverge lentamente do ERP e ninguém sabe desde quando.
Observabilidade que não existe. Um 200 OK na chamada HTTP não significa que os dados chegaram completos. Sem contagem de registros por endpoint por execução, sem comparação com a janela anterior, sem alertas de queda de volume, você está voando às cegas. O pipeline que rodou com sucesso pode ter sincronizado metade dos pedidos porque um token da API expirou no meio da extração.
O pior caso não é o pipeline que quebra e dispara um alerta. É o pipeline que executa com sucesso e entrega dados errados, e o DRE e os dashboards de vendas já foram calculados sobre uma base incompleta.
O que você pode fazer quando os dados do Vhsys chegam ao seu warehouse
Antes de detalhar o conector, vale documentar o que você realmente ganha quando pedidos, notas fiscais, clientes e registros financeiros saem do ERP e chegam modelados junto ao restante do seu stack.
Uma visão completa de DRE e fluxo de caixa
Com contas_pagar, contas_receber, extratos, saldo_bancos e categorias_financeiras no warehouse, você constrói seu próprio DRE gerencial e fluxo de caixa, com a dimensionalidade que os relatórios nativos do ERP não oferecem: por centro de custo, por vendedor, por categoria financeira, por período, ou qualquer combinação. A flag visivel_dre nas categorias financeiras e a hierarquia completa de categorias tornam possível reproduzir e auditar o DRE do ERP enquanto você adiciona visões customizadas.
Performance de vendas por canal, vendedor e produto
O Vhsys registra vendas por múltiplos canais: pedidos, vendas_balcao (ponto de venda), orcamentos e ordens_servico. Quando todos estão no warehouse, ligados por produto e vendedores, você mede receita por canal, conversão de orçamento em pedido, comissão de vendedor contra os campos comissao_regra e comissao_usuario, e margem por linha de produto usando os campos de custo registrados no momento da venda. Essa visão entre canais só é possível quando toda superfície de venda aterrissa no mesmo banco de dados.
Giro de estoque e planejamento de compras
Com produtos, produtos_estoque, entradas_mercadoria e ordens_compra sincronizados continuamente, você pode calcular o giro por depósito, detectar estoque parado, comparar lead times de compra contra prazo_entrega e construir modelos de ressuprimento sobre a velocidade real de vendas em vez de feeling. O ERP mostra o estoque atual; o warehouse permite modelar o histórico de como esse estoque se moveu.
Customer 360 integrado ao seu CRM e stack de suporte
A tabela clientes carrega dados cadastrais, fiscais, limite de crédito e atribuição de vendedor de cada cliente, com veículos vinculados via clientes_veiculos. Cruzada com seu CRM, plataforma de e-commerce ou ferramenta de suporte em uma chave de negócio compartilhada, você responde: quais clientes do ERP abriram tickets de suporte, quais contas com limites de crédito altos pararam de comprar, como a frequência de compra se moveu após uma campanha. Só é possível com dados do ERP e do CRM no mesmo warehouse.
Trilha fiscal histórica ao longo do tempo
notas_fiscais, notas_consumidor, notas_servico, suas respectivas tabelas de inutilizadas e cartas_correcao, mais o histórico de status de cada documento, fornecem uma trilha fiscal histórica que queries pontuais contra a API não entregam. Quando um auditor ou contador pergunta por que uma série de notas foi cancelada ou quando uma carta de correção foi emitida, o warehouse tem a resposta com datas, usuários e motivos, ano após ano.
Métricas de operação de serviço para oficinas e prestadores de serviço
Para segmentos que rodam em ordens de serviço, ordens_servico com seus registros filhos de produtos, servicos, parcelas e status registra técnico, veículo, horas de mão de obra, peças e cada transição de status com timestamps. No warehouse, você mede tempo de execução por tipo de serviço, taxas de retrabalho, rejeição de peças via id_motivo_rejeicao e produtividade por técnico, nada do que os relatórios padrão do ERP expõem em granularidade de registro.
O que está disponível no conector
O conector Vhsys entrega dezenas de endpoints prontos para serem materializados no seu warehouse de destino:
Endpoint | O que contém |
|---|---|
clientes | Registros mestres de clientes com CPF/CNPJ, endereço, contato, limite de crédito, tabela de preços, vendedor atribuído e condições de frete |
clientes_detalhe | Detalhes estendidos do cliente incluindo categoria de cadastro e campos completos de registro fiscal |
clientes_veiculos | Veículos registrados por cliente: placa, renavam, marca, modelo, combustível, ano, quilometragem e chassi |
categorias | Categorias de produtos com subcategorias |
categorias_clientes | Categorias de clientes usadas para segmentação |
categorias_financeiras | Categorias financeiras com flag de visibilidade no DRE, grupo financeiro e categoria pai |
centros_custo | Centros de custo usados nos registros financeiros e de vendas |
subcategorias | Subcategorias de produtos vinculadas às categorias pai |
produtos | Catálogo de produtos com preços, custo, campos fiscais (NCM, CEST, ICMS, IPI), variações, kits e imagens |
produtos_estoque | Movimentações de estoque por produto, depósito e lote com quantidades e valores |
pedidos | Pedidos de venda com totais, impostos, frete, condições de pagamento, transporte e status |
pedidos_produtos | Itens de cada pedido de venda com quantidades, preços, descontos e alocação de depósito |
pedidos_parcelas | Registros de parcelas de cada pedido de venda |
pedidos_status | Histórico de status de cada pedido com timestamps e usuários |
orcamentos | Orçamentos com validade, condições de entrega e flags de conversão |
orcamentos_produtos | Itens de cada orçamento |
orcamentos_parcelas | Registros de parcelas de cada orçamento |
orcamentos_status | Histórico de status de cada orçamento |
vendas_balcao | Vendas balcão (ponto de venda) com tipo de pagamento, troco e metadados do PDV |
vendas_balcao_produtos | Itens de cada venda balcão, incluindo quantidades de troca |
vendas_balcao_parcelas | Registros de pagamento de cada venda balcão, vinculados ao contas a receber |
vendas_balcao_status | Histórico de status de cada venda balcão |
notas_fiscais | Notas fiscais eletrônicas NF-e com detalhamento fiscal completo, metadados de autorização e cancelamento |
notas_fiscais_produtos | Itens de cada NF-e com campos fiscais no nível do item e dados de lote |
notas_fiscais_parcelas | Parcelas de cada NF-e |
notas_fiscais_status | Histórico de status de cada NF-e |
notas_fiscais_cartas_correcao | Cartas de correção (CC-e) emitidas por nota, com sequência, protocolo e conteúdo |
notas_fiscais_inutilizadas | Registros de faixas de números de notas inutilizadas, com motivo e protocolo |
notas_consumidor | Notas do consumidor NFC-e com detalhamento de impostos sobre vendas e metadados de cancelamento |
notas_consumidor_produtos | Itens de cada NFC-e com campos fiscais no nível do item |
notas_consumidor_parcelas | Parcelas de cada NFC-e |
notas_consumidor_status | Histórico de status de cada NFC-e |
notas_consumidor_inutilizadas | Registros de faixas de números de NFC-e inutilizadas |
notas_servico | Notas fiscais de serviço NFS-e com códigos da lista de serviços, retenção de impostos e detalhamento tributário municipal |
lista_servicos | Códigos de referência da lista de serviços com alíquotas de imposto nacional, internacional e municipal |
ordens_compra | Ordens de compra com fornecedor, totais e condições de entrega |
ordens_compra_produtos | Itens de cada ordem de compra |
ordens_compra_parcelas | Parcelas de cada ordem de compra |
ordens_compra_status | Histórico de status de cada ordem de compra |
ordens_servico | Ordens de serviço com técnico, equipamento, garantia, mão de obra, peças e totais de pagamento |
ordens_servico_produtos | Peças usadas em cada ordem de serviço, com motivos de rejeição |
ordens_servico_servicos | Serviços executados em cada ordem com horas, valores e técnicos atribuídos |
ordens_servico_parcelas | Parcelas de cada ordem de serviço |
ordens_servico_status | Histórico de status de cada ordem de serviço |
entradas_mercadoria | Entradas de mercadoria com totais, impostos e referências de notas fiscais |
entradas_produtos | Itens de cada entrada de mercadoria com lote e alocação de depósito |
entradas_parcelas | Parcelas de cada entrada de mercadoria |
entradas_status | Histórico de status de cada entrada de mercadoria |
contas_pagar | Contas a pagar com fornecedor, vencimentos, valores, pagamentos e referências do Open Finance |
contas_receber | Contas a receber com cliente, vencimentos, pagamentos e referências de boleto e QR Code Pix |
extratos | Lançamentos de extrato bancário com conta, categoria, centro de custo e método de pagamento |
saldo_bancos | Saldos de contas bancárias com totais de entradas e saídas |
contas_bancarias | Configuração de contas bancárias com parâmetros de boleto, carteiras e flags de integração |
transportadoras | Transportadoras com CNPJ/CPF, endereços e dados de contato |
vendedores | Vendedores com regras de comissão, dados bancários e status |
autoshop_dados_veiculos | Dados de referência de veículos: combustíveis, cores, marcas, modelos e tipos |
webhooks | Configurações de webhook registradas na conta Vhsys |
A maioria das entidades centrais sincroniza incrementalmente, usando o timestamp de modificação de cada entidade como cursor: clientes, produtos, pedidos, orcamentos, ordens_compra, ordens_servico, vendas_balcao, notas_fiscais, notas_consumidor, contas_pagar, contas_receber, extratos, saldo_bancos e as demais tabelas de configuração. Os filhos de itens, parcelas e status sincronizam em full refresh, que é o comportamento correto para registros que só existem vinculados a um pai. Os relacionamentos entre entidades são preservados no destino: pedidos como pais de itens, parcelas e status; produtos como pais de registros de estoque e itens em toda superfície de venda; clientes como pais de detalhes e veículos.
Como fazer a autenticação
A autenticação exige dois campos:
- Access token: seu access token da API Vhsys, enviado no header access-token de toda requisição
- Secret access token: seu secret access token da API Vhsys, enviado no header secret-access-token de toda requisição
- Onde encontrá-los: faça login na sua conta Vhsys e vá para Configurações → API. Lá você encontrará o access token e o secret access token dos endpoints da API v2. Copie os dois valores e cole-os nos campos correspondentes na plataforma Erathos
Clique em Salvar e fechar para concluir a configuração. O processo completo, passo a passo, está documentado em https://docs.erathos.com/connectors/apis/vhsys.
Por que terceirizar a ingestão para a Erathos
A premissa do conector é direta: o esforço de engenharia de manter a ingestão não deveria ser responsabilidade do seu time de dados. Gestão de cursores, consistência pai-filho, evolução de schema, retry com backoff, alertas de falha, alertas de queda de volume, backfill. Tudo isso é responsabilidade de quem opera a plataforma de ingestão. Com o conector configurado, a plataforma entrega:
Visibilidade de ponta a ponta de cada execução
Tempo de extração por endpoint, contagem de registros por janela, quais janelas foram processadas, onde houve retries. Quando uma métrica se move em um dashboard e um time abre um ticket, você tem a trilha completa para encontrar a causa raiz.
Alertas configurados de fábrica
Falhas de execução, quedas de volume por endpoint e janelas atrasadas são detectadas e roteadas pelas integrações de alerta que seu time já usa, como Slack e e-mail. Você não escreve esse código.
Reprocessamento como operação suportada
Quando você precisa reprocessar uma janela, por exemplo para capturar notas canceladas após mudar a lógica de um modelo ou para corrigir um período afetado por um problema de token, isso é uma operação da plataforma, não uma sequência improvisada de DELETE + INSERT no warehouse.
Cursores corretos, consistência pai-filho, tratamento de evolução de schema e backfill são responsabilidade da plataforma. Seu time de dados foca no modelo, não na encanação.
Pipelines disponíveis
O conector Vhsys está disponível com os seguintes destinos:
- 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
Comece agora
Crie sua conta Erathos em https://app.erathos.com/signup?slug=blog&button=cta&utm_campaign=vhsys_release e conecte o Vhsys ao seu warehouse em minutos. Com seu access token e secret access token, seus primeiros dados aterrissam no destino sem nenhum código de pipeline para escrever, manter ou monitorar.
Dados de vendas, faturamento e finanças gerados todos os dias não deveriam ficar presos dentro de um ERP, desconectados do restante do seu modelo de analytics. Ou pior: presos em um pipeline caseiro que vai continuar custando a atenção do seu time todo mês, para sempre.
Veja a documentação completa do conector em https://docs.erathos.com/connectors/apis/vhsys.