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/invoices

--request POST 'https://sandbox.hiperbanco.com.br/boletos/invoices' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "payers": [
    {
      "document": "12345678900",
      "name": "Carlos Henrique da Silva",
      "tradeName": "API Teste Fictício",
      "email": "[email protected]",
      "address": {
        "addressLine": "Avenida Brasil, 500",
        "neighborhood": "Centro",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "zipCode": "20040000"
      }
    }
  ],
  "invoice": {
    "alias": "Emissão de boleto fictício",
    "amount": 99.90,
    "renewalCount": 0,
    "type": "Levy",
    "dueDate": "2025-07-30",
    "closePayment": "2025-08-30",
    "interest": {
      "startDate": "2025-07-31",
      "value": 3.0,
      "type": "Percent"
    },
    "fine": {
      "value": 1.5,
      "type": "Percent",
      "startDate": "2025-07-31"
    },
    "discounts": {
      "limitDate": "2025-07-29",
      "value": 5.0,
      "type": "FixedPercentUntilLimitDate"
    }
  }
}'

--request POST 'https://sandbox.hiperbanco.com.br/boletos/invoices' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "payers": [
    {
      "document": "98765432100"
    }
  ],
  "invoice": {
    "amount": 100.00,
    "dueDate": "2025-06-28",
    "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
payers	array	Lista de pagadores. Cada item contém informações sobre o pagador.
payers[].document	string	Número do documento do pagador (CPF ou CNPJ).	Insira somente números.
payers[].name	string	Nome completo do pagador.	Máximo de 60 caracteres.
payers[].tradeName	string	Nome fantasia ou comercial do pagador.	Máximo de 100 caracteres.
payers[].email	string	E-mail de contato do pagador.
payers[].address	object	Objeto que deverá conter informações sobre o endereço do pagador.
payers[].address.addressLine	string	Logradouro (nome da rua, avenida etc.).	Máximo de 60 caracteres.
payers[].address.neighborhood	string	Nome do bairro.	Máximo de 40 caracteres.
payers[].address.city	string	Nome da cidade.	Máximo de 40 caracteres.
payers[].address.state	string	Nome do estado.	Formato ISO 3166-2:BR.
payers[].address.zipCode	string	Código postal do endereço.
invoice	object	Objeto com os dados da cobrança (boleto).
invoice.alias	string	Nome para identificar o boleto externamente.
invoice.amount	number	Obrigatório. Valor do boleto.
invoice.renewalCount	number	Quantidade de boletos a serem emitidos. Caso este valor seja > 1, será gerado um boleto com vencimento mensal.
invoice.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.
invoice.dueDate	string	Obrigatório. Data de vencimento do boleto.	Formato yyyy-MM-dd.
invoice.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.
invoice.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.
invoice.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.
invoice.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.
invoice.interest.type	string	Regra para cálculo dos juros .
invoice.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.
invoice.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.
invoice.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.
invoice.fine.type	string	Tipo da regra aplicada a multa .
invoice.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.
invoice.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.
invoice.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.
invoice.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.

{
  "payers": [
    {
      "document": "12345678900",
      "name": "Carlos Henrique da Silva",
      "tradeName": "API Teste Fictício",
      "email": "[email protected]",
      "address": {
        "addressLine": "Avenida Brasil, 500",
        "neighborhood": "Centro",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "zipCode": "20040000"
      }
    }
  ],
  "invoice": {
    "alias": "Emissão de boleto fictício",
    "amount": 99.90,
    "renewalCount": 0,
    "type": "Levy",
    "dueDate": "2025-07-30",
    "closePayment": "2025-08-30",
    "interest": {
      "startDate": "2025-07-31",
      "value": 3.0,
      "type": "Percent"
    },
    "fine": {
      "value": 1.5,
      "type": "Percent",
      "startDate": "2025-07-31"
    },
    "discounts": {
      "limitDate": "2025-07-29",
      "value": 5.0,
      "type": "FixedPercentUntilLimitDate"
    }
  }
}

{
  "payers": [
    {
      "document": "73379344915"
    }
  ],
  "invoice": {
    "amount": 100,
    "dueDate": "2025-06-28",
    "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	Especificação
status	string	Status da promessa ou requisição.	fulfilled (sucesso) rejected(Error)
value	object	Objeto com os dados retornados em caso de sucesso.
value.issueId	string	Identificador único da solicitação.	Retornarar um UUID
value.message	string	Mensagem descritiva sobre o estado da solicitação.

[
    {
        "status": "fulfilled",
        "value": {
            "issueId": "ae518747-d422-4e51-b9e3-ee4882e9f4eb",
            "message": "Solicitação em processamento."
        }
    }
]

[
    {
        "status": "rejected",
        "reason": {
            "response": "CANNOT_BE_LESS_DUE_DATE",
            "status": 400,
            "message": "Data do vencimento do boleto não pode ser anterior ou igual à 'Data atual'",
            "name": "ApiCommonException",
            "devOnly": false,
            "apiErrorCode": "CANNOT_BE_LESS_DUE_DATE",
            "content": [
                "Data do vencimento do boleto",
                "Data atual"
            ]
        }
    }
]

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á "Processed".

📘
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.