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#
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"
{
"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,categoryoucustomer_typenão gera erro: a resposta vem comdatavazio ehas_moreafalse. - Alguns filtros booleanos validam o valor. Na caixa de entrada da equipa (
GET $BUSINESS_API/inbox),unread_onlyeinclude_archivedaceitamtrue,false,1,0,tef, e devolvem400para 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):
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).