Filtros, campos e expansão

Filtros

Use filter[campo][operador]=valor. Vários filtros se combinam apenas com E: o registro precisa atender a todos. Não há OU entre filtros; para isso, use o operador in num mesmo campo.

Operador	Significado
eq	igual
ne	diferente
in	um de vários valores, separados por vírgula (até 100)
nin	nenhum dos valores listados
gt, gte, lt, lte	maior, maior ou igual, menor, menor ou igual
contains	contém o texto (só campos de texto)
isNull	true para sem valor, false para com valor

Nem todo campo aceita todos os operadores: contains só existe em texto, e gt, gte, lt e lte não existem em campos booleanos nem de lista fechada. Cada operação lista, na referência, os filtros que aceita.

ne e nin incluem as linhas sem valor no campo. Para excluí-las, combine com filter[campo][isNull]=false.

Um campo ou operador fora do que a operação aceita responde 400 invalid_query, com a lista aceita no detalhe do erro. Todos os erros de consulta vêm juntos na mesma resposta.

Erro 400 invalid_query

{
  "code": "invalid_query",
  "detail": "Um ou mais parâmetros de consulta são inválidos.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 400,
  "title": "Parâmetros de consulta inválidos",
  "type": "https://developers.mspdesk.com.br/erros/#invalid_query"
}

Os colchetes atrapalham o curl. Com -G e --data-urlencode, os pares vão codificados para a consulta:

curl -G "https://public-api.mspdesk.com.br/v1/tickets" \
  -H "Authorization: Bearer $MSPDESK_API_KEY" \
  --data-urlencode "filter[agentId][in]=12,15" \
  --data-urlencode "filter[subject][contains]=impressora" \
  --data-urlencode "filter[customerId][nin]=42,43"

Se você monta a URL à mão, use curl -g para ele não interpretar os colchetes.

Campos personalizados

Os campos personalizados de tickets se filtram por filter[customFields.{id}][operador], onde {id} é o identificador do campo. Os operadores aceitos dependem do tipo:

Tipo do campo	Operadores
Texto e texto longo	contains, eq, isNull
Inteiro e decimal	eq, gt, gte, lt, lte, isNull
Data e hora	gte, lte, isNull
Lista de opções	eq, in
Caixa de seleção	eq

Só valem campos personalizados da sua empresa; um identificador desconhecido é invalid_query.

Escolher os campos: fields

fields=id,subject,status devolve só esses campos (o id vem sempre) e reduz o tamanho da resposta. Um nome que o recurso não publica é invalid_query.

Expandir relacionados: expand

expand=customer,agent traz dentro do item os dados dos recursos relacionados, em vez de só o identificador. Regras:

• no máximo 3 expansões por requisição;
• cada expansão exige também o escopo de leitura do recurso de destino; sem ele, a resposta é 403 insufficient_scope. Veja Escopos;
• as expansões disponíveis de cada operação estão na descrição do parâmetro expand na referência.

Para paginar os resultados, veja Paginação.