Emissão de boleto
stable
Este endpoint permite que o parceiro Bankly emita boletos de depósito (Deposit) e cobrança (Levy).
Importante
Recordamos que, para que seja possível utilizar o boleto emitido (gerar o PDF, realizar cancelamento, pagamento etc.) , é necessário que ele apresente o status Registered. Portanto, é preciso aguardar o evento BOLETO_WAS_REGISTERED.
Requisição
Requisição HTTP
POST https://api-mtls.sandbox.bankly.com.br/bankslip
--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/bankslip' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-version: 2.0' \
--header 'Authorization: Bearer {{Token}} ' \
--data-raw
'{
"alias": "Boleto da compra dos livros",
"account": {
"number": "15164",
"branch": "0001"
},
"documentNumber": "47742663023",
"amount": 100,
"minimumAmount": 0,
"dueDate": "2023-10-27",
"closePayment": "2023-10-27",
"type": "Levy",
"payer": {
"document": "47742663023",
"name": "Editora Nísia Floresta",
"tradeName": "Editora Floresta",
"address": {
"addressLine": "Rua 6 de Março",
"neighborhood": "Alter do Chão",
"city": "Santarém",
"state": "PA",
"zipCode": "68060100"
}
},
"interest": {
"startDate": "2023-10-27",
"type": "FixedAmount",
"value": 0
},
"fine": {
"startDate": "2023-10-27",
"type": "FixedAmount",
"value": 0
},
"discount": {
"limitDate": "2023-10-27",
"type": "Percent",
"value": 0
}
}'
--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/bankslip' \
--header 'Accept: application/json' \
--header 'api-version: 2.0' \
--header 'Authorization: Bearer {{Token}}' \
--header 'Content-Type: application/json' \
--data-raw '
{
"account": {
"number": "15164",
"branch": "0001"
},
"alias": "Depósito",
"documentNumber": "47742663023",
"amount": 100,
"dueDate": "2024-05-21",
"type": "Deposit"
}'
Autorização
Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:
| Scope | Descrição |
|---|---|
boleto.create | Concede acesso para emitir um boleto. |
Cabeçalhos
| Nome | Descrição |
|---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 2.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
Parâmetros da rota (Path)
Não é necessário enviar campos no path desta requisição.
Corpo da requisição (Body)
No body, envie os seguintes campos em formato JSON:
| Nome | Tipo | Descrição | Especificação |
|---|---|---|---|
account | object | Obrigatório. Objeto que contém informações sobre a conta do beneficiário final do boleto. | — |
account.number | object | Obrigatório. Número da conta do beneficiário final. | — |
account.branch | string | Obrigatório. Número da agência do beneficiário final. | — |
documentNumber | string | Obrigatório. Número do documento (CPF ou CNPJ) do beneficiário final. | Insira somente números. |
amount | number | Obrigatório. Valor do boleto. | — |
minimumAmount | number | Valor mínimo do pagamento do boleto (específico e obrigatório para boletos de cartão de crédito (Invoice)). Importante: Este campo não deve ser preenchido em caso de boletos do tipo de Depósito (Deposit) e Cobrança (Levy). | — |
dueDate | string | Obrigatório. Data de vencimento do boleto. | Formato yyyy-MM-dd. |
closePayment | string | Data limite para o pagamento do boleto após o seu vencimento. Esse campo é de preenchimento obrigatório para a aplicação de juros e/ou multas. Em caso de juros, o valor informado nesse campo corresponde à data em que os juros param de incidir sobre o valor do boleto. | Formato yyyy-MM-dd. |
type | string | Tipo de boleto, o qual pode ser "Deposit" (boleto de depósito) e, "Levy" (boleto de cobrança). Caso o campo type não seja especificado, nosso sistema gerará um boleto de depósito (Deposit) e vai desconsiderar as informações do pagador, assim como os campos referentes a juros, multas e desconto. | — |
alias | string | Nome para identificar o boleto externamente. | — |
payer | object | Objeto que contém informações sobre o pagador, que devem ser preenchidas obrigatoriamente na emissão de boleto de cobrança (Levy) . Somente nesse caso os dados são considerados. | — |
payer.document | string | Número do documento (CPF ou CNPJ) do pagador. | Insira somente números. |
payer.tradeName | string | Nome fantasia do pagador. | Máximo de 100 caracteres. |
payer.name | string | Nome do pagador. | Máximo de 60 caracteres. |
payer.address | object | Objeto que contém informações sobre o endereço do pagador. | |
payer.address.addressLine | string | Logradouro (Nome da rua, avenida etc.). | Máximo de 60 caracteres. |
payer.address.neighborhood | string | Nome do bairro. | Máximo de 40 caracteres. |
payer.address.city | string | Nome da cidade. | Máximo de 40 caracteres. |
payer.address.state | string | Nome do estado. Deve-se respeitar o formato proposto pela ISO 3166-2:BR. Exemplo: SP. | — |
payer.address.zipCode | string | Código postal do endereço. | — |
interest | object | Objeto que contém informações sobre o juros aplicado no boleto de cobrança (Levy). Este objeto somente é obrigatório para especificações da incidência de juros após o vencimento. Caso esse objeto não seja preenchido, considera-se que não há incidência de juros no boleto. | — |
interest.startDate | string | Data de início para cálculo dos juros. Os juros serão aplicados a pagamentos realizados a partir da data informada nesse campo. | Formato yyyy-MM-dd. |
interest.value | number | Valor monetário ou percentual dos juros, dependendo da configuração do campo interest.type. | Quando o campo interest.type apresentar o valor "FixedAmount", o campo aceitará valores com até duas casas decimais. Em caso de "Percent", o valor máximo é 100. |
interest.type | string | Regra para cálculo dos juros. Confira a tabela de regras de juros, multas e descontos. | — |
fine | object | Objeto que contém informações sobre a multa aplicada no boleto de cobrança (Levy). Este objeto somente é obrigatório para especificações da incidência de multa após vencimento. Caso esse objeto não seja preenchido, considera-se que não há incidência de multa no boleto. | — |
fine.startDate | string | Data de início para cálculo da multa. A multa será aplicada a pagamentos realizados a partir da data informada nesse campo. | Formato yyyy-MM-dd. |
fine.value | number | Valor monetário ou percentual da multa, dependendo da configuração do campo fine.type. | Quando o tipo de multa for "Percent", o valor máximo é 100. |
fine.type | string | Tipo da regra aplicada a multa. Confira a tabela de regras de juros, multas e descontos. | — |
discount | object | Objeto que contém informações sobre os descontos aplicados no boleto de cobrança (Levy). Este objeto somente é obrigatório para especificações da incidência de descontos para pagamento em até um dia antes da data de vencimento. Caso esse objeto não seja preenchido, considera-se que não há incidência de descontos no boleto. | — |
discount.limitDate | string | Data limite para incidência de desconto (considera-se desde a data de emissão até um dia antes do vencimento). | Formato yyyy-MM-dd. |
discount.value | number | Valor monetário ou percentual do desconto, dependendo da configuração do campo discounts.type. | Quando o tipo de desconto for "FixedPercentUntilLimitDate", o valor máximo é 100. |
discount.type | string | Tipo da regra para cálculo do desconto. Confira a tabela de regras de juros, multas e descontos. | — |
Nota
É possível aplicar juros e multa ao mesmo título.
{
"alias": "Boleto da compra dos livros",
"account": {
"number": "15164",
"branch": "0001"
},
"documentNumber": "47742663023",
"amount": 100,
"minimumAmount": 40,
"dueDate": "2023-10-27",
"closePayment": "2023-10-27",
"type": "Levy",
"payer": {
"document": "47742663023",
"name": "Editora Nísia Floresta",
"tradeName": "Editora Floresta",
"address": {
"addressLine": "Rua 6 de Março",
"neighborhood": "Alter do Chão",
"city": "Santarém",
"state": "PA",
"zipCode": "68060100"
}
},
"interest": {
"startDate": "2023-10-27",
"type": "FixedAmount",
"value": 0
},
"fine": {
"startDate": "2023-10-27",
"type": "FixedAmount",
"value": 0
},
"discount": {
"limitDate": "2023-10-27",
"type": "Percent",
"value": 0
}
}
{
"account": {
"number": "15164",
"branch": "0001"
},
"alias": "Depósito",
"documentNumber": "47742663023",
"amount": 100,
"dueDate": "2024-05-21",
"type": "Deposit"
}
Importante
Se o boleto não possuir juros ou multa, o campo
closePaymentserá preenchido automaticamente com o valor da data de vencimento (dueDate).Caso a data informada nos campos
dueDate,closePayment,startDateouLimitDatecorresponda a um dia de final de semana ou feriado, o boleto estará apto para pagamento no próximo dia útil.
Regras de juros, multas e descontos novo
| Juros (Interest) | Multa (Fine) | Desconto (Discount) |
|---|---|---|
| FixedAmount: valor monetário por dia corrido (sem distinção de fins de semana e feriados). Esse campo aceita valores com até duas casas decimais. | FixedAmount: valor monetário fixo. | FixedAmountUntilLimitDate: valor fixo até a data limite |
| Percent: valor percentual por dia corrido (sem distinção de fins de semana e feriados). | Percent: percentual sobre o valor do título. | FixedPercentUntilLimitDate: percentual fixo até a data limite. |
Resposta (Response)
O status code 202 indicará que o boleto foi emitido com sucesso.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
| Nome | Tipo | Descrição |
|---|---|---|
account | object | Objeto que contém informações sobre a conta do beneficiário final do boleto. |
account.number | string | Número da conta do beneficiário final. |
account.branch | string | Número da agência do beneficiário final. |
authenticationCode | string | Identificador único do boleto. |
{
"account": {
"number": "string",
"branch": "string"
},
"authenticationCode": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Após a solicitação da emissão de um boleto, em background, ocorrerá o processo de registro que demora cerca de 10 segundos. Inicialmente o status do boleto será "Processed".
Nota
Recordamos que, enquanto o boleto não apresentar o status "Registered" (registrado), não será possível efetuar seu pagamento, emitir o PDF ou realizar seu cancelamento. Recomendamos consultar o status do boleto ou aguardar o envio do evento de webhook de registro (BOLETO_WAS_REGISTERED) para dar continuidade ao processo de emissão.
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint pode retornar erros específicos, conforme a tabela a seguir:
| Status code | Código | Mensagem | Descrição |
|---|---|---|---|
| 400 | INVALID_PARAMETER | 'Close Payment' must be greater than or equal to 'dd/mm/aaaa 00:00:00.' | A data limite de pagamento precisa ser maior ou igual à data de vencimento. A mensagem de erro trará a data de vencimento somada a um dia. |
| 400 | INVALID_PARAMETER | 'Close Payment' must be greater than or equal to 'dd/mm/aaaa 00:00:00.' | A data limite de pagamento precisa ser maior que a data de início de aplicação dos juros. |
| 400 | INVALID_PARAMETER | 'Close Payment' must be greater than or equal to 'dd/mm/aaaa 00:00:00.' | A data limite de pagamento precisa ser maior que a data de início de aplicação da multa. |
| 400 | INVALID_PARAMETER | 'Fine. Start Date' must be greater than or equal to 'dd/mm/aaaa 00:00:00.' | A data de início de aplicação da multa precisa ser maior que a data de vencimento. |
| 400 | INVALID_PARAMETER | 'Fine. Value' must be greater than 0. | O valor da multa não pode ser negativo. |
| 400 | INVALID_PARAMETER | 'Fine. Value' must be between 0 and 100. You entered XXX. | O percentual da multa não pode ser maior que 100. |
| 400 | INVALID_PARAMETER | 'Interest. Start Date' must be greater than or equal to 'dd/mm/aaaa 00:00:00.' | A data de início de aplicação dos juros precisa ser maior que a data de vencimento. |
| 400 | INVALID_PARAMETER | 'Interest.Value' must be greater than 0. | O valor dos juros não pode ser negativo. |
| 400 | INVALID_PARAMETER | 'Interest. Value' must be between 0 and 100. You entered XXX. | O percentual dos juros não pode ser maior que 100. |
| 400 | INVALID_PARAMETER | 'Discounts. Limit Date' must be less than or equal to 'dd/mm/aaaa 00:00:00.' | A data limite de desconto precisa ser inferior à data de vencimento. |
| 400 | INVALID_PARAMETER | 'Discounts. Value' must be less than or equal to 'XXX'. | O valor do desconto precisa ser menor que o valor do boleto. |
| 400 | INVALID_PARAMETER | 'Discounts. Value' must be between 0 and 100. You entered XXX. | O percentual do desconto não pode ser maior que 100. |
| 400 | INVALID_PARAMETER | 'Minimum Amount' must be less than or equal to X. | Valor mínimo do boleto de cartão de crédito deve ser menor que o valor do boleto. |
| 400 | INVALID_PARAMETER | 'Minimum Amount' must be equal to '0'. | Boleto de depósito ou cobrança não deve ter valor mínimo (ou deve ser igual a zero). |
| 400 | INVALID_PARAMETER | 'Minimum Amount' must be greater than '0'. | Boleto de cartão de crédito deve ter valor mínimo maior que zero. |
| 400 | INVALID_PARAMETER | 'Payer' must not be empty. | Boleto de cobrança e boleto de cartão de crédito precisam de informação do pagador. |
| 400 | INVALID_PARAMETER_INVOICE_TYPE | Invoice Type field is not allowed. | O boleto de cartão de crédito não está disponível nessa versão. |
| 400 | CUSTOMER_NOT_FOUND | Customer document not found. | O documento do cliente não foi encontrado. |
| 400 | COMPANY_NOT_FOUND | Company document not found. | O documento da empresa não foi encontrado. |
| 400 | ACCOUNT_NOT_FOUND | Account not found. | A conta não foi encontrada. |
| 400 | ACCOUNT_WAS_CLOSED | Account was closed. | A conta foi encerrada. |
| 400 | ACCOUNT_DOCUMENT_INVALID | Invalid document for this account. | Documento inválido para esta conta. |
| 400 | LIMIT_QUANTITY_EXCEEDED | Maximum quantity limit per month exceeded. | Limite máximo de quantidade por mês excedido. |
| 400 | LIMIT_MINIMUM_AMOUNT | Minimum amount must be informed. | Valor mínimo deve ser informado. |
| 400 | LIMIT_MAXIMUM_AMOUNT | Maximum amount has been exceeded. | O valor máximo foi excedido. |
| 400 | LIMIT_NOT_ENOUGH | Limit not enough. | O limite não é suficiente. |
| 400 | BLOCKED_BY_RISK_ANALYSIS | There was a blockage due to risk analysis. | Houve um bloqueio devido à análise de risco. |
Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400.
Eventos
Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:
Nome do evento (name) | Descrição |
|---|---|
BOLETO_WAS_REGISTERED | O boleto foi registrado e está apto para pagamento. |
Updated about 1 month ago