Consultas, ordenação e filtros

Os endpoints de listagem aceitam parâmetros de consulta para controlar paginação, ordenação e filtros. Os exemplos abaixo usam oportunidades; confirme na página de cada método quais campos estão disponíveis para o recurso consultado.

Paginação

Use $limit para definir a quantidade de registros e $skip para avançar pela lista.

GET /crm/lead/lead?$limit=20&$skip=0
GET /crm/lead/lead?$limit=20&$skip=20

Quando o endpoint retornar uma resposta paginada, use $limit=0 para consultar somente a contagem total.

GET /crm/lead/lead?$limit=0

Ordenação

Use $sort[campo]=1 para ordem crescente e $sort[campo]=-1 para ordem decrescente.

GET /crm/lead/lead?$limit=20&$sort[createdAt]=-1
GET /crm/lead/lead?$limit=20&$sort[score]=-1&$sort[createdAt]=-1

Seleção de campos

Use $select[] para solicitar apenas os campos necessários e reduzir o tamanho da resposta.

GET /crm/lead/lead?$limit=20&$select[]=_id&$select[]=name&$select[]=stage&$select[]=createdAt

Igualdade e múltiplos valores

Para igualdade, informe o campo diretamente. Use $in para aceitar uma lista de valores e $nin para excluí-la.

GET /crm/lead/lead?stage=665f1f0d6b4b2f00127a0001&$limit=20
GET /crm/lead/lead?stage[$in][]=665f1f0d6b4b2f00127a0001&stage[$in][]=665f1f0d6b4b2f00127a0002&$limit=20
GET /crm/lead/lead?source[$nin][]=665f1f0d6b4b2f00127a0003&$limit=20

Comparações

Use $gt e $gte para valores maiores e $lt e $lte para valores menores.

GET /crm/lead/lead?createdAt[$gte]=2026-01-01T00:00:00.000Z&createdAt[$lte]=2026-01-31T23:59:59.999Z&$limit=20
GET /crm/lead/lead?ticket[$gte]=1000&$sort[ticket]=-1&$limit=20

Valores diferentes e condições alternativas

Use $ne para excluir um valor e $or para combinar condições alternativas.

GET /crm/lead/lead?archiveReason[$ne]=665f1f0d6b4b2f00127a0004&$limit=20
GET /crm/lead/lead?$or[0][stage]=665f1f0d6b4b2f00127a0001&$or[1][score][$gte]=80&$limit=20

Boas práticas

• Sempre use $limit ao percorrer listas.
• Ordene por um campo estável para tornar a paginação mais previsível.
• Envie datas em ISO 8601, como 2026-01-01T00:00:00.000Z.
• Prefira campos indexados e documentados no schema do endpoint.
• Considere que valores enviados pela URL chegam como texto e devem respeitar o tipo esperado pelo campo.

Próximos passos

• Consulte os limites de requisição.
• Abra os endpoints da API para conferir os campos de cada recurso.