Emissão de boleto

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 Pending. 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://sandbox.hiperbanco.com.br/boletos/emission

--request POST 'https://sandbox.hiperbanco.com.br/boletos/emission' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "alias": "Teste emissão de boleto",
  "account": {
    "number": "1104835921",
    "branch": "0001"
  },
  "documentNumber": "50300633859100",
  "amount": 442.96,
  "dueDate": "2025-09-20",
  "closePayment": "2025-11-20",
  "type": "Levy",
  "payer": {
    "document": "90842497552",
    "name": "Larissa Nascimento",
    "tradeName": "Larissa Nascimento",
    "address": {
      "zipCode": "76801180",
      "addressLine": "Rua Major Amarante",
      "neighborhood": "Arigolândia",
      "city": "Porto Velho",
      "state": "RO"
    }
  },
  "interest": {
    "startDate": "2025-09-21",
    "value": 73.46,
    "type": "Percent"
  },
  "fine": {
    "startDate": "2025-09-21",
    "value": 64.25,
    "type": "Percent"
  },
  "discount": {
    "limitDate": "2025-09-19",
    "value": 1.58,
    "type": "FixedPercentUntilLimitDate"
  }
}'

--request POST 'https://sandbox.hiperbanco.com.br/boletos/emission' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
    "account": {
        "number": "15164",
        "branch": "0001"
    },
    "alias": "Depósito",
    "documentNumber": "47742663023",
    "amount": 100,
    "dueDate": "2025-05-21",
    "type": "Deposit"
}'

Cabeçalhos

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)

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
alias	string	Nome para identificar o boleto externamente.
type	string	Tipo de boleto, que 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.
amount	number	Obrigatório. Valor do boleto.
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.
documentNumber	string	Obrigatório. Número do documento (CPF ou CNPJ) do beneficiário final.
payer	array	Lista de pagadores. Cada item contém informações sobre o pagador.
payer.document	string	Número do documento do pagador (CPF ou CNPJ).	Insira somente números.
payer.name	string	Nome completo do pagador.	Máximo de 60 caracteres.
payer.tradeName	string	Nome fantasia ou comercial do pagador.	Máximo de 100 caracteres.
payer.address	object	Objeto que deverá conter 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.
account	object	Obrigatório. Objeto que deverá conter informações sobre a conta do beneficiário final do boleto.
account.number	string	Obrigatório. Número da conta.
account.branch	string	Obrigatório. Número da agência.
interest	object	Objeto que deverá conter 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 deverá conter 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 .
discounts	object	Objeto que deverá conter 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.
discounts.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.
discounts.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.
discounts.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": "Teste emissão de boleto",
  "account": {
    "number": "1104835921",
    "branch": "0001"
  },
  "documentNumber": "50300633859100",
  "amount": 442.96,
  "dueDate": "2025-09-20",
  "closePayment": "2025-11-20",
  "type": "Levy",
  "payer": {
    "document": "90842497552",
    "name": "Larissa Nascimento",
    "tradeName": "Larissa Nascimento",
    "address": {
      "zipCode": "76801180",
      "addressLine": "Rua Major Amarante",
      "neighborhood": "Arigolândia",
      "city": "Porto Velho",
      "state": "RO"
    }
  },
  "interest": {
    "startDate": "2025-09-21",
    "value": 73.46,
    "type": "Percent"
  },
  "fine": {
    "startDate": "2025-09-21",
    "value": 64.25,
    "type": "Percent"
  },
  "discount": {
    "limitDate": "2025-09-19",
    "value": 1.58,
    "type": "FixedPercentUntilLimitDate"
  }
}

{
    "account": {
        "number": "15164",
        "branch": "0001"
    },
    "alias": "Depósito",
    "documentNumber": "47742663023",
    "amount": 100,
    "dueDate": "2025-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

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 200 indicará que a solicitação de emissão do boleto foi realizada 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.
`account.branch`	string	Número da agência.
`authenticationCode`	string	Identificador único do boleto.
`status`	string	Status do boleto.

{
    "account": {
        "number": "1104835921",
        "branch": "0001"
    },
    "authenticationCode": "4b712d08-9454-4940-9012-15d414e902e8",
    "status": "Processing"
}

Após a solicitação da emissão de um boleto, em background, ocorrerá o processo de registro que demora cerca de até 30 segundos. Inicialmente o status do boleto será "Processing".

📘
Nota
Recordamos que, enquanto o boleto não apresentar o status "Pending" , 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.

Erros

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 que acompanham os erros 400 (se houver).

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.