# Consultas e listagens

Consultar uma cobrança, listar com filtros e paginar resultados.

Como consultar uma cobrança específica, listar com filtros e paginar. Para saber de pagamentos *no momento em que acontecem*, use [webhooks](https://novexfinance.com.br/docs/webhooks) — esta página é para consulta sob demanda e conciliação.

## Consultar uma cobrança

`GET /v1/charges/{id}`

_Requisição_

```bash
curl https://novexfinance.com.br/api/v1/charges/ch_9f2a71c4e8b35d06a147 \
  -H "Authorization: Bearer $NOVEX_API_KEY"
```

```php
$charge = $novex->get('/charges/ch_9f2a71c4e8b35d06a147');

if ($charge['status'] === 'paid') {
    // liberar o pedido
}
```

```js
const charge = await novex.get('/charges/ch_9f2a71c4e8b35d06a147');

if (charge.status === 'paid') {
  // liberar o pedido
}
```

```python
charge = novex.get('/charges/ch_9f2a71c4e8b35d06a147')

if charge['status'] == 'paid':
    # liberar o pedido
```

> ✅ Esta consulta **reconcilia**: se a cobrança ainda não estiver num estado final, sincronizamos com o processador antes de responder. Ou seja, o que ela devolve é o estado real naquele instante — mesmo que um webhook tenha se perdido no caminho.

Cobrança inexistente, ou de outra conta, responde `404` com `resource_not_found`.

## Listar cobranças

`GET /v1/charges`

_Exemplos_

```bash
# últimas 25 (padrão)
curl https://novexfinance.com.br/api/v1/charges \
  -H "Authorization: Bearer $NOVEX_API_KEY"

# só as pagas, 50 por página
curl "https://novexfinance.com.br/api/v1/charges?status=paid&limit=50" \
  -H "Authorization: Bearer $NOVEX_API_KEY"

# só PIX pagos
curl "https://novexfinance.com.br/api/v1/charges?status=paid&payment_method=pix" \
  -H "Authorization: Bearer $NOVEX_API_KEY"

# pela sua referência
curl "https://novexfinance.com.br/api/v1/charges?reference=48219" \
  -H "Authorization: Bearer $NOVEX_API_KEY"
```

### Filtros

| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| `status` opcional | string | `pending`, `processing`, `authorized`, `paid`, `failed`, `refused`, `refunded`, `chargeback` ou `disputed`. |
| `payment_method` opcional | string | `pix`, `boleto` ou `credit_card`. |
| `reference` opcional | string | Sua referência, exata. Útil para achar a cobrança de um pedido específico. |
| `limit` opcional | inteiro | De 1 a 100. Padrão: 25. |
| `offset` opcional | inteiro | Quantos registros pular. Padrão: 0. |

_Resposta 200_

```json
{
  "object": "list",
  "data": [
    {
      "object": "charge",
      "id": "ch_9f2a71c4e8b35d06a147",
      "status": "paid",
      "amount": 12990,
      "payment_method": "pix",
      "reference": "48219",
      "net_amount": 12341,
      "paid_at": "2026-08-07T14:35:02-03:00"
    },
    // … mais cobranças
  ],
  "has_more": true,
  "limit": 25,
  "offset": 0
}
```

## Percorrer todas as páginas

Use `has_more` como condição de parada:

_Paginação completa_

```php
$offset = 0;
$todas = [];

do {
    $page = $novex->get('/charges', [
        'status' => 'paid',
        'limit'  => 100,
        'offset' => $offset,
    ]);

    $todas = array_merge($todas, $page['data']);
    $offset += 100;
} while ($page['has_more']);
```

```js
let offset = 0;
const todas = [];
let page;

do {
  page = await novex.get('/charges', {
    status: 'paid',
    limit: 100,
    offset,
  });

  todas.push(...page.data);
  offset += 100;
} while (page.has_more);
```

```python
offset, todas = 0, []

while True:
    page = novex.get('/charges', params={
        'status': 'paid',
        'limit': 100,
        'offset': offset,
    })

    todas.extend(page['data'])
    if not page['has_more']:
        break
    offset += 100
```

> ⚠️ Respeite o [limite de 300 requisições por minuto](https://novexfinance.com.br/docs/convencoes#rate-limit) ao varrer o histórico. Para conciliação diária, filtrar por `status=paid` e parar quando alcançar a data já processada é bem mais econômico do que baixar tudo toda vez.

## Consultar em laço não substitui webhook

É tentador perguntar "já pagou?" a cada poucos segundos. Não faça isso em produção:

- **Atrasa a confirmação.** Com consulta a cada 30s, o cliente espera até meio minuto por um PIX que já entrou.
- **Não escala.** Mil cobranças abertas viram milhares de requisições por minuto — e você bate no limite de uso.
- **Não é preciso.** Estados que não são finais podem mudar entre uma consulta e outra.

Cadastre um [webhook](https://novexfinance.com.br/docs/webhooks) e a confirmação chega em menos de um segundo, sem você pedir. Guarde a consulta para os casos certos: **conciliação**, **tela de detalhe do pedido** e **reprocessamento** de um webhook que o seu servidor não conseguiu receber.

## Outras consultas

| Endpoint | Devolve |
| --- | --- |
| `GET /v1/checkouts` | Checkouts hospedados criados pela API. |
| `GET /v1/checkouts/{id}` | Um checkout, com a cobrança gerada quando já foi pago. |
| `GET /v1/withdrawals` | Saques solicitados. |
| `GET /v1/balance` | Saldo disponível e a liquidar. |
| `GET /v1/webhook-deliveries` | Histórico de entregas de webhook, para depurar. |


---

Documentação completa: https://novexfinance.com.br/docs/consultas
Base da API: https://novexfinance.com.br/api/v1