Paginação e limites

limit e offset

As listagens paginam com dois parâmetros de consulta: limit, a quantidade de registros por página, e offset, quantos registros pular. As listagens de pedidos e de contratos vêm do mais recente para o mais antigo.

O valor padrão e o teto de limit mudam por endpoint. Acima do teto vale o teto, sem erro.

Filtros de data nos pedidos

As listagens de pedidos aceitam createdFrom, createdTo, updatedFrom e updatedTo, em ISO-8601, e o filtro status, que pode ser repetido. É o que permite uma consulta incremental: pedir só o que mudou desde a última leitura.

O fim da lista nem sempre é uma página vazia

Três comportamentos documentados na coleção fogem do padrão e precisam de tratamento próprio.

• Pedidos: sem resultado, a resposta é um array vazio.
• Saldo de cashback por cliente: não existe página vazia. Quando o offset passa do último lançamento, a resposta é 400 com no record found, e é esse 400 que encerra a paginação.
• Limites de crédito: com resultado a resposta é um array; sem nenhum, é um objeto vazio. Iterar direto sobre a resposta quebra no caso vazio.

Tamanho de lote

Há duas rotas para enviar estoque e preço em lote. As duas coexistem, e cada uma serve a um ritmo.

• PUT /v1/stock/batch: de 1 a 50 itens por requisição, com o resultado de cada item na resposta. É a rota da atualização contínua. Lote vazio ou acima de 50 itens é recusado com 422.
• POST /api/v1/stocks/batch: até 200 itens por requisição, processados em fila assíncrona. É a rota da carga grande. Ela não está na coleção pública, por isso não tem página de referência nesta área.

Fonte da segunda rota: base de conhecimento da CWS Platform, confirmada pelo time de tecnologia em 06/10/2026.

Limite de requisições

A coleção pública não publica limite de requisições por período. Se o desenho da sua integração depende desse número, confirme com o time de integração em suporte-api@cws.digital antes de dimensionar a carga.