Cobrança BankPlus v3

O módulo de Cobrança na API v3 foi projetado para centralizar e automatizar o ciclo de vida dos recebíveis. Ele permite que sistemas externos gerenciem títulos, emitam boletos e consultem o status de faturamento diretamente no SAP Business One, garantindo que a informação financeira esteja sempre sincronizada e segura.

Collection em anexo no final da página.

1. Configuração e Acesso (InventApps)

Seguindo o padrão global da V3, o acesso aos métodos de cobrança é gerenciado via Bearer Tokens.

• Abra o InventApps e localize o serviço do tipo API Rest.

• Utilize o ID do Serviço e a Chave Secreta para gerar o token de acesso de 8 horas.

• Importante: A porta configurada no InventApps e o Token são os únicos requisitos para a validação da URL, dispensando o uso de apelidos de base de dados na rota como anteriormente.

2. Resumo dos Endpoints

Observação: Este artigo apresenta as regras e os retornos de cada endpoint. Os exemplos completos de requisição e de retorno (sucesso e erro) estão documentados na collection disponibilizada para download, no Postman e no Swagger da API.

3. Métodos de Consulta (GET)

Listar Cobranças
Retorna uma lista geral de cobranças registradas no sistema.

• Endpoint: GET /api/v3/Cobrancas

• Como usar: Ideal para obter uma visão macro dos títulos gerados, permitindo filtros de busca conforme a necessidade da integração.

Obter Detalhes por ID
Busca informações detalhadas de um título específico através de seu identificador único.

• Endpoint: GET /api/v3/Cobrancas/{id}

Obter PDF da Cobrança
Método direto para recuperar o arquivo PDF do boleto para visualização ou impressão.

• Endpoint: GET /api/v3/Cobrancas/{id}/pdf

• Utilidade: Essencial para portais de autoatendimento que precisam disponibilizar a segunda via do boleto instantaneamente para o cliente. Também é o caminho para recuperar o PDF quando a geração do boleto retorna 422 (boleto gerado, PDF não gerado).

4. Métodos de Registro e Geração (POST)

A V3 oferece três formas de gerar cobranças:

• Avulso: boleto sem documento de origem no SAP.

• Individual: um boleto para cada parcela informada.

• Agrupado: um único boleto reunindo 2 ou mais parcelas.

Observação: Os exemplos completos de requisição e de retorno (sucesso e erro) estão documentados na collection disponibilizada para download, no Postman e no Swagger da API.

4.1. Registrar Cobrança Avulsa

Gera um boleto avulso, sem nota fiscal, adiantamento ou LCM de origem no SAP. A empresa é a informada em boletoAvulso.empresaId; não há código de empresa na rota.

• Endpoint: POST /api/v3/Cobrancas/avulso

Regras da requisição

• Campos obrigatórios em boletoAvulso: contratoId, parceiroCodigo, parcelaId, dataVencimento e valorDaParcela.

• O contrato deve existir e estar ativo.

• gerarPdf fica na raiz do body, fora de boletoAvulso.

Exemplo de requisição

{
  "gerarPdf": true,
  "boletoAvulso": {
    "parcelaId": 0,
    "data": "2026-10-30T13:30:08.550Z",
    "statusId": 0,
    "parceiroCodigo": "string",
    "parceiroNome": "string",
    "contratoId": 0,
    "empresaId": 0,
    "dataVencimento": "2026-10-30T13:30:08.550Z",
    "valorDaParcela": 0,
    "valoMulta": 0,
    "jurosContratual": 0,
    "desconto": 0,
    "observacoes": "string",
    "nossoNumero": "string"
  }
}

Retornos

• 201 (JSON): boleto gerado, quando gerarPdf = false. O retorno traz o registro completo do boleto, incluindo codigo, nossoNumero, linhaDigitavel, dataVencimento, valorDaParcela e status.

• 200 (application/pdf): PDF do boleto, quando gerarPdf = true.

• 400 (texto simples, não é ProblemDetails): boletoAvulso não enviado; campo obrigatório de boletoAvulso ausente; empresa ou contrato inexistente; contrato inativo; falha na geração do boleto.

• 422 (ProblemDetails): o boleto foi gerado, mas o PDF falhou. O detail traz o Id e o nosso número para consulta em GET /api/v3/Cobrancas/{id}/pdf.

4.2. Regras comuns aos endpoints Individual e Agrupado

Os endpoints /individual e /agrupado recebem o mesmo formato de body: uma lista em que cada item identifica uma parcela de documento do SAP. As regras abaixo valem para os dois.

• Parâmetro de rota: codigoDaEmpresa (inteiro, obrigatório) — código da empresa no BankPlus.

Identificação da parcela

Regras da requisição

• empresaId no body é opcional; se informado, deve ser igual ao código da empresa da rota.

• gerarPdf deve ter o mesmo valor em todos os itens.

• A mesma parcela não pode ser informada mais de uma vez.

Definição do contrato bancário
O contrato é obtido na seguinte ordem de prioridade:

1. contratoId: tem prioridade e deve ser o mesmo em todos os itens.

2. formaDePagamento: usada quando não há contratoId; também deve ser a mesma em todos os itens.

3. Forma de pagamento do documento no SAP, quando nenhum dos dois campos for informado.

4. Parâmetro "NF sem forma de pagamento usar:" da empresa, quando o documento não tiver forma de pagamento.

Importante: O contrato informado em contratoId ou obtido pela formaDePagamento do body é validado antes da geração: deve existir, estar ativo e estar vinculado à empresa.

Exemplo de requisição (Individual e Agrupado)

[
  {
    "empresaId": 12,
    "tipoDeDocumento": "notafiscal",
    "numeroDaNota": 763574,
    "numeroDoDocumento": 0,
    "numeroDaParcela": 1,
    "gerarPdf": false,
    "contratoId": 11,
    "formaDePagamento": "Bol-Bradesco"
  },
  {
    "empresaId": 12,
    "tipoDeDocumento": "notafiscal",
    "numeroDaNota": 763574,
    "numeroDoDocumento": 0,
    "numeroDaParcela": 2,
    "gerarPdf": false,
    "contratoId": 11,
    "formaDePagamento": "Bol-Bradesco"
  },
  {
    "empresaId": 12,
    "tipoDeDocumento": "adiantamento",
    "numeroDaNota": 4120,
    "numeroDoDocumento": 0,
    "numeroDaParcela": 1,
    "gerarPdf": false,
    "contratoId": 11,
    "formaDePagamento": "Bol-Bradesco"
  },
  {
    "empresaId": 12,
    "tipoDeDocumento": "lcm",
    "numeroDaNota": 0,
    "numeroDoDocumento": 52310,
    "numeroDaParcela": 1,
    "gerarPdf": false,
    "contratoId": 11,
    "formaDePagamento": "Bol-Bradesco"
  }
]

4.3. Registrar Cobrança Individual

Gera um boleto para cada parcela informada, sem agrupamento. Cada item da lista é uma parcela. Se uma parcela falhar, as demais são geradas, e o retorno traz o resultado de cada item na mesma ordem da requisição.

• Endpoint: POST /api/v3/Cobrancas/{codigoDaEmpresa}/individual

• Body e regras: conforme o item 4.2.

• Resultado por item: cada item da lista de resultados traz a identificação da parcela, sucesso, mensagem e, quando gerado, boleto.

Retornos

Motivos de falha

4.4. Registrar Cobrança Agrupada

Gera um único boleto com 2 ou mais parcelas distintas. A operação é tudo ou nada: se uma parcela for inválida, nenhum boleto é gerado. Para gerar um boleto por parcela, use POST /api/v3/Cobrancas/{codigoDaEmpresa}/individual.

• Endpoint: POST /api/v3/Cobrancas/{codigoDaEmpresa}/agrupado

• Body e regras: conforme o item 4.2. O exemplo de requisição daquele item vale também para o agrupado.

Retornos

• 200 (JSON): lista com o boleto agrupado gerado, quando gerarPdf = false. No boleto agrupado, notaFiscal vem 0 e numeroDaParcela vem -1.

• 200 (application/pdf): PDF do boleto agrupado, quando gerarPdf = true.

• 400 (ProblemDetails): requisição recusada; o motivo vem no campo detail. Quando houver vários erros, eles vêm juntos, separados por |.

• 422 (ProblemDetails): o boleto foi gerado, mas o PDF falhou. O detail traz o Id e o nosso número para consulta em GET /api/v3/Cobrancas/{id}/pdf.

Motivos de retorno 400

5. Gestão e Atualização (PATCH)

Para alterar o ciclo de vida de uma cobrança sem reenviar todo o cadastro, utilizamos os métodos de atualização parcial.

Cancelar Cobrança
Executa o cancelamento do título tanto no Add-on quanto a instrução para o banco (caso configurado).

• Endpoint: PATCH /api/v3/Cobrancas/{id}/cancelar

Atualizar Dados da Cobrança
Permite alterar informações da cobrança, como datas de vencimento ou valores de instruções, conforme as regras permitidas pelo SAP.

• Endpoint: PATCH /api/v3/Cobrancas/{id}/atualizar