API Cobrança
disponibiliza operações relacionadas a emissão de boletos, permitindo acompanhar o ciclo de vida de um boleto.
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.
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:
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.
É 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.
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.
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 apisecretRequest 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" }
Código | Descrição |
---|---|
200 | Success |
400 | Bad Request |
401 | Unauthorized |
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.
O webhook será disparado via uma requisição HTTP POST até que o cliente retorne com um status de sucesso (família HTTP 200).
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"
}
]
}
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 |
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 |
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 |
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!
É possível personalizarmos o logotipo que aparece no boleto?
Existe um campo para cancelamento do boleto com data prevista?
O boleto pode ser pago após o vencimento caso não possua multa e juros?
Webhook é enviado até que receba uma resposta 200. Caso a resposta seja diferente disso, qual o padrão de reenvio?
É possivel cadastrar uma data para multa e juros antes da data de 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?
Como funciona o cadastro do webhook?
O campo "SeuNumero" tem um tamanho mínimo em termos de comprimento?
O cliente possui comprovante de pagamento mas não recebemos confirmação de pagamento nem a liquidação.
Quais dados preencher no campo 'Espécie'?
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?
Como funcionam os campos data limite de pagamento e vencimento?
Não recebi pulso de pago no webhook de boleto.
Para que serve o campo ClienteId na emissão de boleto?
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 |
{- "seuNumero": "string",
- "beneficiarioFinal": {
- "razaoSocial": "string",
- "nomeFantasia": "string",
- "documento": "string"
}, - "cliente": {
- "clienteId": "60742a67-b0eb-4704-984d-020c05fd44da",
- "telefone": "string",
- "email": "string",
- "tipo": "1-Fisica",
- "documento": "string",
- "nome": "string",
- "endereco": {
- "cep": "string",
- "estado": "st",
- "cidade": "string",
- "bairro": "string",
- "logradouro": "string",
- "numero": "string",
- "complemento": "string"
}
}, - "sacadorAvalista": {
- "tipo": "1-Fisica",
- "documento": "string",
- "nome": "string",
- "endereco": {
- "cep": "string",
- "estado": "st",
- "cidade": "string",
- "bairro": "string",
- "logradouro": "string",
- "numero": "string",
- "complemento": "string"
}
}, - "vencimento": "2019-08-24T14:15:22Z",
- "valor": 0,
- "canal": "string",
- "multa": {
- "valor": 0,
- "data": "2019-08-24T14:15:22Z",
- "juros": 0
}, - "desconto": {
- "percentual": 0,
- "valorFixo": 0,
- "valorDiario": 0,
- "limite": "2019-08-24T14:15:22Z"
}, - "mensagem": {
- "linha1": "string",
- "linha2": "string",
- "linha3": "string",
- "linha4": "string"
}, - "aceite": true,
- "especie": "string",
- "dataLimitePagamento": "2019-08-24T14:15:22Z"
}
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 |
nossoNumero required | integer <int64> Nosso número do boleto. |
Solicitação.
vencimento | string or null <date-time> Nova data de vencimento. |
{- "vencimento": "2019-08-24T14:15:22Z"
}