Paginação

Como funciona

Toda listagem devolve { "data": [...], "nextCursor": "..." }. Para pedir a página seguinte, repita a mesma consulta com cursor=<nextCursor>. Quando nextCursor é null, você chegou ao fim.

limit define o tamanho da página: de 1 a 100, padrão 25. Um valor fora dessa faixa, ou que não seja número, responde 400 invalid_query; o valor não é ajustado em silêncio.
O cursor é opaco: não monte, não decodifique e não altere. Guarde-o exatamente como veio.
sort=campo,-campo ordena por um ou mais campos (o - inverte). Só valem os campos que cada recurso publica na referência. O desempate é sempre por id, então a ordem é estável entre páginas.

{
  "data": [
    {
      "agentId": 42,
      "answered": true,
      "assetId": 310,
      "businessUnitId": 3,
      "categoryId": 6,
      "closedAt": null,
      "code": 18342,
      "contactId": 88,
      "createdAt": "2026-01-10T12:00:00Z",
      "createdById": null,
      "customFields": [
        {
          "id": 12,
          "name": "Patrimônio",
          "type": "TEXT",
          "value": "PAT-00731"
        }
      ],
      "customerId": 15,
      "deleted": false,
      "deletedAt": null,
      "description": "<p>A impressora do financeiro não aparece na rede desde a troca do roteador.</p>",
      "followUpOfId": null,
      "id": 1042,
      "lastActivityAt": "2026-01-10T14:05:00Z",
      "mergedIntoId": null,
      "origin": "EMAIL",
      "priority": "HIGH",
      "reopened": false,
      "respondedAt": "2026-01-10T12:40:00Z",
      "serviceCatalogId": 9,
      "serviceGroupId": 4,
      "slaResponseDueAt": "2026-01-10T13:00:00Z",
      "slaResponseStatus": "FULLFILLED",
      "slaSolutionDueAt": "2026-01-10T20:00:00Z",
      "slaSolutionStatus": "WITHIN",
      "solvedAt": null,
      "stageId": 12,
      "status": "IN_PROGRESS",
      "subcategoryId": 21,
      "subject": "Impressora sem conexão",
      "tagIds": [
        1
      ],
      "ticketTypeId": 2,
      "updatedAt": "2026-01-10T14:05:00Z",
      "workflowId": 5
    }
  ],
  "nextCursor": "eyJpZCI6MTA0Mn0"
}

Cursor inválido

Mudar qualquer filtro ou a ordenação no meio da paginação invalida o cursor. Um cursor adulterado, ou emitido por outra listagem, também. A resposta é 400 invalid_cursor: recomece da primeira página, sem cursor.

{
  "code": "invalid_cursor",
  "detail": "O cursor informado é inválido ou pertence a outra consulta.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 400,
  "title": "Cursor de paginação inválido",
  "type": "https://developers.mspdesk.com.br/erros/#invalid_cursor"
}

Contar registros

Para saber o total sem percorrer as páginas, use GET /v1/tickets/count com os mesmos filtros da listagem. A contagem aceita apenas filtros: limit, cursor, sort, fields e expand não se aplicam.

Relatórios

A execução de relatório segue o mesmo padrão: GET /v1/reports/{id}/execute aceita só limit e cursor e devolve { "data": [...], "nextCursor": "..." }, uma linha por ticket, em ordem crescente de ticket. O total de linhas está em GET /v1/reports/{id}/count, e as colunas do relatório em GET /v1/reports/{id}. Qualquer outro parâmetro responde 400 invalid_query.

Sincronização incremental

Para manter uma cópia local atualizada, consulte apenas o que mudou desde a última leitura:

Ordene por lastActivityAt (sort=lastActivityAt) e filtre com filter[lastActivityAt][gte]=<último valor visto menos 5 minutos>.
Percorra todas as páginas até nextCursor ser null.
Deduplique pelo par id + lastActivityAt: a margem de 5 minutos faz o mesmo registro reaparecer, e alterações confirmadas depois da sua leitura não se perdem.
Guarde o maior lastActivityAt visto e use-o na próxima rodada.

Tickets recém-criados podem ficar alguns instantes com lastActivityAt vazio; enquanto estiver vazio, o ticket não aparece nas consultas que ordenam ou filtram por esse campo, e entra na rodada seguinte.

curl -g "https://public-api.mspdesk.com.br/v1/tickets?sort=lastActivityAt&limit=100&filter[lastActivityAt][gte]=2026-09-28T14:55:00Z" \
  -H "Authorization: Bearer $MSPDESK_API_KEY"

Os colchetes do filtro pedem -g no curl. Veja Filtros, campos e expansão para a sintaxe completa.