Paginação e Filtros
Como paginar resultados e aplicar filtros nas listagens
Paginação
Todos os endpoints de listagem suportam paginação via query parameters:
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
page | number | 1 | Número da página (mínimo: 1) |
limit | number | 20 | Itens por página (mínimo: 1, máximo: 100) |
Exemplo
curl -X GET "https://api.payhubrasil.com.br/v1/charges?page=2&limit=10" \
-H "Authorization: Basic {credentials}"Resposta Paginada
{
"message": "Cobranças listadas com sucesso",
"data": [],
"pagination": {
"page": 2,
"limit": 10,
"total": 95,
"totalPages": 10
}
}| Campo | Tipo | Descrição |
|---|---|---|
page | number | Página atual |
limit | number | Itens por página |
total | number | Total de itens encontrados |
totalPages | number | Total de páginas disponíveis |
Filtros por Data
Muitos endpoints aceitam filtros de período:
| Parâmetro | Formato | Descrição |
|---|---|---|
date_from | YYYY-MM-DD | Data inicial do filtro |
date_to | YYYY-MM-DD | Data final do filtro |
curl -X GET "https://api.payhubrasil.com.br/v1/charges?date_from=2025-01-01&date_to=2025-01-31" \
-H "Authorization: Basic {credentials}"Filtros por Status
Cada recurso possui seus próprios status. Consulte a documentação de cada endpoint para ver os valores aceitos.
curl -X GET "https://api.payhubrasil.com.br/v1/charges?status=captured" \
-H "Authorization: Basic {credentials}"Busca por Texto
Alguns endpoints aceitam o parâmetro search para busca textual:
curl -X GET "https://api.payhubrasil.com.br/v1/charges?search=cliente@email.com" \
-H "Authorization: Basic {credentials}"Rate Limiting
A API possui limites de requisições por janela de tempo. Os limites são retornados nos headers de cada resposta:
| Header | Descrição |
|---|---|
X-RateLimit-Limit | Limite total de requisições na janela |
X-RateLimit-Remaining | Requisições restantes na janela |
X-RateLimit-Reset | Timestamp (Unix) de quando a janela reseta |
Retry-After | Segundos para aguardar (presente apenas quando excedido) |
Limites Padrão
| Categoria | Limite | Janela | Endpoints |
|---|---|---|---|
| Transações | 100 req | 60 segundos | Cobranças, saques, antecipações |
| Consultas | 200 req | 60 segundos | Carteiras, recebíveis, bancos, submerchants |
| Padrão | 100 req | 60 segundos | Demais endpoints |
Os limites podem ser personalizados por merchant. Quando o limite é excedido, a API retorna status 429 com o código RATE_LIMIT_EXCEEDED.