Emissão de boleto

stable

Este endpoint permite que o parceiro Bankly emita boletos de depósito (Deposit) e cobrança (Levy).

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;
  • Não é possível emitir boletos das 5h25 às 6h05, pois este é o período de sincronização de nosso sistema com o fornecedor.

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:

ScopeDescrição
boleto.createConcede acesso para emitir um boleto.

Cabeçalhos

NomeDescrição
api-versionObrigatório. Versão da API, que, neste caso, é 2.0.
AuthorizationObrigató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:

NomeTipoDescriçãoEspecificação
accountobjectObrigatório. Objeto que contém informações sobre a conta do beneficiário final do boleto.
account.numberobjectObrigatório. Número da conta do beneficiário final.
account.branchstringObrigatório. Número da agência do beneficiário final.
documentNumberstringObrigatório. Número do documento (CPF ou CNPJ) do beneficiário final.Insira somente números.
amountnumberObrigatório. Valor do boleto.
minimumAmountnumberValor 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).
dueDatestringObrigatório. Data de vencimento do boleto.Formato yyyy-MM-dd.
closePaymentstringData 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.
typestringTipo 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.
aliasstringNome para identificar o boleto externamente.
payerobjectObjeto 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.documentstringNúmero do documento (CPF ou CNPJ) do pagador.Insira somente números.
payer.tradeNamestringNome fantasia do pagador.Máximo de 100 caracteres.
payer.namestringNome do pagador.Máximo de 60 caracteres.
payer.addressobjectObjeto que contém informações sobre o endereço do pagador.
payer.address.addressLinestringLogradouro (Nome da rua, avenida etc.).Máximo de 60 caracteres.
payer.address.neighborhoodstringNome do bairro. Máximo de 40 caracteres.
payer.address.citystringNome da cidade.Máximo de 40 caracteres.
payer.address.statestringNome do estado. Deve-se respeitar o formato proposto pela ISO 3166-2:BR. Exemplo: SP.
payer.address.zipCodestringCódigo postal do endereço.
interestobjectObjeto 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.startDatestringData 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.valuenumberValor 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.typestringRegra para cálculo dos juros. Confira a tabela de regras de juros, multas e descontos.
fineobjectObjeto 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.startDatestringData 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.valuenumberValor 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.typestringTipo da regra aplicada a multa. Confira a tabela de regras de juros, multas e descontos.
discountobjectObjeto 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.limitDatestringData 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.valuenumberValor 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.typestringTipo 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 closePayment será preenchido automaticamente com o valor da data de vencimento (dueDate).

Caso a data informada nos campos dueDate, closePayment, startDate ou LimitDate corresponda 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:

NomeTipoDescrição
accountobjectObjeto que contém informações sobre a conta do beneficiário final do boleto.
account.numberstringNúmero da conta do beneficiário final.
account.branchstringNúmero da agência do beneficiário final.
authenticationCodestringIdentificador ú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 codeCódigoMensagemDescrição
400INVALID_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.
400INVALID_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.
400INVALID_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.
400INVALID_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.
400INVALID_PARAMETER'Fine. Value' must be greater than 0.O valor da multa não pode ser negativo.
400INVALID_PARAMETER'Fine. Value' must be between 0 and 100. You entered XXX.O percentual da multa não pode ser maior que 100.
400INVALID_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.
400INVALID_PARAMETER'Interest.Value' must be greater than 0.O valor dos juros não pode ser negativo.
400INVALID_PARAMETER'Interest. Value' must be between 0 and 100. You entered XXX.O percentual dos juros não pode ser maior que 100.
400INVALID_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.
400INVALID_PARAMETER'Discounts. Value' must be less than or equal to 'XXX'.O valor do desconto precisa ser menor que o valor do boleto.
400INVALID_PARAMETER'Discounts. Value' must be between 0 and 100. You entered XXX.O percentual do desconto não pode ser maior que 100.
400INVALID_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.
400INVALID_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).
400INVALID_PARAMETER'Minimum Amount' must be greater than '0'.Boleto de cartão de crédito deve ter valor mínimo maior que zero.
400INVALID_PARAMETER'Payer' must not be empty.Boleto de cobrança e boleto de cartão de crédito precisam de informação do pagador.
400INVALID_PARAMETER_INVOICE_TYPEInvoice Type field is not allowed.O boleto de cartão de crédito não está disponível nessa versão.
400CUSTOMER_NOT_FOUNDCustomer document not found.O documento do cliente não foi encontrado.
400COMPANY_NOT_FOUNDCompany document not found.O documento da empresa não foi encontrado.
400ACCOUNT_NOT_FOUNDAccount not found.A conta não foi encontrada.
400ACCOUNT_WAS_CLOSEDAccount was closed.A conta foi encerrada.
400ACCOUNT_DOCUMENT_INVALIDInvalid document for this account.Documento inválido para esta conta.
400LIMIT_QUANTITY_EXCEEDEDMaximum quantity limit per month exceeded.Limite máximo de quantidade por mês excedido.
400LIMIT_MINIMUM_AMOUNTMinimum amount must be informed.Valor mínimo deve ser informado.
400LIMIT_MAXIMUM_AMOUNTMaximum amount has been exceeded.O valor máximo foi excedido.
400LIMIT_NOT_ENOUGHLimit not enough.O limite não é suficiente.
400BLOCKED_BY_RISK_ANALYSISThere was a blockage due to risk analysis.Houve um bloqueio devido à análise de risco.
400ISSUANCE_BANKSLIPS_CLOSEDBankslip issuance is not allowed at this time.Não é permitido emitir boletos no período entre 5h25 e 6h05.

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_REGISTEREDO boleto foi registrado e está apto para pagamento.