API Cobrança disponibiliza operações relacionadas a emissão de boletos, permitindo acompanhar o ciclo de vida de um boleto.

Todos os clientes e parceiros do banco BS2.

• Ser cliente do banco BS2
• Ter um token de acesso válido

Homologação: https://apihmz.bancobonsucesso.com.br

Produção: https://api.bs2.com

Atendendo a Circular nº 3.598, de 06/06/2012, com redação dada pela Circular 3.956, de 1/08/2019, art 3-A, §1º e Circular 3.978, de 23/01/2020, arts. 30 e 31 o produto foi atualizado incluindo o envio e registro do beneficiário final na CIP. Esta mudança irá afetar apenas os parceiros que forem intermediadores de pagamento. Sendo que o envio do beneficiário final é obrigatório em contrato.

• Quem é o beneficiário final? O dono do produto e/ou serviço oferecido que vai receber o valor do boleto no final do processo. Caso você receba o valor, e depois repasse para seu cliente/parceiro, você é um intermediador de pagamento.

• Como preencher este novo campo? Foi criada uma nova rota para emissão de boletos com a adição do campo beneficiarioFinal. Basta alterar a url e adicionar este campo no request. Lembrando que NÃO há necessidade de gerar novas chaves para utilizar esta nova rota.

• Não sou intermediador, o que devo fazer? O beneficiarioFinal é opcional, caso você não seja intermediador, não precisa preencher este campo.

• O que acontece se eu não migrar para a nova versão (INTERMEDIADOR)? Para clientes que são intermediadores e não mudarem, o BANCO poderá suspender as operações. Visto as medidas legais que o BANCO estará sujeito caso não cumpra com as regras exigidas pelo BACEN.

• O que acontece se eu não migrar para a nova versão (NÃO INTERMEDIADOR)? Não há impacto, mas recomendamos utilizar a nova versão da api, visto que a antiga será descontinuada em breve.

  
  
  • /pj/forintegration/cobranca/v1/boletos/simplificado (sem beneficiarioFinal)
  • /pj/forintegration/cobranca/v2/boletos/simplificado (com beneficiarioFinal)

Utilizamos em nossas API's de autenticação um rate-limit, que permite até 10 requisições de Token e refresh por minuto, sendo necessário realizar o gerenciamento de token descrito abaixo:

Obtenção do Token

Para obter o token de acesso é necessário acessar a plataforma BS2 Empresas, entrar no produto API Banking e criar uma aplicação.

Ao criar a aplicação, deve ser informado as funcionalidades que a mesma terá acesso.

Após preencher as informações e seguir para o próximo passo, será solicitado o 2º fator de autenticação do usuário logado, podendo utilizar o token do aplicativo BS2 Empresas ou sms.

Com o token 2fa validado, serão apresentadas as credencias da aplicação.

Para obter o token de acesso é necessário realizar o fluxo de refresh_token com os dados do passo anterior.

Gerenciamento de Token

É necessário fazer a gestão do token de acesso e do refresh_token dentro do seu sistema.

Caso precise gerar as credenciais novamente, basta acessar a plataforma BS2 Empresas, entrar no produto API Banking, selecionar a aplicação desejada e clicar na opção Gerar novo token.

Pontos Importantes

O cadastro de aplicação é por conta bancária.

Só é necessário acessar a plataforma para gerar um novo token, caso não consiga realizar o fluxo de refresh_token.

O campo expires_in representa a validade do token em segundos, enquanto o token estiver válido, este token deve ser utilizado.

O refresh_token possui um tempo de validade maior que a validade do token (48 horas), ou seja, mesmo se o token de acesso estiver inválido há bastante tempo, e o refresh_token estiver válido, ainda é possível fazer o fluxo de refresh_token para gerar um novo token válido.

Quando o token estiver próximo da validade, deve-se gerar um novo token, usando um refresh_token, para assim, receber um novo token válido pelo mesmo período de tempo.

Não há limite de requisições enquanto o token estiver válido.

Quando um novo token é gerado, o token anterior passa a ser inválido.

É importante frisar que a cada novo token gerado, um novo refresh_token também é gerado.

O token de acesso é necessário para todas as requisições em nossas APIs.

Refresh Token

1.1 Realizar uma requisição Basic Auth no endpoint abaixo com apikey e apisecret da aplicação.

1.2 Informar o valor refresh_token para o campo grant_type.

1.3 Informar o escopo da aplicação para o campo scope.

1.4 Informar o valor do refresh token recebido previamente para o campo refresh_token.

POST /auth/oauth/v2/token

Headers
Content-Type: application/x-www-form-urlencoded
Authorization: basic auth com apikey e apisecret

Request body

grant_type: refresh_token
scope: {escopo da aplicação gerado na plataforma}
refresh_token: {último refresh token gerado (Guid))}

Response body

{
 "access_token": "seu_access_token_guid",
 "token_type": "tipo_de_token",
 "expires_in": "tempo_de_expiracao_em_segundos",
 "refresh_token": "seu_refresh_token_guid",
 "scope": "escopo_da_aplicação"
}

Exemplo:

curl -k 
-H "Authorization: Basic bDczNDQ4ZDYzNGE3NDQ0NjU4ODI4ZWM1OTE4Mzk0ODc4Mjo5YjBkZGE1NDQxZDM0NmMwYjY5MWIyNzg1YTg1NWMzMg==" 
-d "grant_type=refresh_token&scope=saldo&refresh_token=04a8fb41-e28b-4956-b29f-ca59f47ec448" 
-X POST https://apihmz.bancobonsucesso.com.br/auth/oauth/v2/token 

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8

{
 "access_token":"61d741ab-3f4b-4623-8887-ecc943d8ce71",
 "token_type":"Bearer",
 "expires_in":420,
 "refresh_token":"f386e33a-d889-4221-9dba-fc8153112d1d",
 "scope":"saldo"
} 

Respostas

O Banco BS2 disponibiliza um webhook para notificar os clientes em tempo real sobre os eventos que possam ocorrer em seus boletos. Para utilizar o webhook, por favor entre em contato com a equipe do BS2 informando uma URL para que possamos ativar o webhook para você. No momento essa operação é feita apenas manualmente, sendo necessária a solicitação para a equipe Tech do BS2 Empresas.

Funcionamento

O webhook será disparado via uma requisição HTTP POST até que o cliente retorne com um status de sucesso (família HTTP 200).

Contrato

Para cada evento que ocorra em um boleto, um webhook é disparado com a devida informação. Abaixo segue o contrato que será enviado a cada requisição com os dados do boleto e do evento.

{
   "Id":"f3ac8876-5fcb-4dbd-868d-fb5ce76b4af7",
   "Conta":123456,
   "DataNotificacao":"2019-07-12T15:14:17.1724178-03:00",
   "NossoNumeroBoleto":10016587895,
   "SeuNumeroBoleto":"12345",
   "Valor":1000,
   "ValorLiquidado":1000,
   "SituacaoDescricao":"Qualquer valor liquidado independentemente da data do pagamento",
   "Situacao":4,
   "StatusBoleto":[
      {
         "Status":1,
         "Descricao":"Boleto registrado no órgão responsável.",
         "DataStatus":"2019-10-02T22:23:34.9351562-03:00"
      },
      {
         "Status":2,
         "Descricao":"O boleto foi pago com sucesso.",
         "DataStatus":"2019-10-07T07:30:04.9036831-03:00"
      }
   ]
}

Descrição dos campos do modelo principal

Abaixo segue tabela descritiva dos campos enviados na notificação:

Códigos de Situação

Abaixo seguem as situações existentes atualmente e seu significado:

Descrição dos campos do modelo status boleto

A cada novo EVENTO que ocorre com os boletos, enviamos via webhook as informações - abaixo está descrito como 'status' cada evento deste. Abaixo segue a tabela descritiva dos campos enviados no item StatusBoleto

Códigos de Status

Abaixo seguem os eventos informados atualmente e seu significado:

(*) Importante ressaltar que o processo onde é efetivamente identificado o pagamento e recebimento do valor junto ao BS2, é no "Evento 3 - Boleto liquidado/compensado - crédito feito na CC". O processo entre o pagamento do boleto na rede bancária (evento 2) e a compensação efetiva do boleto, podem existir problemas que impedem o recebimento do valor do boleto junto ao BS2, onde muitas vezes o BS2 não tem poder de atuação.

É importante identificar dentro da sua operação, qual a maneira ideal e mais segura de se beneficiar de cada evento deste informado.

Automatize seu processo com segurança!

É possível personalizarmos o logotipo que aparece no boleto?

• "Ao utilizar o endpoint /pj/forintegration/cobranca/v1/boletos/{nossoNumero}/imprimivel - Não é possível alteração de logo. Já no endpoint /pj/forintegration/cobranca/v1/boletos/simplificado - Enviamos um json com os dados do boleto e é possível que desenvolva em sua aplicação o modelo do boleto que desejar.

Existe um campo para cancelamento do boleto com data prevista?

• Atualmente não temos cancelamento via parâmetros em nossa API, as possibilidades são:
  • Cancelamento automático na CIP após 60 dias.
  • Cancelamento solicitado pelo cliente via API no endpoint /pj/forintegration/cobranca/v1/boletos/{nossoNumero}/solicitacoes/cancelamentos.

O boleto pode ser pago após o vencimento caso não possua multa e juros?

• Sim, o boleto após o vencimento pode ser pago em até 60 dias caso não seja solicitado o cancelamento do boleto.

Webhook é enviado até que receba uma resposta 200. Caso a resposta seja diferente disso, qual o padrão de reenvio?

• Realizamos várias tentativas durante um tempo, se não obtivermos sucesso dentro desse período encerramos a notificação. O período e o número de retentativas depende do webhook.

É possivel cadastrar uma data para multa e juros antes da data de vencimento?

• Não é possivel, a data para cobrança de multa só ocorre após vencimento.

O que significa valor pago e valor liquidado?

• Valor Pago: Alguns bancos permitem que os boletos no momento do pagamento sejam pagos parcialmente, caso um boleto seja pago parcialmente será possivel verificar no momento do pagamento que o valor pago é ou não condizente com o valor total do boleto, este campo é preenchido quando há o pagamento (caixas eletrônicos, lotéricas, etc) o que geralmente ocorre seguido do pagamento.

• Valor Liquidado: Este campo é preenchido quando o valor foi financeiramente liquidado, ou seja, a quantia referente ao boleto já está disponível em seu extrato bancário.

Qual tempo para compensação de um boleto?

• O tempo para compensação é de até 3 dias úteis após o pagamento do boleto, a liquidação do boleto ocorre durante a madrugada, se por acaso não houver a compensação até às 06h, o boleto será compensado no dia seguinte.

Como funciona o cadastro do webhook?

• O webhook é um serviço prestado pelo BS2 onde encaminhamos via HTTP POST as atualizaçãoes dos boletos. Para enviar os dados precisamos que nos disponibilizem uma URL para receber nossas chamadas. Caso deseje ter autenticação na sua URL, podemos enviar basic auth ou bearer token.
• Para cadastrar o webhook é necessário acionar o time comercial. Em breve disponibilizaremos rotas para o cadastro de webhook.
• Mais informações em: Webhook de Boletos

O campo "SeuNumero" tem um tamanho mínimo em termos de comprimento?

• Sim, são 10 caracteres alfanuméricos.

O cliente possui comprovante de pagamento mas não recebemos confirmação de pagamento nem a liquidação.

• Por mais que o cliente possua comprovante, existe um processo realizado de validações na CIP, orgão regulatório referente a boletos, em alguns casos o pagamento é realizado ocorre uma validação na CIP onde o valor pago é estornado ao sacado e não ocorre a liquidação do boleto. Como BS2 não temos parte neste fluxo e é necessário que o sacado verifique junto ao banco onde realizou o pagamento o porque do boleto ter sido retornado.

Quais dados preencher no campo 'Espécie'?

• Pensando em padronizar a emissão, foi criado um padrão único para o campo TituloDocEspecie, ou seja, informando algum dos códigos abaixo, ele será convertido para o padrão aceito pelo seu banco.

Existe um campo "aceite" que pode ser enviado na emissão de boleto, o que seria esse campo? O que ocorre se enviarmos como true?

• O campo 'Aceite' indica se o pagador (quem recebe o boleto) aceitou o boleto, ou seja, se ele assinou o documento de cobrança que originou o boleto. O padrão é usar Não neste campo, pois nesse caso não é necessário a autorização do Pagador para protestar o título. Se escolher Sim, o beneficiário (quem emite o boleto) precisará de algum documento onde o Pagador reconhece a dívida para poder protestar o título.

Como funcionam os campos data limite de pagamento e vencimento?

• Atualmente temos dois campos para delimitar o prazo de pagamento do boleto: vencimento e dataLimitePagamento. Caso seja realizada a emissão de um boleto hoje dia 01/04/2021 e queira definir um prazo de 30 dias para pagamento, basta definir a data de vencimento para o dia 01/05/2021. Ponto de atenção: Após a data de vencimento, o boleto ainda estará disponível para pagamento por 60 dias, caso não defina a data limite pagamento. Importante ressaltar que o boleto não estará mais disponível para pagamento em 4 dias úteis após a data definida no campo dataLimitePagamento. Para que o boleto não seja pago após a data de vencimento, basta definir o campo dataLimitePagamento com mesma data do vencimento.

Não recebi pulso de pago no webhook de boleto.

• Algumas instituições bancárias não encaminham o pulso de pago para nós, são elas : Inter, Caixa Econômica Federal, Banestes e Banco do Brasil.

Para que serve o campo ClienteId na emissão de boleto?

• O clienteId (GUID) é retornado no response da emissão do boleto. Após o primeiro boleto criado, é possível utilizar este mesmo clienteId para a emissão dos próximos boletos, não sendo necessário passar todos os dados do cliente.