Integração Nativa com ERP SAP Business One

A integração nativa com SAP Business One foi desenvolvida para oferecer máxima compatibilidade e segurança, dividida em duas partes principais: um plugin leve instalado na infraestrutura do cliente e o consumo nativo pelo Vendelo. Esta solução mantém a arquitetura desacoplada e não interfere no desempenho do B1. Este guia é destinado a consultores de integração e técnicos responsáveis pela implementação.

Visão Geral da Arquitetura

O plugin de integração opera como um middleware robusto que estabelece comunicação bidirecional entre o Vendelo e o SAP Business One, utilizando uma arquitetura dupla que garante segurança máxima e desempenho otimizado:

  • Plugin Leve: Instalado no servidor de integração do cliente
  • Vendelo Nativo: Consome os dados através do plugin de forma segura
  • Envio de dados: O Vendelo transmite informações para o SAP B1 através da Service Layer (SL)
  • Recepção de dados: O SAP monitora modificações através da procedure SBO_TRANSACTION_NOTIFICATION
  • Tratamento de falhas: Sistema à prova de falhas que ignora erros silenciosamente, sem interromper o fluxo do B1
  • Consultas diretas: Queries SQL/HANA apenas onde a Service Layer não oferece suporte
  • Arquitetura Desacoplada: Não modifica estruturas originais do B1

Esta arquitetura permite que o Vendelo seja desinstalado ou desvinculado do B1 sem deixar qualquer resíduo na estrutura original do SAP.

Plugin Leve do Servidor

O plugin instalado no servidor de integração do cliente oferece as seguintes funcionalidades:

Principais Recursos

  • Consumo da Service Layer: Acessa a API do B1 sem exposição pública
  • Monitoramento de Eventos: Detecta automaticamente atualizações no B1
  • Consultas SQL Seguras: Permite consultas de leitura controladas
  • Relatórios Crystal Reports: Gera espelhos de notas e impressão de propostas
  • Controle de Acesso: Token de segurança para autenticação

Componentes do Plugin

Componente Função Tecnologia
API Controller Gerencia requisições HTTP ASP.NET Core
Database Client Conexão direta com B1 SQL Server / HANA
Service Layer Proxy Intermedia chamadas SL HTTP Client
Crystal Reports Helper Geração de relatórios Crystal Reports Engine

O plugin deve ser instalado em um servidor com acesso à rede do SAP Business One, mas não precisa estar no mesmo servidor do B1.

Consumo Nativo pelo Vendelo

O Vendelo consome os dados através do plugin utilizando exclusivamente a Service Layer oficial do SAP:

Fluxo de Integração

  1. Vendelo solicita dados ao plugin através de requisições criptografadas
  2. Plugin autentica a requisição e valida o token de acesso
  3. Plugin consulta a Service Layer ou executa consulta SQL conforme necessário
  4. Dados são retornados criptografados para o Vendelo
  5. Vendelo processa e armazena os dados em sua própria estrutura de nuvem

Tipos de Operações Suportadas

Operação Método Descrição
Consulta de Dados GET Leitura de registros via Service Layer
Criação de Registros POST Inclusão de novos documentos
Atualização de Dados PATCH Modificação de registros existentes
Consultas SQL Custom Query Relatórios e consultas específicas
Geração de PDFs Crystal Reports Relatórios e documentos impressos

Pré-requisitos do Sistema

Software Necessário

Componente Versão Observações Status
.NET Runtime / SDK 8.0 ou superior Download: dotnet-sdk-8.0.411-win-x64.exe ou superior — site oficial Microsoft Obrigatório
SAP Business One 10.0 ou superior Com Service Layer configurada e em execução Obrigatório
Windows Server 2016 ou superior Para execução como serviço Windows Obrigatório

Link direto para download do .NET 8 SDK:
https://dotnet.microsoft.com/pt-br/download/dotnet/8.0

Permissões de Banco de Dados

É necessário criar um usuário específico para integração com as seguintes características:

  • Acesso de leitura: Permissão somente leitura no banco SAP HANA ou SQL Server
  • Acesso de escrita: Permissão de escrita exclusivamente na tabela de usuário VDO_KEYS

O usuário de integração deve ter permissões mínimas necessárias, seguindo o princípio do menor privilégio para garantir segurança.

Configuração no SAP Business One

Criação da Tabela de Usuário

  1. Acesse o SAP Business One como administrador do sistema
  2. Navegue para Ferramentas → Definições → Definições Gerais → Campos e Tabelas de Usuário
  3. Clique em Gerenciar Tabelas de Usuário
  4. Configure a nova tabela com os seguintes parâmetros:
    • Nome da Tabela: VDO_KEYS
    • Descrição: Vendelo – Integração
    • Tipo: SEM OBJETO vinculado
    • Campos de usuário: Não criar campos adicionais
  5. Salve a configuração — o B1 criará automaticamente os campos Code e Name

A tabela VDO_KEYS utiliza apenas os campos nativos Code e Name criados automaticamente pelo SAP Business One, simplificando a configuração. Caso a tabela já exista de uma instalação anterior, limpe todos os seus registros antes de prosseguir.

Implementação da Procedure de Monitoramento

Após criar a tabela de usuário, implemente a procedure de monitoramento de transações:

  1. Conecte-se ao banco de dados SAP (HANA ou SQL Server)
  2. Execute o script de criação da procedure VDO_TRIAGE_EVENTS (SQL ou HANA, conforme ambiente)
  3. Configure a procedure SBO_TRANSACTION_NOTIFICATION para chamar a VDO_TRIAGE_EVENTS
  4. Teste a execução para verificar se não há erros

A procedure VDO_TRIAGE_EVENTS é à prova de falhas — erros são tratados silenciosamente para não interromper o fluxo normal do SAP Business One.

Instalação do Plugin

Download e Instalação do .NET 8

  1. Baixe o .NET 8 SDK pelo link disponível na seção de Pré-requisitos
  2. Execute o instalador como administrador
  3. Verifique a instalação através do comando: dotnet --version

Configuração como Serviço do Windows

  1. Extraia os arquivos do plugin para o diretório de instalação — recomendado: C:\vendelo\
  2. Edite o arquivo appsettings.json com as configurações do ambiente (token, banco de dados, Service Layer)
  3. Execute o arquivo setup.bat como administrador — ele gera o certificado SSL automaticamente e cria o serviço Windows “Vendelo – B1i”
  4. Verifique se o serviço foi criado no Gerenciador de Serviços do Windows
  5. Configure o serviço para inicialização automática
  6. Confirme que a porta 8787 (HTTPS) está aberta no firewall do cliente

O setup.bat executa internamente o script generate_certificate.ps1 (PowerShell) para criar o certificado autoassinado e, em seguida, registra o serviço com o comando sc.exe create "Vendelo - B1i" binPath= "C:\vendelo\b1i\Vendelo.B1i.exe".

Configuração dos Arquivos

Arquivo appsettings.json

Este arquivo contém as configurações principais do plugin de integração. Fica localizado no diretório de instalação (C:\vendelo\b1i\). A seção Logging, Host.CORS, AllowedHosts e UseWindowsService não devem ser editadas.

Seção: Kestrel (HTTPS e Certificado)

Parâmetro Descrição Exemplo / Padrão Status
Kestrel.Endpoints.Url Endereço e porta HTTPS de exposição do plugin https://*:8787 Obrigatório
Certificate.Path Caminho completo do arquivo de certificado SSL (.pfx) C:\vendelo\certificate\default.pfx Obrigatório
Certificate.Password Senha do arquivo de certificado .pfx XXXXX Obrigatório

Seção: B1Settings (Autenticação e Empresas)

Parâmetro Descrição Exemplo / Padrão Status
Token Token de autenticação compartilhado entre plugin e Vendelo. Deve ser idêntico ao configurado no B1iSettings.json vdo-abc123 Obrigatório
UseLogs Habilita geração de logs detalhados de operações. Útil para diagnóstico; desabilitar em produção para melhor performance false Opcional
DBProvider Tipo do banco de dados SAP. Valores aceitos: SQLSERVER, ODBC-HANA SQLSERVER Obrigatório
SysDBName Nome do banco de sistema. Exclusivo para ODBC-HANA SK1 Condicional
DBName Nome do banco de dados da empresa SAP SBODemoBR Obrigatório
DBHost Endereço IP ou nome do servidor de banco de dados 192.168.1.100 Obrigatório
DBPort Porta do banco de dados. Usar null para instância padrão do SQL Server; 30013 para HANA null (SQL) / 30013 (HANA) Opcional
DBUsername Usuário do banco de dados para conexão direta (leitura + escrita na VDO_KEYS) integration_user Obrigatório
DBPassword Senha do usuário de banco de dados ***** Obrigatório
SLLanguage Código do idioma da Service Layer. Para Português (Brasil): 29 29 Obrigatório
SLBaseUrl URL base da Service Layer do SAP Business One https://127.0.0.1:50000 Obrigatório
SLUserName Usuário da Service Layer. Recomendado usar o usuário dedicado B1i B1i Obrigatório
SLPassword Senha do usuário da Service Layer ***** Obrigatório

O arquivo suporta múltiplas empresas. Basta adicionar novos objetos dentro do array Companies, cada um com sua própria configuração de banco de dados e Service Layer.

A configuração de banco de dados (DBProvider, SysDBName, DBName, DBHost, DBPort, DBUsername, DBPassword) é para conexão direta ao banco (SQL/HANA). As configurações SL* são para comunicação via Service Layer. Ambas são necessárias e independentes.

Arquivo B1iSettings.json

Uso exclusivo da Vendelo — consultor SAP, ignorar. Este arquivo é configurado pelo time Vendelo no servidor de nuvem. Em ambientes Docker, deve ser criado como File Mount em /etc/vdo/B1iSettings.json e a variável de ambiente B1iConfigFileName=/etc/vdo/B1iSettings.json deve ser definida nos serviços gql e jobProxy.

Parâmetros de Conexão (por empresa)

Parâmetro Descrição Exemplo Status
CompanyId ID da empresa no Vendelo Obrigatório
Token Token compartilhado — deve ser idêntico ao configurado no appsettings.json vdo-***** Obrigatório
ServerType Tipo do servidor de banco. Valores: SQLSERVER, HANA SQLSERVER Obrigatório
DbName Nome do banco de dados da empresa SAP SBODemoBR Obrigatório
BaseUrl URL do plugin instalado no servidor do cliente (aponta para este servidor) https://IP:8787 Obrigatório
DefaulUserId ID do usuário padrão Vendelo criado no SAP para operações automáticas Obrigatório

Parâmetros de Comportamento (por empresa)

Parâmetro Descrição Padrão Impacto
ImportOnlySaleItems Quando true, importa apenas itens marcados como itens de venda no SAP true Performance / Catálogo
BlockAddKitItemAsNormalItem Impede que itens do tipo kit sejam adicionados como itens normais em pedidos false Vendas
ManageItemStatusOnlyInVendelo Quando true, o status de ativo/inativo dos itens é controlado exclusivamente pelo Vendelo, ignorando o status do SAP false Catálogo
EnableDocDataVersionControl Habilita controle de versão de documentos para auditoria de alterações false Auditoria
AddInvoicesForPaidOrders Quando true, gera automaticamente nota fiscal para pedidos com pagamento confirmado false Fiscal
IgnoreStock Quando true, nunca busca o saldo em estoque no SAP false Vendas / Estoque
GetStockOnlyFromPositions Quando true, consulta o saldo de estoque somente das posições (bins) configuradas false Estoque
IgnoreDealDocumentsFromBpId ID do parceiro de negócios cujos documentos fiscais devem ser ignorados (ex.: NF ao consumidor final). Aceita null para desabilitar null Fiscal
ShowTotalizedInvBalance Quando true, exibe o saldo de inventário de forma totalizada (soma de todos os depósitos) false Estoque
SetPrintedQuoteAsPreparing Quando true, altera automaticamente o status de um orçamento para “em preparo” ao ser impresso false Workflow
AddOnFiscalName Nome do add-on fiscal instalado no SAP utilizado para emissão de NF. Valores suportados: INVENT, SKILL. Usar null se não houver add-on null Fiscal

Parâmetros de Campos de Usuário (UDF)

Parâmetro Descrição Padrão Status
XPedFieldName Nome do campo UDF no SAP usado para armazenar o número de pedido externo (ex.: pedido do cliente) null Opcional
NItemPedFieldName Nome do campo UDF no SAP usado para armazenar o número do item dentro do pedido externo null Opcional

Parâmetros de Contas Contábeis

Parâmetro Descrição Padrão Status
DownPayAccount Conta contábil para lançamento de entradas/adiantamentos (down payment) null Opcional
PayRateDebitAccount Conta contábil de débito utilizada para lançamento de taxas de pagamento (ex.: taxa de cartão) null Opcional
PayRateCreditAccount Conta contábil de crédito utilizada para lançamento de taxas de pagamento null Opcional

Parâmetros de Queries Customizadas

Parâmetro Descrição Padrão Status
QueryToGetWarehouse Query SQL/HANA para retornar um depósito específico por item/documento. Substitui: {0}=DocObjectCode, {1}=BPL_IDAssignedToInvoice, {2}=CardCode, {3}=ShipToCode, {4}=ItemCode, {5}=Quantity. Deve retornar coluna ID null Opcional
QueryToGetItemBarCode Query SQL/HANA para retornar o código de barras de um item a partir do seu ItemCode. Substitui: {0}=ItemCode. Deve retornar coluna ID null Opcional

Exemplos de queries customizadas:
QueryToGetWarehouse: SELECT "U_TX_CodEANTrib" as "ID" FROM OITM WHERE "ItemCode" = '{4}';
QueryToGetItemBarCode: SELECT "U_BARCODE" as "ID" FROM OITM WHERE "ItemCode" = '{0}';

Configurações de Banco de Dados — Comparativo SQL Server vs HANA

Parâmetro SQL Server HANA / ODBC-HANA Status
DBProvider SQLSERVER HANA ou ODBC-HANA Obrigatório
SysDBName Não utilizado Obrigatório para ODBC-HANA (ex.: SK1) Condicional
DBPort null (instância padrão) 30013 ou 30015 Opcional
Criptografia TrustServerCertificate SSL/TLS Obrigatório

Configuração de Rede e Firewall

Configuração de Porta

  • Porta padrão: 8787 (HTTPS)
  • Protocolo: TCP
  • Direção: Entrada (Inbound)
  • Acesso: Restrito ao IP fixo fornecido pela Vendelo no momento da contratação

A porta 8787 é a padrão configurada no appsettings.json, mas pode ser alterada conforme preferência do provedor de cloud. Certifique-se de atualizar tanto o arquivo de configuração quanto as regras de firewall e o parâmetro BaseUrl no B1iSettings.json.

Regras de Firewall

  1. Abra o Windows Firewall com Segurança Avançada
  2. Crie uma nova regra de entrada (Inbound Rule)
  3. Configure para porta TCP 8787 (ou porta personalizada definida no appsettings.json)
  4. Restrinja o acesso ao IP fixo fornecido pela Vendelo
  5. Teste a conectividade externa

Vantagens da Arquitetura

Arquitetura Desacoplada

  • Sem Campos de Usuário: Não cria estruturas extras no SAP (exceto a tabela VDO_KEYS e a procedure de monitoramento, removíveis a qualquer momento)
  • Sem Dependências: Vendelo funciona independentemente do B1
  • Remoção Limpa: Desinstalação sem resíduos permanentes no ERP
  • Estrutura Original Preservada: B1 permanece intacto durante toda a operação

Performance e Infraestrutura

  • Estrutura Própria de Nuvem: Vendelo roda em infraestrutura independente
  • Sem Impacto no B1: Não afeta desempenho do ERP
  • Cache Inteligente: Otimização de consultas frequentes
  • Processamento Assíncrono: Operações não bloqueantes

Comparativo com Outras Integrações

Aspecto Vendelo Nativo Integrações “Homologadas”
Modificação do B1 Nenhuma estrutura permanente Campos de usuário, triggers, stored procedures
Impacto na Performance Zero Significativo (consultas diretas)
Processo de Homologação Não necessário Obrigatório devido às modificações
Manutenibilidade Alta Baixa (dependências estruturais)

Outras integrações que se dizem “homologadas” frequentemente fazem uma grande bagunça estrutural no SAP, criando campos de usuário, modificando tabelas e instalando componentes que ficam permanentemente no sistema.

Aspectos de Segurança

Proteção de Dados

  • Criptografia End-to-End: Todas as comunicações são criptografadas via HTTPS
  • Token de Autenticação: Acesso controlado por tokens seguros, compartilhados entre plugin e Vendelo
  • Sem Exposição Pública: Service Layer não fica acessível externamente
  • Logs de Auditoria: Registro completo de todas as operações (quando UseLogs: true)

Controle de Acesso

Recurso Método de Proteção Nível de Segurança
API Endpoints Token Bearer + HTTPS Alto
Banco de Dados Credenciais criptografadas + usuário com permissões mínimas Muito Alto
Service Layer Cookies de sessão seguros (usuário B1i dedicado) Alto
Arquivos de Configuração Proteção de dados do Windows + acesso restrito ao servidor Muito Alto
Certificado SSL Certificado autoassinado gerado no setup, protegido por senha no PFX Alto

Sistema de Monitoramento

Logs do Sistema

O plugin gera logs detalhados para monitoramento e debugging. Habilite com UseLogs: true no appsettings.json.

  • Localização: Diretório de instalação do plugin (C:\vendelo\b1i\)
  • Rotação: Diária com retenção de 30 dias
  • Níveis: Information, Warning, Error
  • Formato: JSON estruturado

Indicadores de Status

Status Significado Ação Recomendada
Conectado Integração funcionando normalmente Monitoramento de rotina
Desconectado Falha na comunicação Verificar conectividade e logs
Erro de autenticação Token inválido ou expirado Renovar token de acesso e sincronizar com B1iSettings.json
Erro de configuração Parâmetros incorretos Revisar appsettings.json e B1iSettings.json

Resolução de Problemas

Problemas Comuns

  • Erro de conexão SL: Verificar se a Service Layer está ativa e acessível na URL configurada em SLBaseUrl
  • Falha na procedure: Confirmar se VDO_TRIAGE_EVENTS está criada corretamente e sendo chamada pela SBO_TRANSACTION_NOTIFICATION
  • Timeout de conexão: Verificar configurações de rede e firewall; confirmar que a porta 8787 está liberada
  • Erro de certificado: Validar certificado SSL e configurações HTTPS; verificar senha no campo Certificate.Password
  • Tabela não encontrada: Confirmar criação da tabela VDO_KEYS no SAP; se já existia, limpar os registros antes de reconectar
  • Token inválido: Confirmar que o valor de Token no appsettings.json é idêntico ao Token no B1iSettings.json
  • Serviço não inicia: Verificar se o caminho C:\vendelo\b1i\Vendelo.B1i.exe existe e se o .NET 8 está corretamente instalado

Comandos de Diagnóstico

  • Verificar serviço: sc query "Vendelo - B1i"
  • Iniciar serviço: sc start "Vendelo - B1i"
  • Parar serviço: sc stop "Vendelo - B1i"
  • Status do .NET: dotnet --info
  • Versão do .NET: dotnet --version
  • Teste de porta local: telnet localhost 8787

Sempre verifique os logs do plugin antes de reportar problemas — eles contêm informações detalhadas sobre erros e status da integração. Habilite UseLogs: true temporariamente para obter mais detalhes.

Perguntas Frequentes

O plugin pode afetar o desempenho do SAP Business One?

Não. O plugin utiliza apenas consultas de leitura otimizadas e não interfere nas operações do B1. Além disso, pode ser instalado em um servidor separado do SAP.

É necessário criar campos de usuário no SAP para a integração funcionar?

Não. A arquitetura do Vendelo é completamente desacoplada. A única estrutura criada é a tabela VDO_KEYS (que usa apenas campos nativos do SAP) e a procedure de monitoramento VDO_TRIAGE_EVENTS, ambas removíveis sem deixar resíduos.

O que acontece se eu quiser remover o Vendelo do ambiente?

A remoção é completamente limpa. Basta parar e remover o serviço Windows “Vendelo – B1i”, excluir os registros da tabela VDO_KEYS e remover a chamada à VDO_TRIAGE_EVENTS na procedure SBO_TRANSACTION_NOTIFICATION. O B1 permanece inalterado.

A integração funciona tanto com SQL Server quanto com HANA?

Sim. Configure o parâmetro DBProvider no appsettings.json como SQLSERVER, HANA ou ODBC-HANA conforme seu ambiente. Para ODBC-HANA, o campo SysDBName também é obrigatório.

Como é garantida a segurança das comunicações?

Todas as comunicações utilizam criptografia HTTPS com certificado SSL, autenticação por token Bearer e a Service Layer nunca fica exposta publicamente. O acesso à porta 8787 é restrito ao IP fixo da Vendelo.

Por que outras integrações precisam de homologação e o Vendelo não?

Outras integrações modificam a estrutura do SAP criando campos de usuário, triggers e procedures permanentes. O Vendelo utiliza apenas a API oficial (Service Layer) sem modificações estruturais, tornando a homologação desnecessária.

É possível gerar relatórios Crystal Reports através da integração?

Sim. O plugin inclui um componente específico para geração de PDFs através do Crystal Reports Engine, permitindo espelhos de notas fiscais e impressão de propostas comerciais.

O plugin precisa estar no mesmo servidor do SAP Business One?

Não é obrigatório. O plugin pode ser instalado em qualquer servidor Windows com acesso à rede do B1 e conectividade HTTPS com o Vendelo. O recomendado é instalá-lo em C:\vendelo\b1i\.

Como são sincronizadas as atualizações do SAP com o Vendelo?

A procedure VDO_TRIAGE_EVENTS, chamada pela SBO_TRANSACTION_NOTIFICATION, registra eventos de modificação na tabela VDO_KEYS. O plugin monitora essa tabela e notifica o Vendelo em tempo real.

Posso usar campos de usuário já existentes no meu SAP com o Vendelo?

Sim. O Vendelo pode ler e utilizar campos de usuário existentes sem criar novos campos. Os parâmetros XPedFieldName e NItemPedFieldName no B1iSettings.json permitem mapear campos UDF já existentes.

É possível alterar a porta padrão 8787 para outra porta?

Sim. Altere a porta no arquivo appsettings.json na seção Kestrel.Endpoints.Url e atualize também o parâmetro BaseUrl no B1iSettings.json e as regras de firewall correspondentes.

O que acontece se a procedure VDO_TRIAGE_EVENTS falhar?

A procedure foi desenvolvida para ser à prova de falhas. Erros são capturados e tratados silenciosamente, sem interromper o fluxo normal do SAP Business One, garantindo estabilidade total do sistema.

Como verificar se a integração está funcionando corretamente?

Execute sc query "Vendelo - B1i" para verificar o serviço, teste a porta com telnet localhost 8787 e consulte os logs do plugin. O dashboard do Vendelo também exibe o status da integração em tempo real.

É necessário reiniciar o SAP Business One após instalar a integração?

Não. Apenas certifique-se de que a Service Layer esteja ativa e que a tabela VDO_KEYS e a procedure VDO_TRIAGE_EVENTS tenham sido criadas corretamente.

Posso usar o mesmo plugin para múltiplas empresas no SAP?

Sim. O plugin suporta múltiplas empresas. Adicione novos objetos no array Companies de ambos os arquivos (appsettings.json e B1iSettings.json) com os parâmetros de conexão de cada empresa.

Como configurar o certificado SSL para HTTPS?

O arquivo setup.bat executa automaticamente o script generate_certificate.ps1, que cria um certificado autoassinado em C:\vendelo\certificate\default.pfx. A senha gerada deve ser registrada no campo Certificate.Password do appsettings.json.

Como atualizar o plugin para uma nova versão?

Pare o serviço com sc stop "Vendelo - B1i", substitua os arquivos do plugin mantendo os arquivos de configuração (appsettings.json), e reinicie com sc start "Vendelo - B1i". Sempre faça backup das configurações antes da atualização.

Como obter suporte técnico para problemas na integração?

Entre em contato com o suporte técnico da Vendelo fornecendo os logs do plugin (habilite UseLogs: true antes de reproduzir o problema), a versão instalada do .NET e uma descrição detalhada do problema.

Como configurar o plugin em ambiente Docker (servidor Vendelo)?

Crie o arquivo B1iSettings.json como File Mount em /etc/vdo/B1iSettings.json no container e defina a variável de ambiente B1iConfigFileName=/etc/vdo/B1iSettings.json nos serviços gql e jobProxy. O arquivo appsettings.json permanece no servidor Windows do cliente.

Qual o add-on fiscal suportado para emissão de NF?

O parâmetro AddOnFiscalName no B1iSettings.json aceita os valores INVENT e SKILL. Configure com o nome do add-on fiscal instalado no ambiente SAP do cliente. Deixe null caso não haja add-on fiscal configurado.