Pular para o conteúdo
MSP Desk para desenvolvedores

Lista os itens faturáveis de um ticket

GET
/v1/tickets/{ticketId}/billable-items
Code sample: Shell / cURL
curl --request GET \
  --url 'https://public-api.mspdesk.com.br/v1/tickets/1/billable-items?filter%5Bid%5D%5Bin%5D=1%2C2%2C3&filter%5BbillingStatus%5D%5Beq%5D=PENDING&filter%5BbillingStatus%5D%5Bin%5D=PENDING%2CINVOICED%2CCOMPLETED%2CCANCELED&filter%5BproductServiceId%5D%5Bin%5D=1%2C2%2C3&limit=25&sort=-createdAt&fields=id%2Cdescription%2Cquantity&expand=customer%2Cagent' \
  --header 'Authorization: Bearer <token>'

Escopo exigido: tickets:read. Paginação por cursor opaco (?cursor=), nunca por página/offset — use nextCursor da resposta anterior. A ordenação padrão é -createdAt (o lançamento mais novo primeiro), a mesma da aba.

createdAt é o instante do lançamento, e é a única data desta API que também ordena: ela existe em todo item, desde sempre. updatedAt só filtra — é uma coluna nova, nula no item que nunca foi alterado desde ela, e um valor nulo não serve de chave de paginação estável.

Autorizações

Seção intitulada “Authorizations”

Parâmetros

Seção intitulada “Parameters”

Parâmetros de caminho

Seção intitulada “Path Parameters”
ticketId
required
integer format: int64

ID do ticket

Exemplo
1

Parâmetros de consulta

Seção intitulada “Query Parameters”
filter[id][eq]
integer format: int64

Filtra por id igual ao valor informado.

filter[id][in]
string
Exemplo
1,2,3

Filtra por id igual a um dos valores informados, separados por vírgula (até 100).

filter[billingStatus][eq]
string
Allowed values: PENDING INVOICED COMPLETED CANCELED

Filtra por billingStatus igual ao valor informado.

filter[billingStatus][in]
string
Exemplo
PENDING,INVOICED,COMPLETED,CANCELED

Filtra por billingStatus igual a um dos valores informados, separados por vírgula (até 100).

filter[productServiceId][eq]
integer format: int64

Filtra por productServiceId igual ao valor informado.

filter[productServiceId][in]
string
Exemplo
1,2,3

Filtra por productServiceId igual a um dos valores informados, separados por vírgula (até 100).

filter[invoiceId][eq]
integer format: int64

Filtra por invoiceId igual ao valor informado.

filter[invoiceId][isNull]
boolean

Filtra por invoiceId ter ou não valor: true sem valor; false com valor.

filter[launchedByAgentId][eq]
integer format: int64

Filtra por launchedByAgentId igual ao valor informado.

filter[createdAt][gte]
string format: date-time

Filtra por createdAt maior ou igual ao valor informado.

filter[createdAt][lte]
string format: date-time

Filtra por createdAt menor ou igual ao valor informado.

filter[updatedAt][gte]
string format: date-time

Filtra por updatedAt maior ou igual ao valor informado.

filter[updatedAt][lte]
string format: date-time

Filtra por updatedAt menor ou igual ao valor informado.

limit
integer format: int32
default: 25 >= 1 <= 100

Itens por página. 1 a 100; padrão 25.

cursor
string

Cursor opaco da próxima página, devolvido em nextCursor da resposta anterior. Omita na primeira página.

sort
string

Campo de ordenação: createdAt, id (padrão -createdAt). Prefixe com - para descendente (ex.: sort=-createdAt); sempre desempatado por id na mesma direção.

Exemplo
-createdAt
fields
string

Campos de primeiro nível a retornar, separados por vírgula (id sempre volta): id, description, quantity, unitPrice, totalPrice, productServiceId, customerId, billingStatus, invoiceId, launchedByAgentId, createdAt, updatedAt.

Exemplo
id,description,quantity
expand
string

Objetos a acrescentar à resposta, separados por vírgula, até 3 por requisição: . Sem o escopo exigido de algum item pedido: 403 insufficient_scope.

Exemplo
customer,agent

Respostas

Seção intitulada “Responses”

200

Seção intitulada “200”

Página de itens faturáveis

Media typeapplication/json
object
data
Array<object>

Item faturável lançado em um ticket.

object
billingStatus

Situação de faturamento do item.

string
nullable
Allowed values: PENDING INVOICED COMPLETED CANCELED
createdAt

Instante do lançamento. Nunca é nulo.

string format: date-time
nullable
customerId

Cliente do ticket no momento do lançamento — é por ele que a fatura agrupa.

integer format: int64
nullable
description

Descrição do item. Quando o lançamento não a informa, é o nome do produto/serviço no momento do lançamento.

string
nullable
id

Identificador do item.

integer format: int64
invoiceId

Fatura em que o item entrou. Enquanto for nulo, o item se edita e se exclui por esta aba; preenchido, só pela fatura.

integer format: int64
nullable
launchedByAgentId

Agente que lançou o item. Nunca é nulo, e não muda numa edição.

integer format: int64
nullable
productServiceId

Produto/serviço do catálogo. Nulo quando o produto foi excluído do catálogo depois do lançamento: o item preserva descrição e preço, mas perde o vínculo.

integer format: int64
nullable
quantity

Quantidade lançada. Sempre maior que zero.

number
nullable
totalPrice

quantity × unitPrice, com duas casas.

number
nullable
unitPrice

Preço unitário travado no lançamento — não acompanha o catálogo.

number
nullable
updatedAt

Instante da última alteração do registro. Nulo em item anterior a esta API que nunca foi alterado desde então.

string format: date-time
nullable
nextCursor

Cursor opaco da próxima página; null quando não há mais páginas.

string
nullable
Exemplo
{
  "data": [
    {
      "billingStatus": "PENDING",
      "createdAt": "2026-01-10T13:10:00Z",
      "customerId": 15,
      "description": "Hora técnica",
      "id": 614,
      "invoiceId": null,
      "launchedByAgentId": 42,
      "productServiceId": 8,
      "quantity": 2,
      "totalPrice": 61,
      "unitPrice": 30.5,
      "updatedAt": "2026-01-10T13:10:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6MTA0Mn0"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

400

Seção intitulada “400”

Requisição malformada ou parâmetros de consulta inválidos

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

401

Seção intitulada “401”

Chave de API ausente, inválida, revogada ou expirada

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

403

Seção intitulada “403”

Acesso negado: empresa inativa (account_inactive), API pública desabilitada para a empresa (public_api_disabled), escopo liberado só com a API pública (scope_requires_public_api) ou escopo insuficiente (insufficient_scope)

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

404

Seção intitulada “404”

Recurso inexistente, de outra empresa, ou rota inexistente

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

429

Seção intitulada “429”

Limite de uso atingido (rate_limited); o campo layer indica a camada: ip, company, key, operation ou concurrency

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

Retry-After
integer format: int32

Segundos até poder repetir

500

Seção intitulada “500”

Erro interno inesperado

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo