Emissão de boleto

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 5h25min às 6h05min, pois este é o período de sincronização de nosso sistema com o fornecedor.

Requisição (Request)

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, que, neste caso, é 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.	Formato ISO 3166-2:BR.
`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 .	—
`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 .	—
`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 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:

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	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.
400	ISSUANCE_BANKSLIPS_CLOSED	Bankslip 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_REGISTERED`	O boleto foi registrado e está apto para pagamento.

Emissão de boleto

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos

Parâmetros da rota (Path)

Corpo da requisição (Body)

📘
Nota

🚧
Importante

Regras de juros, multas e descontos novo

Resposta (Response)

📘
Nota

👍
Dica

Erros

Eventos

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos

Parâmetros da rota (Path)

Corpo da requisição (Body)

📘Nota

🚧Importante

Regras de juros, multas e descontos novo

Resposta (Response)

📘Nota

👍Dica

Erros

Eventos

📘
Nota

🚧
Importante

📘
Nota

👍
Dica