Consulta por authenticationCode
O endpoint 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 (Request)
Requisição HTTP
GET https://sandbox.hiperbanco.com.br/boletos/getData/{{authenticationCode}}/{{accountBranch}}/{{accountNumber}}--request GET 'https://sandbox.hiperbanco.com.br/boletos/getData/{{authenticationCode}}/{{accountBranch}}/{{accountNumber}}' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' Cabeçalhos (Headers)
| Nome | Propriedade | Descrição |
|---|---|---|
| version | cutting-edge | Essa propriedade garante que o response da API seja retornado no formato JSON |
| Authorization | Bearer token | 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 |
|---|---|---|
| accountBranch | path | Número da agência ao qual a conta do beneficiário final do boleto pertence. |
| accountNumber | path | Número da conta do beneficiário final do boleto. |
| authenticationCode | path | Identificador único do boleto, retornado no endpoint de emissão de boletos. |
ImportanteOs campos accountBranch e accountNumber devem ser preenchidos com as informações da conta logada.
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 ISO 8601 - UTC. |
| 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. |
| account | object | Objeto que contém informações sobre a conta do beneficiário final do boleto. |
| account.number | string | Número da conta. |
| account.branch | string | Número da agência. |
| document | string | Identificador único que relaciona o boleto bancário com o beneficiário final. |
| amount | object | Objeto que contém informações sobre o valor do boleto. |
| amount.currency | string | Código da moeda com base na ISO-4217. |
| amount.value | number | Valor do boleto. |
| dueDate | string | Data de vencimento do boleto, no formato ISO 8601 - UTC. |
| closePayment | string | Data limite de pagamento após a data de vencimento. |
| emissionDate | string | Data de emissão do boleto, no formato ISO 8601 - UTC. |
| type | string | Tipo do boleto, que pode ser "Deposit" (depósito) ou "Levy" (cobrança). |
| payer | object | Objeto que contém informações sobre o pagador do boleto. Este objeto somente será retornado caso o boleto seja de cobrança (Levy). |
| payer.document | string | Número do documento (CPF ou CNPJ) do pagador. |
| payer.name | string | Nome completo do pagador. |
| payer.tradeName | string | Nome fantasia 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.neighborhood | string | Nome do bairro ou distrito. |
| payer.address.city | string | Nome da cidade. |
| payer.address.state | string | Estado (UF). |
| payer.address.zipCode | string | Código postal do endereço. |
| recipientFinal | object | Objeto que contém informações sobre o beneficiário final do boleto. |
| recipientFinal.document | string | CPF ou CNPJ do recebedor. |
| recipientFinal.name | string | Nome completo do recebedor. |
| recipientFinal.tradeName | string | Nome fantasia do recebedor. |
| recipientFinal.address | object | Endereço do recebedor. |
| recipientFinal.address.addressLine | string | Endereço do beneficiário final. |
| recipientFinal.address.neighborhood | string | Nome do bairro. |
| recipientFinal.address.city | string | Nome da cidade. |
| recipientFinal.address.state | string | Estado (UF). |
| recipientFinal.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, PIX, DCC, DigitalCorrespondentBanking). |
| payments[].paidOutDate | string | Data de pagamento, no formato ISO 8601 - UTC. |
| interest | object | Objeto que contém informações sobre os juros aplicados no boleto de cobrança (Levy). |
| interest.startDate | string | Data de início para cálculo dos juros, no formato ISO 8601 - UTC. Os juros serão aplicados a pagamentos realizados a partir da data informada nesse campo. |
| interest.type | string | Regra para cálculo dos juros. Confira a tabela com as regras referentes a juros, multas e descontos. |
| interest.value | number | Valor monetário ou percentual dos juros, dependendo da configuração do campo interest.type. |
| 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 ISO 8601 - UTC. A multa será aplicada a pagamentos realizados a partir da data informada nesse campo. |
| fine.type | string | Tipo da regra aplicada a multa. |
| fine.value | number | Valor monetário ou percentual da multa, dependendo da configuração do campo fine.type. |
| discount | object | Objeto que contém informações sobre os descontos aplicados no boleto de cobrança (Levy). |
| discount.limitDate | string | Data limite, no formato ISO 8601 - UTC, para incidência de desconto (considera-se desde a data de emissão até um dia antes do vencimento). |
| discount.value | number | Valor monetário ou percentual do desconto, dependendo da configuração do campo discount.type. |
| discount.type | string | Tipo da regra para cálculo do desconto. |
| alias | string | Apelido ou descrição da cobrança/boleto. |
NotaOs campos barcode, digitable, ournumber e document somente retornam quando o boleto apresentar o status "Registered".
{
"authenticationCode": "9748f92e-3618-4f71-a9d5-758ba1cb3275",
"barcode": "65591115700000021000000007242500777294687200",
"updatedAt": "2025-07-22T13:34:57.22+00:00",
"ourNumber": "7772946872",
"digitable": "65590000020724250077072946872008111570000002100",
"status": "Registered",
"account": {
"number": "1104714229",
"branch": "0001"
},
"document": "000007772946872",
"amount": {
"currency": "BRL",
"value": 21
},
"dueDate": "2025-07-29T03:00:00+00:00",
"closePayment": "2025-08-29T03:00:00+00:00",
"emissionDate": "2025-07-22T13:34:53.717+00:00",
"type": "Levy",
"payer": {
"document": "31280646870",
"name": "Ana Beatriz Almeida",
"tradeName": "Loja Aquarela",
"address": {
"addressLine": "Rua das Acácias, 45",
"neighborhood": "Pituba",
"city": "Salvador",
"state": "BA",
"zipCode": "41830560"
}
},
"recipientFinal": {
"document": "73379344915",
"name": "Felipe Souza Andrade",
"tradeName": "Felipe Andrade ME",
"address": {
"addressLine": "Av. Oceânica, 1200",
"neighborhood": "Rio Vermelho",
"city": "Salvador",
"state": "BA",
"zipCode": "41940470"
}
},
"payments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": 0,
"paymentChannel": "Agency",
"paidOutDate": "2023-05-17T19:45:59.465Z"
}
],
"interest": {
"startDate": "2025-07-30T03:00:00+00:00",
"type": "Percent",
"value": 5.5
},
"fine": {
"startDate": "2025-07-30T03:00:00+00:00",
"type": "Percent",
"value": 2
},
"alias": "Emissão de boleto"
}{
"authenticationCode": "94123ae2-573b-4a7f-b406-6cd71f9f6802",
"barcode": "65596115700000100000000007242500779173951400",
"updatedAt": "2025-07-22T14:06:16.979+00:00",
"ourNumber": "7791739514",
"digitable": "65590000020724250077091739514007611570000010000",
"status": "Registered",
"account": {
"number": "1104714229",
"branch": "0001"
},
"document": "000007791739514",
"amount": {
"currency": "BRL",
"value": 100
},
"dueDate": "2025-07-29T03:00:00+00:00",
"closePayment": "2025-07-29T03:00:00+00:00",
"emissionDate": "2025-07-22T14:06:12.667+00:00",
"type": "Deposit",
"payer": {
"document": "73379344915",
"name": "Bruna Carvalho Ferreira",
"tradeName": "Bruna Boutique",
"address": {
"addressLine": "Rua do Limoeiro, 98",
"neighborhood": "Barbalho",
"city": "Salvador",
"state": "BA",
"zipCode": "40301290"
}
},
"recipientFinal": {
"document": "73379344915",
"name": "Bruna Carvalho Ferreira",
"tradeName": "Bruna Boutique",
"address": {
"addressLine": "Rua do Limoeiro, 98",
"neighborhood": "Barbalho",
"city": "Salvador",
"state": "BA",
"zipCode": "40301290"
}
},
"payments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": 0,
"paymentChannel": "Agency",
"paidOutDate": "2023-05-17T19:45:59.465Z",
"createAt": "2024-02-08T21:25:25.374Z",
"updatedAt": "2024-02-08T21:25:25.374Z"
}
]
}Status do boleto
| Status | Descrição |
|---|---|
| Processed | A solicitação do boleto foi aceita e está sendo processada. |
| Registered | O boleto foi registrado na Nuclea/CIP. |
| Conciliated | O boleto foi conciliado, mas o valor ainda não está disponível na conta do emissor. |
| Settled | O boleto foi liquidado/baixado. |
| Cancelled | O boleto foi cancelado pelo beneficiário final ou por decurso do prazo. |
Regras de juros, multas e descontos
| 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. |
Erros
Este endpoint não retorna erros específicos. Porém, ele poderá retornar alguns erros comuns entre todos os endpoints.
Eventos
Este endpoint não possui eventos relacionados a ele.
Updated about 2 months ago