# Filtrar e pesquisar

Os filtros de query que cada listagem aceita, a pesquisa de texto com q, o que acontece a parâmetros desconhecidos e porque a API não tem expand.


Cada listagem da API aceita um conjunto próprio de filtros, descrito na operação correspondente da [Referência da API](/docs/api/business). O servidor aplica-os antes de paginar, por isso `has_more` e `next_cursor` referem-se sempre ao resultado já filtrado.

## Como os filtros se combinam

Todos os filtros vão na query string e combinam-se com E: um cliente só aparece se cumprir cada um deles. Os parâmetros de paginação `limit` e `after` juntam-se a qualquer filtro (veja [Paginação](/docs/getting-started/pagination)).

A listagem de clientes (`GET $BUSINESS_API/customers`, permissão `business:customers:read`) aceita:

| Parâmetro | Valores | Efeito |
| :--- | :--- | :--- |
| `q` | texto | Procura o texto no `display_name`, sem distinguir maiúsculas de minúsculas, em qualquer parte do nome. |
| `customer_type` | `individual`, `business` | Apenas clientes deste tipo. |
| `category` | `residential`, `commercial`, `industrial`, `institutional`, `government` | Apenas clientes desta categoria tarifária. |
| `status` | `active`, `suspended`, `closed` | Apenas clientes neste estado. |

Outras listagens seguem o mesmo padrão com filtros próprios. As facturas (`GET $BUSINESS_API/invoices`, permissão `invoices:read`) filtram por `customer_id`, `account_id`, `meter_id`, `reading_id`, `billing_run_id` e `status` (`draft`, `open`, `paid`, `partially_paid`, `void`, `uncollectible`), e o `q` delas procura no número da factura e nas contas cujo titular corresponde ao texto.

## Exemplo de pedido e resposta

```bash
curl -sS -G "$BUSINESS_API/customers" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "category=institutional" \
  --data-urlencode "status=active" \
  --data-urlencode "q=escola" \
  --data-urlencode "limit=10"
```

```json
{
  "data": [
    {
      "id": "cus_2kFq9AbN4yPdS8uMqX5iZc0tEfB",
      "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
      "customer_type": "business",
      "category": "institutional",
      "display_name": "Escola Primária de Malhangalene",
      "status": "active",
      "created_at": "2026-11-19T08:20:00.123456789Z",
      "updated_at": "2026-11-19T08:20:00.123456789Z"
    }
  ],
  "has_more": false
}
```

## Valores que o servidor não reconhece

- Um parâmetro de query que essa listagem não lê é ignorado. Um erro de escrita, como `stauts=active`, devolve a lista sem esse filtro em vez de um erro, por isso confirme o nome na referência.
- Na listagem de clientes, um valor fora da lista de `status`, `category` ou `customer_type` não gera erro: a resposta vem com `data` vazio e `has_more` a `false`.
- Alguns filtros booleanos validam o valor. Na caixa de entrada da equipa (`GET $BUSINESS_API/inbox`), `unread_only` e `include_archived` aceitam `true`, `false`, `1`, `0`, `t` e `f`, e devolvem `400` para qualquer outro valor.

## Sem expand

A API não tem parâmetro `expand` nem `include` para embutir objectos relacionados. Quando um nome relacionado é útil numa listagem, o próprio recurso já o traz: uma propriedade inclui `customer_name`, o nome do cliente a que pertence, e omite-o quando não é conhecido. Para o objecto completo, peça-o pelo identificador, por exemplo `GET $BUSINESS_API/customers/{id}`.

## Na linha de comandos

O comando `gotactl api` passa qualquer filtro como parâmetro de query com `-f` (parâmetro de query num GET ou campo do corpo JSON, no formato chave=valor):

```bash
gotactl api GET business:/customers -f category=institutional -f q=escola --json
```

O comando `gotactl customers list` tem `--status` (filtrar por estado) e `--limit` (número máximo de registos a devolver).

## Próximos passos

- [Percorrer as páginas de uma listagem](/docs/getting-started/pagination)
- [Ler os erros 400 e os seus códigos](/docs/getting-started/errors)
- [Automatizar consultas com a CLI](/docs/guides/automate-cli)

