Paginação, filtros e ordenação

Todo endpoint de listagem da API pública usa o mesmo contrato de paginação, os mesmos parâmetros de página e o mesmo formato de resposta. Os filtros mudam de recurso para recurso, mas seguem convenções previsíveis.

Paginação

Duas variáveis de entrada:

curl "$SUNCHAT_BASE/v1/produto?page=2&pageSize=50" \
  -H "X-Ambiente: $SUNCHAT_CONTA" \
  -H "X-Authorization: X-Chave-Api $SUNCHAT_CHAVE"

Valor fora do intervalo devolve 422 com o campo apontado. A API não corrige o número em silêncio, então pedir pageSize=500 é erro, e não 200.

Formato da resposta

A resposta é sempre um objeto com os registros em Items e os contadores ao lado. Nunca um array solto na raiz.

{
  "Items": [
    { "Id": "8f14e45f-ea6d-4a1c-9c1f-3b7d2a5e9c04", "Nome": "Camiseta branca" }
  ],
  "Page": 2,
  "PageSize": 50,
  "TotalItems": 327,
  "TotalPages": 7,
  "HasNext": true,
  "HasPrevious": true
}

Percorrendo todas as páginas

Use HasNext como condição de parada, e não uma comparação sua entre Page e TotalPages:

page=1
while :; do
  resposta=$(curl -s "$SUNCHAT_BASE/v1/produto?page=$page&pageSize=200" \
    -H "X-Ambiente: $SUNCHAT_CONTA" \
    -H "X-Authorization: X-Chave-Api $SUNCHAT_CHAVE")

  echo "$resposta" | jq -c '.Items[]'

  [ "$(echo "$resposta" | jq -r '.HasNext')" = "true" ] || break
  page=$((page + 1))
done

Filtros

Filtros vão na query string e são todos opcionais. Combiná-los aplica E lógico: ?ativo=true&search=camiseta devolve produtos ativos que também casam com "camiseta".

As convenções que se repetem em toda a API:

Parâmetro desconhecido é ignorado, sem erro. Confira o nome exato na página do endpoint, porque um filtro escrito errado não reclama: ele só não filtra, e a resposta parece boa demais.

Ordenação

O parâmetro sort recebe o nome do campo. Prefixe com - para inverter, e separe por vírgula para ordenar por mais de um campo:

?sort=nome            → nome crescente
?sort=-preco          → preço decrescente
?sort=-preco,nome     → preço decrescente e, dentro de cada preço, nome crescente

O nome do campo não diferencia maiúsculas de minúsculas.

Campos aceitos por recurso

Cada recurso aceita a sua própria lista. Campo fora dela é ignorado, e a listagem volta para a ordenação padrão.