Cobrança

Download OpenAPI specification:Download

Introdução Cobrança

O que é API de Cobrança ?

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

Quem pode usar a API de Cobrança

Todos os clientes e parceiros do banco BS2.

Quais são requisitos para a utilização da API de Cobrança ?

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

Endereços das nossas APIS

Beneficiário Final

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)

image

Autenticação

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.

image

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.

image

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.

image

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

Código Descrição
200 Success
400 Bad Request
401 Unauthorized

Webhook - Notificações

Webhook de Boletos

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:

Campo Descrição
Id Código único da notificação
DataNotificacao Data do disparo do webhook ao parceiro
NossoNumeroBoleto Define o valor do campo nosso número do boleto.
SeuNumeroBoleto Campo seu número enviado no momento da criação do boleto.
Valor Valor do boleto. O valor pago pode ser diferente (multa/desconto).
ValorLiquidado Informa o valor que foi pago pelo cliente, se o boleto tiver sido pago.
StatusBoleto Matriz com o histórico de status do boleto [Vide tabela abaixo]
Situacao Situação do boleto [Vide tabela abaixo]
SituacaoDescricao Descrição da situação do boleto

Códigos de Situação

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

Situação Descrição
1 Boleto em aberto - A vencer
2 Boleto em aberto - Vencido
3 Boleto Cancelado / Baixado
4 Boleto Liquidado / Compensado

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

Campo Descrição
Status Código do status - evento [Vide tabela abaixo]
Descricao Descrição do status
DataStatus Data em que o fato ocorreu

Códigos de Status

Abaixo seguem os eventos informados atualmente e seu significado:

Status Descrição
1 Boleto Registrado junto ao órgão responsável - CIP
2 Identificado pagamento do boleto na rede bancária (*)
3 Boleto liquidado/compensado - crédito feito na CC (*)
4 Boleto cancelado/baixado (sem movimentação financeira)

(*) 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!

Dúvidas Frequentes

É 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.

Boletos

Emissão e registro do boleto na CIP.

Request Body schema:

Criar do boleto simplificado

seuNumero
string or null

Campo para definição de número para o boleto à escolha do cliente, aceita apenas números e letras. Não é obrigatório! Em caso de não enviar, geramos uma numeração automática para este campo em nossa camada do BS2

object (swagger_cobranca.bs2.pj.cobranca.boletos.v2.criarBoletoSimplificadoV2.BeneficiarioFinal)

Dono do produto e/ou serviço oferecido.

required
object (swagger_cobranca.bs2.pj.cobranca.boletos.v2.criarBoletoSimplificadoV2.Cliente)

ClienteDto para criação de Boleto Simplificado V2

object (swagger_cobranca.bs2.pj.cobranca.boletos.compartilhados.SacadorAvalista)

Sacador/Avalista não são obrigatórios, mas uma vez que se informe o CPF/CNPJ do mesmo, é preciso que informe os demais dados do Avalista.

vencimento
required
string <date-time>

Data de vencimento do boleto, deverá ser maior ou igual que a data atual. Exemplo: 2019-03-28

valor
required
number <double>

Valor da cobrança original

canal
string or null

Caso o boleto possua beneficiário final, informar neste campo.

object (swagger_cobranca.bs2.pj.cobranca.boletos.compartilhados.Multa)

Multas e juros do boleto

object (swagger_cobranca.bs2.pj.cobranca.boletos.compartilhados.Desconto)

DescontoDto

object (swagger_cobranca.bs2.pj.cobranca.boletos.compartilhados.Mensagem)

MensagemDto

aceite
boolean or null

Campo para definição de aceite do boleto para casos de protesto do título

especie
string or null

Espécie do Boleto – Ex: 01 (Duplicata Mercantil)

dataLimitePagamento
string or null <date-time>

Data limite para pagamento

Responses

Request samples

Content type
{
  • "seuNumero": "string",
  • "beneficiarioFinal": {
    },
  • "cliente": {
    },
  • "sacadorAvalista": {
    },
  • "vencimento": "2019-08-24T14:15:22Z",
  • "valor": 0,
  • "canal": "string",
  • "multa": {
    },
  • "desconto": {
    },
  • "mensagem": {
    },
  • "aceite": true,
  • "especie": "string",
  • "dataLimitePagamento": "2019-08-24T14:15:22Z"
}

Response samples

Content type
No sample

Realiza a busca de boletos gerados a partir de uma série de filtros.

query Parameters
inicio
integer or null <int64>

Página dos registros

limite
integer or null <int64>

Quantidade de registros (MÁXIMO 100)

emissaoInicial
string or null <date-time>

Data início de emissão do boleto

emissaoFinal
string or null <date-time>

Data final de emissão do boleto

vencimentoInicial
string or null <date-time>

Data início de vencimento do boleto

vencimentoFinal
string or null <date-time>

Data final de vencimento do boleto

status
integer <int32> (swagger_cobranca.bs2.pJ.domain.cobranca.models.boletos.avulso.boletoAggregate.StatusBoleto)
Enum: "1-Aberto" "2-Vencido" "3-Cancelado" "4-Pago"

Status do boleto

documentoSacado
string or null

Cpf ou Cnpj do sacado

canal
string or null

Apelido para identificação do Beneficiário

seuNumero
string or null

Seu número do boleto

nossoNumero
integer or null <int64>

Nosso número do boleto

Responses

Response samples

Content type
No sample

Obtém detalhe do boleto pelo código de identificação.

path Parameters
boletoId
required
string <uuid>

Código do boleto. Exemplo: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Responses

Response samples

Content type
No sample

Obtém detalhe do boleto pelo campo nosso numero

path Parameters
nossoNumero
required
integer <int64>

Nosso número do boleto. Exemplo: 123456789

Responses

Response samples

Content type
No sample

Obtém boleto imprimível pelo código de identificação.

path Parameters
boletoId
required
string <uuid>

Código do boleto. Exemplo: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Responses

Response samples

Content type
No sample

Obtém boleto imprimível pelo campo nosso número.

path Parameters
nossoNumero
required
integer <int64>

Nosso número do boleto. Exemplo: 123456789

Responses

Response samples

Content type
No sample

Solicita novo vencimento do boleto pelo nosso número.

path Parameters
nossoNumero
required
integer <int64>

Nosso número do boleto.

Request Body schema:

Solicitação.

vencimento
string or null <date-time>

Nova data de vencimento.

Responses

Request samples

Content type
{
  • "vencimento": "2019-08-24T14:15:22Z"
}

Response samples

Content type
No sample

Solicita novo vencimento do boleto pelo código identificador.

path Parameters
boletoId
required
string <uuid>

The boleto identifier.

Request Body schema:

The nova solicitacao.

vencimento