Serviço de API Rest BankPlus v3

O serviço de API Rest do BankPlus evoluiu para atender às demandas de performance e segurança das integrações atuais. A Versão 3 (V3) estabelece um novo padrão de interoperabilidade, permitindo a comunicação segura entre o Add-on e sistemas externos.

O que isso significa na prática?
A API permite que sistemas externos, como portais de faculdades para impressão de boletos, plataformas de e-commerce para pagamentos ou sistemas de CRM para gestão de clientes, consultem e emitam documentos diretamente pelo Add-on, de forma automática e em tempo real.

1. O que mudou na V3?

A principal evolução da V3 é a substituição de chaves estáticas por tokens temporários (Bearer Tokens) e a adoção do padrão OpenAPI (Swagger) como fonte oficial da documentação.

• Credenciais por serviço: a autenticação usa um Client ID e um Client Secret exclusivos para cada serviço configurado no InventApps.

• Tokens com expiração: o acesso é feito por tokens com validade definida, o que reduz o risco de exposição de credenciais permanentes.

• URL simplificada: a rota não exige mais o apelido da base de dados. A porta do serviço e o token são suficientes para identificar o acesso.

• Documentação viva: o Swagger funciona como console de testes em tempo real e reflete sempre os campos e regras da versão instalada.

• Retornos padronizados: os erros de validação seguem o formato ProblemDetails, e operações com várias parcelas informam o resultado de cada item (veja o item 6).

2. Configuração de Ambiente

Antes de realizar qualquer teste ou integração, confira os pré-requisitos abaixo:

1. InventApps: o InventApps deve estar configurado para a sua empresa.

   • Caso seja a primeira instalação, siga o artigo: BankPlus WebClient | Instalação do Invent Apps Services

2. Configuração do Serviço: ao criar o serviço do tipo API Rest V3, é indispensável marcar a flag "Usar Service Layer no Processamento".

   • Nota: essa opção garante que a API utilize a camada de serviços oficial do SAP (Service Layer), para que o processamento dos dados ocorra conforme o esperado na V3.
     

3. Status do Serviço: confirme se o serviço está com o status "Iniciado".

4. URL Base: a URL de acesso é formada pelo endereço do servidor e pela porta configurada no serviço (ex.: http://192.168.0.1:9993). Todos os endpoints partem de /api/v3/ (ex.: http://192.168.0.1:9993/api/v3/Cobrancas).

3. Autenticação e Ciclo de Vida do Token

Na V3, toda requisição precisa de um token válido. O fluxo de autenticação é o seguinte:

1. Geração de Credenciais: ao configurar o serviço no InventApps, são gerados o Client ID (ID do Serviço) e o Client Secret (Chave Secreta).

2. Solicitação de Acesso: a aplicação externa faz um POST para o endpoint de autenticação enviando essas credenciais. O endpoint e o formato do body estão disponíveis no Swagger.

3. Entrega do Bearer Token: a API valida os dados e retorna um token JWT, que deve ser enviado no cabeçalho (Header) de todas as requisições seguintes:

   Authorization: Bearer [SEU_TOKEN]

4. Política de Renovação: o token tem validade de 8 horas. Após esse prazo, solicite um novo token repetindo o passo 2.

4. Homologação: Swagger e Postman

A V3 disponibiliza duas formas equivalentes de consulta e teste. Ambas são fontes oficiais e trazem a documentação detalhada dos endpoints: regras de validação, exemplos de requisição e exemplos de retorno de sucesso e de erro. Os artigos de cada módulo resumem as regras principais e indicam essas fontes para os exemplos completos.

Swagger (Interface Interativa)

O Swagger é uma documentação viva, acessível pelo navegador. É a ferramenta ideal para conhecer a estrutura da V3 sem precisar escrever código.

• Vantagem: não requer instalação. Permite visualizar o esquema de dados (Schema), consultar a descrição das regras de cada endpoint e executar chamadas rápidas pelo botão Try it out.

• URL de Acesso: composta pelo endereço do servidor (IP fixo, nome de domínio ou localhost para testes internos) e pela porta configurada no serviço do InventApps.

  • Exemplo padrão: http://localhost:9993/swagger/index.html

  • Nota: se o serviço estiver instalado em um servidor dedicado, substitua "localhost" pelo IP ou nome do servidor correspondente.

• Como usar: acesse a URL do seu serviço, clique em Authorize, informe o Bearer Token que é obtido após fazer o login com o ClientId e ClientSecret e realize os testes diretamente nos endpoints.

Postman (Automação e Organização)

O Postman é indicado para quem prefere organizar fluxos de trabalho ou automatizar testes. A collection da V3 é disponibilizada para download no artigo de cada módulo e já traz as instruções e exemplos de cada endpoint.

• Vantagem: permite salvar variáveis de ambiente (como URL base e token) e encadear requisições.

• Configuração: importe a collection, faça o login com o ClientId e ClientSecret e na aba Authorization "Bearer Token" informe o token ativo.

5. Módulos Disponíveis

A V3 é organizada em módulos, cada um responsável por um tipo de operação e alinhado às regras de negócio do SAP Business One.

Cobrança

• Gestão de recebíveis: consulta de cobranças, obtenção do PDF do boleto, cancelamento e atualização.

• Geração de boletos em três modalidades: avulso (sem documento de origem no SAP), individual (um boleto por parcela de nota fiscal, adiantamento ou LCM) e agrupado (um único boleto reunindo 2 ou mais parcelas).

Pagamento

• Agendamento e execução de pagamentos com conciliação automática no SAP.

Renegociação

• Recuperação de crédito com workflow de aprovação para novas propostas e taxas.

Empresa e Filiais

O módulo de Empresas funciona como um centralizador de contexto. Ele não realiza lançamentos, mas fornece os IDs necessários para direcionar as requisições de Cobrança, Pagamento e Renegociação em ambientes com múltiplas filiais ou bancos de dados.

• Listar Empresas (GET /api/v3/Empresas): retorna todas as bases de dados e filiais configuradas no serviço. Use este endpoint para identificar o id ou o codigoDaFilial a ser informado nos demais endpoints, como o codigoDaEmpresa da rota e o empresaId do body na geração de boletos.

• Obter por ID (GET /api/v3/Empresas/{id}): retorna os detalhes de uma única unidade, como o nome do banco de dados (ex.: SBO_TESTE) e o código da filial no SAP.

Parceiros (Business Partners)

• Sincronização de dados cadastrais de clientes e fornecedores e consulta de notas fiscais.

6. Padrão de Retornos

Os endpoints da V3 seguem os códigos HTTP abaixo. O significado exato em cada endpoint está descrito no artigo do módulo e no Swagger.

Formato ProblemDetails
Os erros padronizados trazem os campos title (resumo), status (código HTTP), detail (motivo; quando há vários erros, eles vêm separados por |) e instance (rota chamada).

7. Boas Práticas de Integração

• Renovação do token: implemente a renovação automática do token antes do fim das 8 horas para evitar interrupções.

• Padronização de datas: utilize o formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) para evitar conflitos de fuso horário.

• Tratamento do retorno 207: em operações com várias parcelas, percorra a lista de resultados e trate individualmente os itens com sucesso = false. Reenvie apenas as parcelas que falharam.

• Não gerar boletos em duplicidade: ao receber 422 ou ao perder a resposta por timeout, não reenvie a geração. Consulte o boleto por GET /api/v3/Cobrancas/{id} ou recupere o PDF por GET /api/v3/Cobrancas/{id}/pdf. Uma nova tentativa para a mesma parcela é recusada, pois ela já possui boleto ativo.

• Leitura das mensagens de erro: registre o conteúdo completo do campo detail ou da mensagem de cada item. Elas identificam a parcela, o documento e o motivo, o que agiliza o atendimento pelo suporte.

• Ambiente de testes: realize as validações iniciais em uma base de homologação antes de apontar a integração para a base de produção.