Listar recargas

Este endpoint retorna o histórico paginado de recargas realizadas pela conta do parceiro autenticado, com filtros de data, ordenação e busca. Veja a Visão Geral para os conceitos de produto e recarga.

Pré-requisitos

Para que seja possível utilizar este endpoint, é necessário que:

O parceiro esteja autenticado com um token válido.

Requisição (Request)

Requisição HTTP

GET https://sandbox.hiperbanco.com.br/recharges

--request GET 'https://sandbox.hiperbanco.com.br/recharges?startDate=2026-08-01&endDate=2026-08-25&page=1&perPage=10' \
--header 'version: cutting-edge' \
--header 'Authorization: Bearer {{token}}'

Cabeçalhos (Headers)

Nome	Propriedade	Descrição
`version`	`cutting-edge`	Obrigatório. 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 / Query)

Nome	Tipo	Descrição	Especificação
`startDate`	`query`	Opcional. Data inicial da busca. Se não for informado, a busca considera recargas a partir das últimas 5 horas.	Formato `YYYY-MM-DD`.
`endDate`	`query`	Opcional. Data final da busca. Só é considerado em conjunto com `startDate`.	Formato `YYYY-MM-DD`.
`page`	`query`	Opcional. Página do resultado da busca.	Padrão `1`.
`perPage`	`query`	Opcional. Itens por página.	Máximo `100`. Padrão `10`.
`orderColumn`	`query`	Opcional. Coluna da tabela pela qual ordenar os resultados da busca.	Padrão `createdAt`.
`orderDirection`	`query`	Opcional. Sentido da ordenação. Funciona apenas se `orderColumn` tiver sido especificado.	`ASC` ou `DESC`. Padrão `DESC`.
`search`	`query`	Opcional. Query de pesquisa.	—
`searchColumns`	`query`	Opcional. Colunas as quais usar para pesquisar, separadas por vírgula.	Padrão `status`.

Corpo da requisição (Body)

Não é necessário enviar campos no body desta requisição.

Resposta (Response)

O status code 200 indicará sucesso na requisição. Sendo bem-sucedido, o retorno irá trazer o seguinte campo em formato JSON:

Nome	Tipo	Descrição
`items`	`array`	Lista de recargas encontradas.
`items[].type`	`string`	Tipo do produto da recarga (atualmente sempre `cellphone`).
`items[].nsu`	`string`	NSU da recarga.
`items[].product`	`string`	Nome do produto. Presente quando não nulo na origem.
`items[].amount`	`number`	Valor da recarga.
`items[].dueDate`	`string`	Data de vencimento.
`items[].createdAt`	`Date`	Data de criação da recarga.
`items[].expiresIn`	`string`	Prazo de expiração. Pode ser vazio.
`items[].cellphoneNumber`	`string`	Número de celular recarregado, no formato "(DDD) numero".
`meta`	`object`	Metadados de paginação.
`meta.count`	`number`	Quantidade total de itens encontrados.
`meta.page`	`number`	Página atual.
`meta.perPage`	`number`	Itens por página.
`meta.totalPages`	`number`	Total de páginas.

{
  "items": [
    {
      "type": "cellphone",
      "nsu": "123456789",
      "product": "Crédito Claro R$ 10",
      "amount": 10,
      "dueDate": "2026-08-25",
      "createdAt": "2026-08-25T10:00:00.000Z",
      "expiresIn": "",
      "cellphoneNumber": "(71) 999999999"
    }
  ],
  "meta": {
    "count": 1,
    "page": 1,
    "perPage": 10,
    "totalPages": 1
  }
}

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
`404`	`RechargesNotFound`	`Recharges not found.`	Nenhuma recarga foi encontrada para os filtros informados.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints, que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.