PT EN

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. 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).

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#