Renegociação BankPlus v3

A funcionalidade de Renegociação na API v3 permite negociar dívidas de clientes diretamente pelo Add-on, aplicando multas, juros, taxas e descontos de forma automatizada. Na V3, o fluxo de aprovação foi reestruturado: a decisão de aprovar passou a ser enviada no corpo da requisição, e as etapas de aprovação, reprovação e cancelamento ganharam endpoints próprios.

Collection em anexo no final da página.

1. Configuração e Acesso (InventApps)

Diferente da versão anterior, a V3 utiliza o modelo de Bearer Tokens com expiração de 8 horas.

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

2. Obtenha o ID do Serviço e a Chave Secreta.

3. Gere o token de acesso conforme o guia geral de Autenticação da API v3.

Importante: não é mais necessário informar o apelido da base na URL. A validação é feita pela porta e pelo token vinculado ao serviço.

2. Resumo dos Endpoints

Parâmetros de rota

• codigoDaEmpresa: código da empresa no BankPlus, obtido em GET /api/v3/Empresas.

• codigoDoCliente: código do Parceiro de Negócios (PN) no SAP.

• id: código da renegociação, o mesmo exibido no campo "Código" da tela de Renegociação do BankPlus.

Fluxo de uso

1. Consulte as parcelas disponíveis do cliente.

2. Crie a renegociação informando as parcelas de origem e as novas parcelas propostas. Ela pode ser aprovada no mesmo envio ou ficar pendente.

3. Se ficou pendente, aprove ou reprove pelos endpoints de status.

4. Se necessário, cancele uma renegociação já aprovada ou processada.

3. Métodos de Consulta (GET)

Buscar Parcelas para Renegociação

Retorna as parcelas do cliente disponíveis para uma nova renegociação na empresa informada.

• Endpoint: GET /api/v3/Renegociacao/{codigoDaEmpresa}/{codigoDoCliente}/parcelas

• Como usar: informe o código da empresa e o código do PN. O retorno traz a lista de documentos aptos para o acordo, que servem de base para montar as parcelas de origem no POST.

Obter Renegociação por ID

Busca os detalhes de um acordo existente, incluindo o status atual e o espelho das novas parcelas propostas.

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

Listar Renegociações da Empresa

Retorna as renegociações registradas para a empresa informada.

• Endpoint: GET /api/v3/Renegociacao/empresa/{codigoDaEmpresa}

• Como usar: útil para acompanhar os acordos da empresa e identificar o id de uma renegociação antes de aprová-la, reprová-la ou cancelá-la.

4. Criar Renegociação (POST)

Na V2, a aprovação era definida por um parâmetro na URL (aprovar=S/N). Na V3, essa decisão foi movida para o Body da requisição, junto com a justificativa do acordo.

• Endpoint: POST /api/v3/Renegociacao/{codigoDaEmpresa}

• Estrutura do Body (JSON):

  • aprovar: true para efetivar o acordo no mesmo envio, ou false para salvar a renegociação sem aprová-la.

  • motivo: descrição ou justificativa do acordo.

  • renegociacao: objeto com codigoParceiro, dataVencimentoProposta e as listas parcelaRenegociadas (parcelas de origem) e propostas (novas parcelas).

Observação: a V3 utiliza o padrão camelCase nos nomes dos campos (iniciando com letra minúscula) e exige datas no formato ISO 8601 (ex.: 2026-03-19T00:00:00Z). A estrutura completa dos campos pode ser consultada no Swagger.

5. Gestão de Status (PATCH)

Para alterar o status de uma renegociação existente sem reenviar os dados financeiros, utilize os métodos PATCH.

Aprovar

Altera o status de "Aguardando Aprovação" para "Aprovada", integrando o lançamento ao SAP.

• Endpoint: PATCH /api/v3/Renegociacao/{codigoDaEmpresa}/{id}/aprovar

Reprovar

Invalida a proposta atual e libera as parcelas originais para uma nova negociação.

• Endpoint: PATCH /api/v3/Renegociacao/{codigoDaEmpresa}/{id}/reprovar

Cancelar

Utilizado para renegociações já aprovadas ou processadas, revertendo o status conforme as regras de negócio do Add-on.

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