---
agentTools:
  projectIndex: https://docs.ninepay.com.br/llms.txt
  projectSearch: https://docs.ninepay.com.br/agentSearch?query=term1%20term2
---

# Listagens e Paginação

As rotas de listagem devolvem os itens da sua empresa, do mais novo para o mais antigo, em páginas.

## Paginação

| Parâmetro | Padrão | O que faz |
| --- | --- | --- |
| `page` | `1` | A página, a partir de 1 |
| `limit` | `10` | Itens por página, de 1 a 100 |
| `sort` | `created_at` | O campo da ordenação |
| `direction` | `desc` | `asc` ou `desc` |

A resposta traz os itens em `data`, os endereços das páginas em `links` e os totais em `meta`:

```json
{
  "data": [{ "id": 315968, "name": "Maria Silva" }],
  "links": {
    "first": "https://payments.cefis.com.br/api/v1/customers?page=1",
    "last": "https://payments.cefis.com.br/api/v1/customers?page=4",
    "prev": null,
    "next": "https://payments.cefis.com.br/api/v1/customers?page=2"
  },
  "meta": { "current_page": 1, "last_page": 4, "per_page": 10, "total": 37 }
}
```

Para ler tudo, avance `page` até `meta.last_page`.

> 📘 Planos
>
> `GET /plans` só pagina quando você manda `page` ou `limit`. Sem nenhum dos dois, devolve todos os planos de uma vez, sem `links` e `meta`.

## Filtros

Os filtros que recebem lista vão repetidos na query: `status[]=active&status[]=overdue`. Os intervalos de data (`AAAA-MM-DD`) só valem com o início **e** o fim.

### `GET /customers`

| Filtro | O que faz |
| --- | --- |
| `query` | Busca no nome, e-mail, CPF ou CNPJ |
| `status[]` | `1` (ativo) ou `2` (inativo) |

### `GET /subscriptions`

| Filtro | O que faz |
| --- | --- |
| `customer_id` | As assinaturas de um cliente |
| `plan_id` | As assinaturas de um plano |
| `status[]` | `new`, `trial`, `active`, `overdue`, `paused`, `canceled` ou `expired` |
| `query` | Busca no nome, e-mail, CPF ou CNPJ do cliente, no nome do plano e nos valores do `custom_data` |
| `created_at_start` e `created_at_end` | Criadas no intervalo |
| `end_at_start` e `end_at_end` | Que terminam no intervalo |

Aceita também `sort=customer_name`, para ordenar pelo nome do cliente.

### `GET /payments`

| Filtro | O que faz |
| --- | --- |
| `subscription_id` | As faturas de uma assinatura |
| `payment_link_id` | Os pagamentos de um link de pagamento |
| `show_only_individual` | `true`: só as cobranças avulsas (sem assinatura, link ou carnê) |
| `method[]` | `credit`, `debit`, `pix` ou `billet` |
| `status[]` | `unpaid`, `paid`, `unauthorized`, `canceled` ou `reversed` |
| `query` | Busca no nome, e-mail, CPF ou CNPJ do cliente, no valor e nos dígitos do cartão |
| `created_at_start` e `created_at_end` | Criados no intervalo |
| `due_date_start` e `due_date_end` | Que vencem no intervalo |
| `paid_at_start` e `paid_at_end` | Pagos no intervalo |

As validações de cartão e o início de período de teste não aparecem na listagem de pagamentos.