Migrar do relatório legado

Quem é afetado

Esta página é para quem chama GET https://api.mspdesk.com.br/v1/custom-reports/integrations/{uuid}/execute com o cabeçalho X-API-key.

O endpoint novo é GET /v1/reports/{id}/execute, no host public-api.mspdesk.com.br.

O que muda

	Legado	Novo
Host	`api.mspdesk.com.br`	`public-api.mspdesk.com.br`
Caminho	`/v1/custom-reports/integrations/{uuid}/execute`	ver a referência de `executeReport`
Autenticação	`X-API-key: <chave>`	`Authorization: Bearer <chave>`
Escopo	—	`reports:read`
Limite	—	balde de relatório (ver Limites)
Erros	`404` para chave inválida/revogada/expirada/inativa, empresa inativa ou chave sem `reports:read`; `403 public_api_disabled` / `403 scope_requires_public_api` em RFC 9457 quando a empresa não tem a API habilitada nem `reports:read` liberado por concessão	RFC 9457 com `code` em todo erro (Erros)

O legado já exige o mesmo que o endpoint novo: a empresa com a API pública habilitada ou com reports:read liberado por concessão. Se o legado já responde 403 public_api_disabled ou 403 scope_requires_public_api para a sua empresa, resolva isso antes de migrar: veja Sua empresa está habilitada?.

O que muda no corpo

O endpoint novo tem outro formato. Não basta trocar o host e o cabeçalho: o código que lê a resposta também muda.

Paginação por cursor. A resposta é uma página { data, nextCursor }, uma linha por ticket, em ordem crescente de ticket. Repita a chamada com cursor=<nextCursor> até nextCursor vir null; veja Paginação. Os parâmetros aceitos são só limit e cursor: page, size ou qualquer outro respondem 400 invalid_query.
Linhas chaveadas por identificador estável. Cada valor da linha vem sob a chave (key) da coluna, não mais sob o nome de exibição. A lista de colunas, com a chave, o nome de exibição e o tipo de cada uma, está em GET /v1/reports/{id}. Toda linha traz também o ticketId.
Valores tipados. Números, booleanos, códigos de enum, datas ISO-8601 e durações em minutos vêm com o tipo próprio, não como texto formatado. Campos personalizados vêm em customFields, no mesmo formato da listagem de tickets.
Total separado. O número total de linhas está em GET /v1/reports/{id}/count, que não consome o limite de relatório.
Sem notas e apontamentos na linha. Para esses dados, use o ticketId da linha com GET /v1/tickets/{ticketId}/notes e GET /v1/tickets/{ticketId}/appointments. Essas operações exigem o escopo tickets:read: numa empresa com a API pública desabilitada cuja concessão libera só reports:read, elas respondem 403 scope_requires_public_api.

As colunas de um relatório, geradas a partir da especificação:

{
  "columns": [
    {
      "key": "ticketCode",
      "label": "Código do Ticket",
      "type": "INTEGER"
    },
    {
      "key": "ticketStatus",
      "label": "Status",
      "type": "ENUM"
    },
    {
      "key": "customFields.12",
      "label": "Contrato",
      "type": "OPTION"
    }
  ],
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Tickets por SLA"
}

Uma página de linhas:

{
  "data": [
    {
      "customFields": [
        {
          "id": 12,
          "name": "Contrato",
          "type": "DROPDOWN",
          "value": {
            "id": 7,
            "label": "Ouro"
          }
        }
      ],
      "ticketCode": 1042,
      "ticketCreatedAt": "2026-09-25T17:30:00Z",
      "ticketId": 1042,
      "ticketStatus": "IN_PROGRESS"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiaWQiLCJmIjoicmVwb3J0OmExYjIiLCJrIjpbXSwiaWQiOjEwNDJ9"
}

Os parâmetros e os campos completos estão na referência de GET /v1/reports/{id}/execute.

Avisos no legado

O endpoint legado passa a devolver o cabeçalho Link com rel="successor-version", apontando para o endpoint novo. Quando o aviso de desligamento é enviado, ele também devolve Deprecation e Sunset: a data de desligamento está no cabeçalho Sunset e no aviso da MSP Works. O prazo entre o aviso e o desligamento é de 30 dias, uma exceção descrita na política de descontinuação.

Checklist

Troque o host para public-api.mspdesk.com.br.
Troque o caminho pelo da referência de executeReport.
Troque o cabeçalho X-API-key: <chave> por Authorization: Bearer <chave>.
Confira que a chave tem o escopo reports:read.
Confira que a empresa tem a API habilitada ou reports:read liberado por concessão.
Troque a leitura por nome de coluna pela chave de GET /v1/reports/{id} e percorra as páginas com cursor.
Trate o 429 do balde de relatório: espere o Retry-After e repita. Veja Limites de uso.