SAP Business One — Geração de boletos

Este artigo explica como habilitar a geração de boletos em PDF dentro do Vendelo para clientes que emitem cobrança pelo Invent Bank Plus no SAP Business One. A primeira metade é para o gestor: o que o recurso entrega, onde ele aparece e o que ele não faz. A segunda é o passo a passo do consultor de implantação: o que configurar no appsettings.json do Vendelo.B1i — o plugin instalado no servidor de integração do cliente —, as regras que ligam e desligam o botão, o roteiro de homologação e a tabela de erros. Ao final, você sai de um ambiente sem boleto para um vendedor enviando o PDF por WhatsApp no celular.

O que o recurso entrega (para o gestor)

Sem este recurso, o vendedor que precisa da segunda via de um boleto abre um chamado no financeiro, alguém entra no SAP, gera o PDF e devolve por e-mail. Com ele, o próprio vendedor gera o boleto na tela em que já está — na nota fiscal ou na consulta financeira do cliente — e envia pelo WhatsApp na hora, do celular, na frente do cliente.

O que o usuário pode fazer:

• Gerar o boleto de uma parcela específica — sai um arquivo PDF.
• Gerar os boletos de todas as parcelas de uma nota — sai um arquivo ZIP com um PDF por parcela.
• Visualizar o arquivo na hora, ou enviar por WhatsApp (ou qualquer app de compartilhamento do aparelho).

O Vendelo não emite boleto. Quem cria a cobrança, registra no banco e produz o PDF é o Invent Bank Plus. O Vendelo pergunta ao Bank Plus quais boletos existem para aquele documento e entrega o PDF ao usuário. Se o boleto ainda não foi gerado no Bank Plus, não há o que buscar — e o usuário vê “Boleto indisponível para este título”.

Consequência prática para o gestor: a rotina de geração de boletos no SAP continua igual. O Vendelo é uma janela de leitura sobre ela. Se o financeiro atrasa a geração da remessa, o vendedor não vê boleto — e isso é comportamento correto, não defeito.

Onde o usuário encontra

1. Na nota fiscal de venda

Na aba Resumo da nota fiscal de venda, a barra inferior de ações traz o botão Gerar boleto. É o caminho de quem acabou de faturar e quer mandar a cobrança junto com a nota.

2. Nas informações financeiras do cliente

Em Informações financeiras → Itens a pagar, a coluna Boleto traz o botão Abrir em cada título que aceita boleto. É o caminho de quem está negociando com um cliente inadimplente e quer resolver a pendência na conversa.

Nos dois caminhos abre o mesmo modal: escolha Todas as parcelas ou Parcela específica e depois Visualizar ou WhatsApp.

A diferença entre os dois caminhos está na lista de parcelas. Pela nota fiscal, o Vendelo consulta o Bank Plus antes de abrir o modal e mostra cada parcela com valor, vencimento e número do boleto. Pela grade de títulos, o modal abre já com o número da parcela daquela linha.

Como funciona, de ponta a ponta

São quatro elos. O consultor não precisa conhecer o que trafega entre eles, mas precisa saber em qual deles a falha aconteceu — é isso que separa “reinicia o serviço” de “abre chamado na Invent”.

1. Vendelo (app do vendedor): mostra o botão e o modal e, no fim, abre ou compartilha o arquivo recebido. Nada é configurado aqui.

2. Vendelo (nuvem): valida o documento, descobre a filial e o ID do ERP e chama o B1i da empresa. Não conhece o Bank Plus.

3. Vendelo.B1i (plugin no servidor de integração do cliente): é o único elo que conhece o Bank Plus. Precisa estar na versão 1.0.0.14 ou superior — é ela que traz o módulo de boletos. É aqui que fica toda a configuração de boleto, no appsettings.json.

4. Invent Bank Plus: devolve os boletos do documento e o PDF de cada um.

Regra de bolso do diagnóstico: erro de configuração aparece antes de qualquer contato com a Invent (o usuário recebe “provedor não configurado” e o log do Bank Plus fica vazio). Erro da Invent chega com a resposta dela embutida na mensagem. Veja a tabela de erros.

Invent Bank Plus, Skill e outros add-ons

O Vendelo não fala “boleto” em geral: ele fala com um add-on específico. Hoje o B1i tem dois provedores:

Provedor	Para que serve
Invent Bank Plus	O provedor de produção. Único add-on bancário homologado com o Vendelo.
Fake	Simulador de homologação. Devolve boletos e PDFs fictícios, sem tocar em banco nenhum. Nunca em produção.

Cliente que usa Skill ou qualquer outro add-on bancário: fale conosco antes de vender ou prometer o recurso. Não existe configuração no appsettings.json que faça o boleto funcionar com outro add-on — a integração precisa ser desenvolvida e homologada com o fabricante. Traga o caso para o time do Vendelo com o nome e a versão do add-on, e avaliamos prazo e viabilidade. Tentar apontar o provedor Invent para a API de outro fornecedor não funciona.

Não confunda com o add-on fiscal do cliente (que também pode ser Invent ou Skill, e cuida de nota fiscal). São coisas separadas: um cliente pode ter add-on fiscal da Skill e cobrança pelo Bank Plus, e aí o boleto funciona normalmente. O que importa aqui é quem gera a cobrança bancária.

Pré-requisitos da implantação

Confirme item por item antes de tocar no appsettings.json. Cada um destes já foi causa de “não funciona” em campo:

Item	Obrigatoriedade	Como confirmar
Invent Bank Plus instalado e gerando boletos no SAP do cliente	Obrigatório	Peça ao financeiro uma nota fiscal recente com boleto já gerado e anote o número do documento — ela será a sua massa de teste
API do Bank Plus publicada e no ar	Obrigatório	A Invent informa a URL base e a credencial de acesso
Rede liberada entre o servidor de integração e o Bank Plus	Obrigatório	Teste a partir do servidor onde o B1i roda, não da sua máquina
Credencial de acesso à API da Invent	Obrigatório	Fornecida pela Invent; é o que vai no campo Authorization
Vendelo.B1i versão 1.0.0.14 ou superior instalado no servidor de integração do cliente	Obrigatório	É a versão que traz o módulo de boletos. Na dúvida, valide com a etapa 1 da homologação: se o provedor Fake responde, a versão atende
Empresa configurada no Vendelo (URL, token e base do B1i)	Obrigatório	As informações financeiras online do cliente já funcionam
Filiais com ERP id sincronizado	Obrigatório	A filial do documento identifica a cobrança no Bank Plus; filial sem ERP id derruba a geração
Notas fiscais sincronizadas com o ERP	Obrigatório	Documento que só existe no Vendelo não tem boleto

Configuração do Vendelo.B1i

Toda a configuração de boleto vive em um único lugar: o nó B1Settings.BillingSlipSettings do appsettings.json do Vendelo.B1i, no servidor de integração do cliente. Não há tela, não há cadastro no Vendelo, não há nada a configurar no app do vendedor.

Exemplo 1 — Invent Bank Plus (produção)

{
  "B1Settings": {
    "Encrypted": true,
    "Token": "KEY:AQAAANCMnd8BFdERjHoAwE...",
    "BillingSlipSettings": {
      "DefaultProvider": "Invent",
      "Providers": [
        {
          "Name": "Invent",
          "BaseUrl": "https://servidor-do-bankplus:8443",
          "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        }
      ]
    },
    "Companies": [
      {
        "Company": {
          "DBName": "SBO_CLIENTE",
          "DBHost": "SRV-SAP",
          "DBProvider": "...",
          "DBUsername": "...",
          "DBPassword": "KEY:AQAAANCMnd8BFdERjHoAwE..."
        }
      }
    ]
  }
}

Exemplo 2 — Fake (homologação)

{
  "B1Settings": {
    "Encrypted": true,
    "Token": "KEY:AQAAANCMnd8BFdERjHoAwE...",
    "BillingSlipSettings": {
      "DefaultProvider": "Fake",
      "Providers": [
        {
          "Name": "Fake"
        },
        {
          "Name": "Invent",
          "BaseUrl": "https://servidor-do-bankplus:8443",
          "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        }
      ]
    },
    "Companies": [ "..." ]
  }
}

Repare no que muda entre os dois: só o DefaultProvider. Deixe os dois provedores cadastrados e alterne pelo nome — assim você vai e volta entre homologação e produção sem reescrever credencial (e sem risco de errar a URL na pressa). O Fake não usa BaseUrl nem Authorization: ele não chama ninguém.

Campo	Obrigatoriedade	Descrição
DefaultProvider	Obrigatório	Qual provedor usar. Aceita Invent, BankPlus (nomes equivalentes, mesmo provedor) e Fake. Precisa casar com o Name de um item de Providers — maiúsculas e minúsculas não importam.
Providers[].Name	Obrigatório	Identificador do provedor, referenciado pelo DefaultProvider.
Providers[].BaseUrl	Obrigatório	Apenas a raiz da API do Bank Plus (protocolo, servidor e porta). O B1i completa o caminho sozinho — não acrescente rota nenhuma depois do host. Barra final é ignorada. Não se aplica ao Fake.
Providers[].Authorization	Obrigatório	Valor completo do cabeçalho de autorização, incluindo o esquema (Bearer …, Basic …), exatamente como a Invent entregou. O B1i envia o conteúdo como veio, sem prefixar nada. Não se aplica ao Fake.

Com BaseUrl ou Authorization em branco, o B1i não acusa erro de digitação: ele simplesmente não ativa o provedor — e o usuário recebe “provedor de boleto não configurado”, sem nenhum registro no Bank Plus. Diante desse erro, o primeiro lugar para olhar é este arquivo, não a rede.

Uma configuração para todas as empresas

O BillingSlipSettings fica fora do nó Companies, e isso é proposital: é um provedor por instalação do B1i, não por empresa. Uma instalação atende várias bases do SAP, desde que todas usem o mesmo Bank Plus e a mesma credencial. Se o cliente tiver bases atendidas por Bank Plus distintos, precisa de instalações separadas do B1i.

Criptografia da credencial

Com Encrypted: true, o B1i descriptografa, na inicialização, todo valor que comece com KEY: — inclusive o Authorization do provedor de boleto. Valor sem o prefixo é usado exatamente como está escrito.

O utilitário EncryptSettings não criptografa o Authorization. Ele protege Token, LagoToken, DBPassword e SLPassword, e nada mais. Rodar o utilitário e assumir que o arquivo inteiro ficou protegido deixa a credencial do Bank Plus em texto puro no servidor. Ou aceite isso conscientemente, ou proteja o valor à parte e cole no arquivo com o prefixo KEY:.

A proteção é vinculada à máquina: um valor KEY: só é lido no servidor onde foi gerado. Copiar um appsettings.json pronto de um servidor para outro quebra a leitura. Em troca ou migração de servidor, gere os valores de novo na máquina nova.

Depois de editar o arquivo

O B1i lê a configuração uma vez, na inicialização. Salvar o arquivo não muda nada em quem já está rodando: reinicie o serviço do Vendelo.B1i. É a causa mais comum de “configurei e continua dizendo que não está configurado”.

Configuração do Vendelo

Do lado do Vendelo não há chave nova de boleto — nada a habilitar, nada a licenciar em separado. O que precisa existir é a empresa apontando para o B1i (URL, token e nome da base), a mesma configuração que faz as informações financeiras online funcionarem. Se a aba Itens a pagar do cliente já traz os títulos do SAP, este elo está de pé.

Boleto é recurso online: o app precisa de conexão e o documento não pode ter alterações pendentes de sincronização. Em campo, sem sinal, o botão não aparece — e isso é proposital, já que o PDF vem do servidor do cliente na hora do clique.

Quando o botão aparece (e quando não)

Metade dos chamados de “sumiu o botão” se resolve aqui. As regras são fixas e avaliadas no app.

Na nota fiscal — todas as condições precisam ser verdadeiras

• O documento é uma nota fiscal de venda (pedido, cotação e nota de crédito não têm boleto).
• O documento já tem ERP id — ou seja, existe no SAP.
• Não há alterações pendentes nem edição em andamento na tela.
• O aparelho está online e sem pendências offline.

Na grade de Itens a pagar — quem é elegível

O botão Abrir só aparece nos tipos de título que o SAP consegue associar a uma cobrança:

Tipo de título	Tem botão de boleto?
Nota fiscal de saída (AR Invoice)	Sim
Lançamento contábil / conciliação (Journal)	Sim
Nota de crédito de saída (AR Credit Note)	Não
Adiantamento de cliente (AR Down Payment)	Não
Documentos de compra (AP Invoice, AP Credit Note, AP Down Payment)	Não
Recebimentos e pagamentos (Incoming/Outgoing Payment)	Não

Além do tipo, a linha precisa ter filial, tipo de origem e ID de origem preenchidos. Faltando qualquer um, o botão aparece mas recusa a ação — sinal de dado incompleto vindo do ERP, normalmente filial sem ERP id.

Roteiro de homologação

Suba em duas etapas. A primeira prova o caminho até o B1i sem depender da Invent; a segunda liga o Bank Plus de verdade. Fazer as duas de uma vez é o que transforma um erro simples numa caça ao fantasma: quando algo falha, você não sabe se é a sua configuração, a rede do cliente ou a API da Invent.

Etapa 1 — Provar a cadeia com o provedor Fake

1. No appsettings.json, deixe "DefaultProvider": "Fake", como no exemplo 2 acima.

2. Reinicie o serviço do Vendelo.B1i.

3. No app, abra uma nota fiscal de venda já sincronizada e toque em Gerar boleto.

4. O modal deve listar três parcelas, de R$ 101,00, R$ 102,00 e R$ 103,00, vencendo em 7, 14 e 21 dias. Essa é a assinatura do Fake: se você a vê, app, nuvem, B1i, token e empresa estão de pé.

5. Toque em Visualizar: abre um PDF de teste com os dados do documento. Toque em WhatsApp: o compartilhamento do aparelho abre com o arquivo anexado.

Não esqueça o Fake ligado em produção. Ele entrega um PDF que parece um boleto e não é: sem código de barras válido, sem registro no banco. Voltar o DefaultProvider para Invent e reiniciar o serviço faz parte da etapa 2 — não é opcional.

Etapa 2 — Ligar o Bank Plus

1. Troque para "DefaultProvider": "Invent", confira BaseUrl e Authorization e reinicie o serviço.

2. Use a nota que o financeiro indicou no levantamento — uma com boleto comprovadamente já gerado no Bank Plus. Testar com nota sem boleto produz um “não encontrado” legítimo que parece falha de configuração e queima horas.

3. Gere uma parcela e confira o PDF: valor, vencimento, sacado e código de barras devem bater com o boleto que o financeiro emite hoje pelo SAP.

4. Gere todas as parcelas e confira o ZIP: um PDF por parcela, nada faltando.

5. Repita pelo caminho Informações financeiras → Itens a pagar → Boleto → Abrir, em um título de nota fiscal de saída.

6. Feche com um teste no celular do vendedor, com dados móveis, enviando por WhatsApp para um número de teste. É o uso real do recurso — e o único jeito de provar o compartilhamento no aparelho.

Erros, causas e o que fazer

Mensagem / status	O que aconteceu	O que fazer
BILLING_SLIP_PROVIDER_NOT_CONFIGURED	O B1i não ativou provedor nenhum: DefaultProvider em branco, sem item correspondente em Providers, ou BaseUrl/Authorization vazios	Revise o BillingSlipSettings e reinicie o serviço
B1I_NOT_CONFIGURED	A empresa no Vendelo está sem URL, token ou base do B1i	Corrija o cadastro da empresa; sem isso nenhuma integração online funciona
BILLING_SLIP_PDF_NOT_SUPPORTED	O B1i instalado não tem o módulo de boletos (anterior à 1.0.0.14)	Atualize o Vendelo.B1i do cliente para a versão 1.0.0.14 ou superior
BILLING_SLIP_NOT_FOUND	O Bank Plus não tem boleto para esse documento (ou para essa parcela)	Confirme com o financeiro se a cobrança foi gerada; confirme a filial do documento
INVALID_INSTALLMENT	Vieram vários boletos onde se esperava um só, sem número de parcela	Gere pela parcela específica
DOCUMENT_NOT_SYNCED	A nota ou a filial está sem ERP id	Sincronize o documento; verifique o ERP id da filial
INVALID_DOCUMENT_TYPE	Pediu boleto para um documento que não é nota fiscal de venda	Use a nota fiscal, não o pedido
FINANCIAL_TITLE_NOT_SUPPORTED	O título não é nota fiscal de saída nem lançamento contábil	Comportamento esperado — veja a tabela de elegibilidade
FINANCIAL_TITLE_WITHOUT_BILLING_REFERENCE	A linha veio do ERP sem filial ou sem ID de origem	Investigue o dado no SAP: quase sempre é filial sem ERP id
PROVIDER_ERROR	O Bank Plus respondeu erro (credencial recusada, indisponibilidade, timeout). A mensagem traz a resposta devolvida pela Invent	Credencial, rede ou instabilidade da API — leve a mensagem para a Invent

Ao abrir chamado, mande o status exato, o número do documento, a filial e o horário. Com esses quatro dados o log responde em minutos de qual lado está o problema; sem eles, a investigação começa do zero.

Perguntas frequentes

O Vendelo emite o boleto ou só busca o que já existe?

Só busca. A emissão, o registro no banco e o PDF são do Invent Bank Plus. Se a cobrança não foi gerada no SAP, o Vendelo não tem o que mostrar.

O cliente usa a Skill (ou outro add-on bancário). Dá para configurar?

Não. O único add-on bancário homologado é o Invent Bank Plus, e não existe configuração no appsettings.json que contorne isso — a integração precisa ser desenvolvida e homologada com o fabricante. Fale com o time do Vendelo, informando o add-on e a versão, antes de prometer o recurso ao cliente.

Precisa de licença ou módulo extra do Vendelo?

Não. Precisa do Vendelo.B1i na versão 1.0.0.14 ou superior — que traz o módulo de boletos — instalado no servidor de integração, e do Bank Plus licenciado no cliente. A configuração é um nó no appsettings.json do B1i.

Configurei tudo e continua dizendo que o provedor não está configurado. Por quê?

Na quase totalidade dos casos, o serviço do B1i não foi reiniciado — a configuração é lida só na inicialização. Se já reiniciou, confira se o DefaultProvider casa exatamente com o Name de um provedor e se BaseUrl e Authorization estão preenchidos.

Serve para boleto de pedido de venda?

Não. O boleto nasce da cobrança, e a cobrança nasce do faturamento. Só nota fiscal de venda (e lançamento contábil, na consulta financeira) tem boleto.

Uma instalação do B1i atende várias empresas?

Sim, desde que todas usem o mesmo Bank Plus e a mesma credencial: o provedor é único por instalação do B1i. Bank Plus diferentes exigem instalações separadas.

Dá para usar o provedor Fake para demonstração comercial?

Para demonstrar o fluxo da tela, sim. Nunca em ambiente onde alguém possa confundir o PDF de teste com um boleto real: ele não tem código de barras válido nem registro bancário.

Por que “todas as parcelas” baixa um ZIP em vez de um PDF só?

Porque o Bank Plus devolve um PDF por boleto e o B1i empacota os arquivos sem alterá-los. Cada parcela chega como o arquivo original, com o número do boleto e da parcela no nome.

O vendedor consegue gerar boleto sem internet?

Não. O PDF vem do servidor do cliente no momento do clique, então o botão só aparece com conexão e sem pendências offline no documento.

O boleto sai igual ao que o financeiro emite pelo SAP?

Sim: é o mesmo arquivo, produzido pelo mesmo Bank Plus. O Vendelo não redesenha nem reprocessa o PDF.

O que muda quando o cliente troca o servidor de integração?

Os valores criptografados com o prefixo KEY: param de funcionar, porque a proteção é vinculada à máquina. Gere os valores de novo no servidor novo e reinicie o serviço.