Consulta por authenticationCode
deprecated
Nota
A documentação da nova versão deste endpoint está disponível na aba v2 deste manual. Para acessá-la, basta selecionar a versão desejada (v2) no menu suspenso localizado no canto superior esquerdo da página.
A API de consulta de dados por authenticationCode retorna o status do boleto e outras informações para que o boleto possa ser gerado pelo parceiro, de forma personalizada.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- O boleto tenha sido emitido com sucesso.
Requisição
Requisição HTTP
GET https://api-mtls.sandbox.bankly.com.br/bankslip/branch/{{branch}}/number/{{number}}/{{authenticationCode}}
--location --request GET 'https://api-mtls.sandbox.bankly.com.br/bankslip/branch/{{branch}}/number/{{number}}/{{authenticationCode}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-version: 1.0' \
--header 'Authorization: Bearer {{accessToken}}
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.read | Concede acesso para consultar boletos. |
Cabeçalhos (Headers)
| Nome | Descrição |
|---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
authorization | Obrigatório. Token de autorização do tipo Bearer. |
Parâmetros da rota (Path)
No path desta requisição envie os seguintes campos:
| Nome | Tipo | Descrição |
|---|---|---|
branch | path | Número da agência da conta que está emitindo o boleto. |
number | path | Número da conta que está emitindo o boleto. |
authenticationCode | path | Identificador único do boleto, retornado na API de emissão de boletos. |
Corpo da requisição (Body)
Não é necessário enviar parâmetros no body desta requisição.
Resposta (Response)
O status code 200 indicará que a solicitação foi aceita com sucesso e trará um objeto contendo as informações do boleto.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
| Nome | Tipo | Descrição |
|---|---|---|
authenticationCode | string | Identificador único do boleto. |
barcode | string | Número do código de barras do boleto. |
updatedAt | string | Data de atualização do status do boleto, no formato YYYY-MM-DDTHH:mm:SS. |
ourNumber | string | Número que relaciona o boleto ao seu emissor. |
digitable | string | Linha digitável para pagamento do boleto. |
status | string | Situação do boleto no momento da consulta. Confira os possíveis status do boleto na tabela abaixo. |
account | object | Objeto que contém informações sobre a conta do pagador. |
account.number | string | Número da conta. |
document | string | Número do documento (CPF ou CNPJ) do pagador. |
amount | object | Objeto que contém informações sobre o valor pago. |
amount.currency | string | Código da moeda com base na ISO-4217. |
amount.value | number | Valor pago. |
minimumAmount | object | Objeto que contém informações sobre o valor mínimo pago (específico e obrigatório para boletos de cartão de crédito). |
minimumAmount.currency | string | Código da moeda com base na ISO-4217. |
minimumAmount.value | number | Valor mínimo pago. |
dueDate | string | Data de vencimento do boleto, no formato YYYY-MM-DDTHH:mm:SS. |
closePayment | string | Data limite de pagamento após a data de vencimento. |
emissionDate | string | Data de emissão do boleto, no formato YYYY-MM-DDTHH:mm:SS. |
type | string | Tipo do boleto, o qual pode ser "Deposit" (Depósito), "Levy" (Cobrança) e "Invoice" (Fatura). |
payer | object | Objeto que contém informações sobre o pagador do boleto. Este objeto só será retornado caso o boleto seja de cobrança(Levy). |
payer.document | string | Número do documento (CPF ou CNPJ) do pagador. |
payer.tradeName | string | Nome fantasia do pagador. |
payer.name | string | Nome do pagador. |
payer.address | object | Objeto que contém informações sobre o endereço do pagador. |
payer.address.addressLine | string | Endereço do pagador. |
payer.address.city | string | Nome da cidade. Deve-se evitar acentos e outros caracteres especiais. |
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. |
recipientFinal | object | Objeto que contém informações sobre o recebedor do pagamento. |
recipientFinal.document | string | Número do documento (CPF ou CNPJ) do recebedor. |
recipientFinal.tradeName | string | Nome fantasia do recebedor. |
recipientFinal.name | string | Nome do recebedor. |
recipientFinal.address | object | Objeto que contém informações sobre o endereço do recebedor. |
recipientFinal.address.addressLine | string | Endereço do recebedor. |
recipientFinal.address.city | string | Nome da cidade. Deve-se evitar acentos e outros caracteres especiais. |
recipientFinal.address.state | string | Nome do estado Deve-se respeitar o formato proposto pela ISO 3166-2:BR. Exemplo: SP. |
recipientFinal.address.zipCode | string | Código postal do endereço. |
recipientOrigin | object | Objeto que contém informações sobre o cliente que solicitou a emissão do boleto |
recipientOrigin.document | string | Número do documento (CPF ou CNPJ) do solicitante. |
recipientOrigin.tradeName | string | Nome fantasia do solicitante |
recipientOrigin.name | string | Nome do solicitante. |
recipientOrigin.address | object | Objeto que contém informações sobre o endereço do solicitante. |
recipientOrigin.address.addressLine | string | Endereço do solicitante. |
recipientOrigin.address.city | string | Nome da cidade. Deve-se evitar acentos e outros caracteres especiais. |
recipientOrigin.address.state | string | Nome do estado Deve-se respeitar o formato proposto pela ISO 3166-2:BR. Exemplo: SP. |
recipientOrigin.address.zipCode | string | Código postal do endereço. |
payments[] | array of strings | Lista de objetos contendo informações sobre os pagamentos realizados referentes ao boleto. |
payments[].id | string | Identificador único do pagamento. |
payments[].amount | number | Valor pago. |
payments[].paymentChannel | string | Nome do canal de pagamento (Agency, SelfServiceTerminal, InternetBanking, CorrespondentBanking, CallCenter, EletronicFile, DDA). |
payments[].paidOutDate | string | Data de pagamento, no formato YYYY-MM-DDTHH:mm:SS. |
interest | object | Objeto que contém informações sobre o juros aplicado no boleto de cobrança (Levy). |
interest.startDate | string | Data de início para cálculo dos juros, no formato YYYY-MM-DDTHH:mm:SS. |
interest.value | number | Valor monetário ou percentual dos juros, dependendo da configuração do campo interest.type. |
interest.type | string | Regra para cálculo dos juros. Confira as possíveis regras referentes a juros na tabela abaixo. |
fine | object | Objeto que contém informações sobre a multa aplicada no boleto de cobrança (Levy). |
fine.startDate | string | Data de início para cálculo da multa, no formato YYYY-MM-DDTHH:mm:SS. |
fine.value | number | Valor monetário ou percentual da multa, dependendo da configuração do campo fine.type. |
fine.type | string | Tipo da regra aplicada a multa. Confira as possíveis regras referentes a multa na tabela abaixo. |
discounts | object | Objeto que contém informações sobre os descontos aplicados no boleto de cobrança (Levy). |
discounts.limitDate | string | Data limite, no formato YYYY-MM-DDTHH:mm:SS, para incidência de desconto (considera-se desde a data de emissão até um dia antes do vencimento). |
discounts.value | number | Valor monetário ou percentual do desconto, dependendo da configuração do campo discounts.type. |
discounts.type | string | Tipo da regra para cálculo do desconto. Confira as possíveis regras referentes a descontos na tabela abaixo. |
{
"authenticationCode": "5566165e-51fb-459b-a31c-1e996165280b",
"barcode": "33297940700000001000001115801398869900725986",
"updatedAt": "2022-02-14T17:49:28.518+00:00",
"ourNumber": "44696851879",
"digitable": "33290001151446968518579001874704188970000002000",
"status": "Registered",
"account": {
"number": "15164"
},
"document": "47742663023",
"amount": {
"currency": "BRL",
"value": 20
},
"minimumAmount": {
"currency": "BRL",
"value": 1
},
"dueDate": "2022-02-15T03:00:00+00:00",
"closePayment": "2023-07-10T03:00:00+00:00",
"emissionDate": "2022-02-14T17:49:28.802+00:00",
"type": "Deposit",
"payer": {
"document": "47742663023",
"name": "Nísia Floresta",
"tradeName": "",
"address": {
"addressLine": "Rua 6 de Março",
"city": "Santarém",
"state": "PA",
"zipCode": "68060100"
}
},
"recipientFinal": {
"document": "09992220074",
"name": "Maria Quitéria de Jesus",
"tradeName": "",
"address": {
"addressLine": "Rua 6 de Março",
"city": "Santarém",
"state": "PA",
"zipCode": "68060100"
}
},
"recipientOrigin": {
"document": "09992220074",
"name": "Maria Quitéria de Jesus",
"tradeName": "",
"address": {
"addressLine": "Rua 6 de Março",
"city": "Santarém",
"state": "PA",
"zipCode": "68060100"
}
},
"payments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": 0,
"paymentChannel": "Agency",
"paidOutDate": "2023-05-17T19:45:59.465Z"
}
],
"interest": {
"startDate": "0001-01-02T23:59:59-03:06",
"value": 0,
"type": "Free"
},
"fine": {
"startDate": "0001-01-02T23:59:59-03:06",
"value": 0,
"type": "Free"
},
"discounts": {
"limitDate": "0001-01-02T23:59:59-03:06",
"value": 0,
"type": "Free"
}
}
Status do boleto
| Nome | Descrição |
|---|---|
| Processed | A solicitação do boleto foi aceita e está sendo processada. |
| Registered | O boleto foi registrado na CIP. |
| MarkedConciliation | Ocorrência de erro no processo de conciliação. Geralmente isso acontece quando há algum problema com a conta do emissor, sendo necessária uma análise manual. |
| Conciliation | O boleto foi conciliado, mas o valor ainda não está disponível na conta do emissor. |
| Settled | O boleto foi liquidado/baixado. |
| CancelledByRecipient | O boleto foi cancelado pelo emissor. |
| CancelledByDeadLine | O boleto foi cancelado por decurso do prazo. |
| BlockedForPayment | O boleto está bloqueado para pagamento. |
| UnfitBeneficiary | O beneficiário do boleto está inapto. |
Importante
Caso o status Accepted seja retornado, considerar como Processed. Caso retorne o status Cancelled, considerar como CancelledByRecipient ou CancelledByDeadLine.
Regras de juros, multa e descontos
| Juros (Interest) | Multa (Fine) | Descontos (Discounts) |
|---|---|---|
| AmountPerCalendaryDay: valor monetário por dia corrido (sem distinção de fins de semana e feriados). Esse campo aceita apenas números inteiros. | FixedAmount: valor monetário fixo. | FixedAmountUntilLimitDate: valor fixo até a data limite |
| PercentPerMonth: percentual ao mês. | Percent: percentual sobre o valor do título. | FixedPercentUntilLimitDate: percentual fixo até a data limite. |
| Free: indica a não incidência de juros no boleto. | Free: indica a não incidência de multa. | Free: indica que não há incidência de desconto no boleto. |
| AmountPerBusinessDay: valor monetário por dia útil. | --- | --- |
| PercentPerMonthBusinessDay: percentual ao mês (considerando apenas os dias úteis). | --- | --- |
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:
| Satus code | Código | Descrição |
|---|---|---|
| 400 | PERSIST_REQUEST_INVALID | Agência ou conta incorreta. |
| 404 | BANKSLIP_NOT_FOUND | Boleto não encontrado. |
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 (se houver).
Eventos
Este endpoint não possui eventos relacionados a ele.
Updated 4 months ago