Listar recargas de celular

Este endpoint retorna o histórico paginado de recargas de celular realizadas pela conta do parceiro autenticado, com filtros de data, ordenação e busca. Veja a Visão Geral para o fluxo completo de uma 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/cellphone/recharges

--request GET 'https://sandbox.hiperbanco.com.br/cellphone/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. Requer o escopo `transactions:read`.

Parâmetros da rota (Path / Query)

Nome	Tipo	Descrição	Especificação
`startDate`	`query`	Opcional. Data inicial da busca.	Formato `YYYY-MM-DD`.
`endDate`	`query`	Opcional. Data final da busca.	Formato `YYYY-MM-DD`.
`page`	`query`	Opcional. Página do resultado da busca.	Deve ser um número positivo.
`perPage`	`query`	Opcional. Itens por página.	Deve ser um número positivo. Máximo `100`.
`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`.
`search`	`query`	Opcional. Query de pesquisa.	—
`searchColumns`	`query`	Opcional. Colunas as quais usar para pesquisar, separadas por vírgula.	Ex.: `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 de celular encontradas.
`items[].cellPhoneNumber`	`string`	Número de celular recarregado.
`items[].areaCode`	`string`	DDD do número de celular.
`items[].authorizationCode`	`string`	Código de autorização da recarga.
`items[].message`	`string`	Mensagem descritiva do resultado da recarga.
`items[].nsu`	`string`	NSU da recarga.
`items[].amount`	`number`	Valor da recarga.
`items[].productId`	`string`	Id do produto recarregado.
`meta`	`object`	Metadados de paginação.

{
  "items": [
    {
      "cellPhoneNumber": "999999999",
      "areaCode": "71",
      "authorizationCode": "123456",
      "message": "Recharge captured successfully.",
      "nsu": "123456789",
      "amount": 10,
      "productId": "abc123"
    }
  ],
  "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
`403`	`AccessDenied`	`You do not have permission to perform this action.`	O parceiro não tem permissão para consultar as recargas.
`404`	`RechargesNotFound`	`Recharges not found.`	Nenhuma recarga de celular 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.