As nossas API's permitem até 10 requisições por minuto. Para aumentar esse limite, entre em contato com o suporte. Saiba mais sobre horários e limites das API's.

⚠️Atenção: Na API de Tickets, após 3 requisições com erro, o código 429 - Too many failed requests será retornado, bloqueando requisições por 60 segundos. Esse tempo sobra após mais 3 erros consecutivos. O tempo de espera está no parâmetro retry-after do header da resposta.

https://api.movidesk.com/public/v1

Tickets

 URL:    /tickets
 Métodos: GET / POST / PATCH

Tickets/Past

 URL:    /tickets/past
 Métodos: GET

⚠️Atenção: A rota  /tickets traz os tickets com a data de atualização (lastupdate) inferior a 90 dias. Tickets que possuem uma data de atualização mais antiga devem ser buscados na rota /tickets/past.  A quantidade máxima de retorno em um GET de lista de tickets será de 100 tickets por página.

Layout

ticket

⚠️ Atenção: As APIs de atendimento de suporte podem demorar alguns minutos para atualizar tickets, usuários e outros registros, o que pode fazer com que eles não apareçam imediatamente nos resultados da pesquisa.

Tickets » Clientes

ticket.clients[n]

Tickets » Ações

ticket.actions[n]

Tickets » Ações » Apontamentos de horas

ticket.actions.timeAppointments[n]

Tickets » Ações » Despesas

ticket.actions.expenses[n]

Tickets » Ações » Anexos

ticket.actions.attachments[n]

Tickets » Tickets Pais/Filhos

ticket.parentTickets[n]
ticket.childrenTickets[n]

Tickets » Históricos de responsabilidades

ticket.ownerHistories[n]

Tickets » Históricos de status

ticket.statusHistories[n]

Tickets » Campos adicionais

ticket.customFieldValues[n]

*Observação: Serão apresentadas na consulta da propriedade customFieldValues apenas campos adicionais que estiverem com suas regras de exibição sendo atingidas no momento da consulta.

Tickets » Campos adicionais » Itens

ticket.customFieldValues.items[n]

Person

ticket.clients[n].organization
ticket.actions[n].createdBy
ticket.actions[n].timeAppointments[n].createdBy
ticket.owner
ticket.createdBy
ticket.slaSolutionChangedBy

Team

ticket.actions[n].timeAppointments[n].createdByTeam

*UTC: O Tempo Universal Coordenado (do inglês Universal Time Coordinated) é o fuso horário de referência a partir do qual se calculam todas as outras zonas horárias do mundo. Ex: Se o seu fuso horário for o de Brasília (UTC-03:00) e o horário atual for 15h30, o horário UTC será 18h30.

Todo o fluxo de dados (Visualização/Inserção/Alteração) devem possuir o formato JSON conforme exemplo abaixo:

{ 
  "id":1,
  "protocol":"MOVI202109000001",
  "type":2,
  "subject":"Assunto",
  "category":"Categoria",
  "urgency":"Urgência",
  "status":"Status",
  "baseStatus":"Status base",
  "justification":"Justificativa",
  "origin":9,
  "createdDate":"2016-11-18T14:25:07.1920886",
  "originEmailAccount":"[email protected]",
  "owner":{ 
    "id":"CodRefDoResponsável",
    "personType":1,
    "profileType":1,
    "businessName":"Nome do responsável",
    "email":"[email protected]",
    "phone":"(47) 99999-9999"
  },
  "ownerTeam":"Equipe (do) responsável",
  "createdBy":{ 
    "id":"CodRefDoGeradorDoTicket",
    "personType":1,
    "profileType":2,
    "businessName":"Nome do gerador do ticket",
    "email":"[email protected]",
    "phone":"(47) 99999-9999"
  },
  "serviceFull":[ 
    "Serviço nível 1",
    "Serviço nível 2",
    "Serviço nível 3"
  ],
  "serviceFirstLevelId":1,
  "serviceFirstLevel":"Serviço nível 1",
  "serviceSecondLevel":"Serviço nível 2",
  "serviceThirdLevel":"Serviço nível 3",
  "contactForm":"Formulário de contato",
  "tags":[ 
    "Tag1",
    "Tag2",
    "Tag3"
  ],
  "cc":"[email protected],[email protected]",
  "resolvedIn":"2016-11-19T14:25:07.1920886",
  "reopenedIn":"2016-11-20T14:25:07.1920886",
  "closedIn":"2016-11-21T14:25:07.1920886",
  "lastActionDate":"2016-11-21T14:25:07.1920886",
  "actionCount":1,
  "lastUpdate":"2016-11-21T14:25:07.1920886",
  "lifeTimeWorkingTime":9999,
  "stoppedTime":9,
  "stoppedTimeWorkingTime":9,
  "resolvedInFirstCall":false,
  "chatWidget":"Chat - Exemplo",
  "chatGroup":"Grupo do Chat",
  "chatTalkTime":999,
  "chatWaitingTime":9,
  "sequence":2,
  "slaAgreement":"SLA Utilizado",
  "slaAgreementRule":"SLA Regra Utilizado",
  "slaSolutionTime":999,
  "slaResponseTime":99,
  "slaSolutionChangedByUser":false,
  "slaSolutionChangedBy":{ 
    "id":"CodRef",
    "personType":1,
    "profileType":3,
    "businessName":"Nome da pessoa que realizou a alteração",
    "email":"[email protected]",
    "phone":"(47) 99999-9999"
  },
  "slaSolutionDate":"2016-11-21T14:25:07.1920886",
  "slaSolutionDateIsPaused":false,
  "slaResponseDate":"2016-11-21T14:25:07.1920886",
  "slaRealResponseDate":"2016-11-21T14:25:07.1920886",
  "clients":[ 
    { 
      "id":"CodRefDoCliente",
      "personType":2,
      "profileType":2,
      "businessName":"Nome do cliente",
      "email":"[email protected]",
      "phone":"(47) 99999-9999",
      "isDeleted":false,
      "organization":{ 
        "id":"CodRefDaOrganização",
        "personType":1,
        "profileType":2,
        "businessName":"Nome da organização",
        "email":"[email protected]",
        "phone":"(47) 99999-9999"
      }
    }
  ],
  "actions":[ 
    { 
      "id":1,
      "type":2,
      "origin":9,
      "description":"Descrição da ação",
      "status":"Status",
      "justification":"Justificativa",
      "createdDate":"2016-11-21T14:25:07.1920886",
      "createdBy":{ 
        "id":"CodRefDoGeradorDaAção",
        "personType":1,
        "profileType":1,
        "businessName":"Nome do gerador da ação",
        "email":"[email protected]",
        "phone":"(47) 99999-9999"
      },
      "isDeleted":false,
      "timeAppointments":[ 
        { 
          "id":1,
          "activity":"Atividade do apontamento",
          "date":"2016-11-21T00:00:00",
          "periodStart":"21:32:13.7345254",
          "periodEnd":"21:39:08.3443985",
          "workTime":"00:06:54.6098731",
          "accountedTime":7.7666666666666666,
          "workTypeName":"Hora Extra",
          "createdBy":{ 
            "id":"CodRefDoGeradorDoApontamento",
            "personType":1,
            "profileType":1,
            "businessName":"Nome do gerador do apontamento",
            "email":"[email protected]",
            "phone":"(47) 99999-9999"
          },
          "createdByTeam":{ 
            "id":101,
            "name":"Qualidade"
          }
        }
      ],
      "expenses":[ 
        { 
          "id":12,
          "type":"Transporte",
          "serviceReport":"0",
          "createdBy":{ 
            "id":"9B7387E9-4C46-4BD0",
            "personType":1,
            "profileType":3,
            "businessName":"Administrador",
            "email":null,
            "phone":null,
            "address":null,
            "complement":null,
            "cep":null,
            "city":null,
            "bairro":null,
            "number":null,
            "reference":null
          },
          "createdByTeam":null,
          "date":"2018-11-05T18:22:00",
          "quantity":null,
          "value":145.11
        },
        { 
          "id":13,
          "type":"Alimentação",
          "serviceReport":"0",
          "createdBy":{ 
            "id":"9B7387E9-4C46-4BD0",
            "personType":1,
            "profileType":3,
            "businessName":"Administrador",
            "email":null,
            "phone":null,
            "address":null,
            "complement":null,
            "cep":null,
            "city":null,
            "bairro":null,
            "number":null,
            "reference":null
          },
          "createdByTeam":null,
          "date":"2018-11-05T18:22:00",
          "quantity":null,
          "value":25.33
        }
      ],
      "attachments":[ 
        { 
          "fileName":"minhaImagem.png",
          "path":"7BDEA1B62A8641FF86982D0CF9F3DEC0",
          "createdBy":{ 
            "id":"CodRefDeQuemEnviouOArquivo",
            "personType":1,
            "profileType":1,
            "businessName":"Nome de quem enviou o arquivo",
            "email":"[email protected]",
            "phone":"(47) 99999-9999"
          },
          "createdDate":"2017-05-29T14:19:50.0129141"
        }
      ],
      "parentTickets":[ 
        { 
          "id":2,
          "subject":"Assunto do ticket pai",
          "isDeleted":false
        }
      ],
      "childrenTickets":[ 
        { 
          "id":3,
          "subject":"Assunto do ticket filho",
          "isDeleted":false
        }
      ],
      "satisfactionSurveyResponses":[ 
        { 
          "id":1,
          "responsedBy":{ 
            "id":"CodRefDeQuemRespondeuAPesquisa",
            "personType":1,
            "profileType":2,
            "businessName":"Nome de quem respondeu a pesquisa",
            "email":"[email protected]",
            "phone":"(47) 99999-9999"
          },
          "responseDate":"2016-11-22T14:25:07.1920886",
          "satisfactionSurveyModel":2,
          "satisfactionSurveyNetPromoterScoreResponse":null,
          "satisfactionSurveyPositiveNegativeResponse":null,
          "satisfactionSurveySmileyFacesResponse":5,
          "comments":"Comentário na resposta da pesquisa"
        }
      ],
      "customFieldValues":[ 
        { 
          "customFieldId":3,
          "customFieldRuleId":2,
          "line":1,
          "value":null,
          "items":[ 
            { 
              "personId":null,
              "clientId":null,
              "team":null,
              "customFieldItem":"um"
            }
          ]
        },
        { 
          "customFieldId":1,
          "customFieldRuleId":1,
          "line":1,
          "value":"texto via api",
          "items":[ 

          ]
        }
      ]
    }
  ]
}

Obtendo um único ticket

⚠️Atenção: Lista ou Array: As variáveis de tipo lista ou “array” serão apresentadas somente na consulta de tipo “ticket individual”, conforme exemplo a seguir, não sendo exibidos no retorno de consulta do tipo “lista de tickets”.

GET: /tickets
Parâmetros: id / protocol, token

Exemplo:

Obtendo o ticket com o id 1

GET: https://api.movidesk.com/public/servir/v1/tickets?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1

Retorno:

  {
    "id": 1,
    "protocol":"MOVI202109000001",
    "type": 2,
    "origin": 0,
    "status": "Novo",
    "justification": null,
    ... Demais colunas no formato do layout acima
  }

Obtendo o ticket com o protocolo MOVI202109000001

GET: https://api.movidesk.com/public/v1/tickets?token=52ee6ca5-8639-422b-bafe-470013c11176&protocol=MOVI202109000001

Retorno:

 {
    "id": 1,
    "protocol":"MOVI202109000001",
    "type": 2,
    "origin": 0,
    "status": "Novo",
    "justification": null,
    ... Demais colunas no formato do layout acima
  }

⚠️ Atenção: Campos adicionais: Serão apresentadas na consulta da propriedade customFieldValues apenas campos adicionais que estiverem com suas regras de exibição sendo atingidas no momento da consulta.

Obtendo uma lista de tickets

⚠️ Atenção: Lista ou Array: As variáveis de tipo lista ou “array” serão apresentadas somente na consulta de tipo “ticket individual”, conforme exemplo a seguir, não sendo exibidos no retorno de consulta do tipo “lista de tickets”.

GET: /tickets
Parâmetros: token, (LastUpdate e/ou CreatedDate e/ou Status)
Exemplo:

Obtendo uma lista de tickets (é obrigatório o uso de algum filtro)

GET: https://api.movidesk.com/public/servir/v1/tickets?token=52ee6ca5-8639-422b-bafe-470013c11176&status=Novo

Retorno:

  [
    {
      "id": 1,
      "type": 2,
      "origin": 0,
      "status": "Novo"
    },
    {
      "id": 2,
      "type": 2,
      "origin": 0,
      "status": "Novo"
    }
    ... Demais itens da lista 
  ]

Paginação da lista de tickets

GET: /tickets
Parâmetros: token, (Page e/ou Size)

⚠️ Atenção: A lista será paginada com uma quantidade máxima de 100 registros por página, podendo ser utilizado a paginação com os recursos:

Page: ID da página buscada (A primeira página será por default a número 0 e deverá ser a página padrão a ser mostrada caso a busca não possua filtros de paginação).

Size: Quantidade de itens que serão retornados (Máximo 100 itens e caso seja adicionado um valor maior, será desconsiderado e apresentado apenas 100 itens).

GET: https://api.movidesk.com/public/servir/v1/tickets?token=52ee6ca5-8639-422b-bafe-470013c11176&status=Novo&page=0&size=100

Retorno:

[
    {
      "id": 1,
      "type": 2,
      "origin": 0,
      "status": "Novo"
    },
    {
      "id": 2,
      "type": 2,
      "origin": 0,
      "status": "Novo"
    }
    ... Demais itens da lista 
  ]

GET: /tickets
Parâmetros: token

Headers: Content-Type: application/json

Corpo do post: {objeto JSON}

Exemplo:

POST: https://api.movidesk.com/public/v1/tickets?token=52ee6ca5-8639-422b-bafe-470013c11176&returnAllProperties=false
Headers: Content-Type: application/json
RequestBody:
{  
 "type": 2,
 "subject": "Assunto",
 "category": "Categoria",
 "urgency": "Urgência",
 "status": "Status",
 "justification": "Justificativa",
 "createdDate": "2016-11-18T14:25:07.1920886",
  ... Demais colunas no formato do layout acima
}

Retorno: Status 200 e no corpo o id (número) do ticket inserido.

Diferentemente da inserção de dados (POST) a atualização é efetuada de forma parcial. Sendo assim, é necessário enviar ao servidor somente os dados que se deseja alterar.

⚠️ Atenção: A alteração das listas (objetos filhos) sempre sobrescreve todos os itens da lista.

Nas listas de ações e apontamentos deve ser informado o Id no corpo para indicar alteração, pois quando o Id não for informado (for igual a zero) as ações e apontamentos serão inseridos e não alterados. Nas listas de clientes e apontamentos serão excluídos os clientes e apontamentos que não forem informados no corpo.

PATCH: /tickets
Parâmetros: token, id

Headers: Content-Type: application/json

Corpo do post: {objeto JSON}

Exemplos:

Alterando o assunto do ticket com id (número do ticket) 1

PATCH: https://api.movidesk.com/public/v1/tickets?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1
Headers: Content-Type: application/json
RequestBody:
{
  "subject": "Movidesk"
}

Retorno: Status 200

No exemplo acima, é alterado somente o campo subject, os demais campos permanecem inalterados

Removendo as tags do ticket com id (número do ticket) 1

PATCH: https://api.movidesk.com/public/v1/tickets?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1
Headers: Content-Type: application/json
RequestBody:
{
  "tags": []
}

Retorno: Status 200

Como as tags estão em uma lista, no exemplo acima, todas as tags serão removidas. Pois os valores informados na lista sempre sobrescrevem os valores previamente gravados.

Anexos

 URL:    /ticketFileUpload
 Método: POST

Layout

POST: /ticketFileUpload
Parâmetros: token, id e action Id

Headers: Content-Type: multipart/form-data

Corpo do post: anexos

Exemplo:

POST: https://api.movidesk.com/public/v1/ticketFileUpload?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1452&actionId=1
Headers: Content-Type: multipart/form-data
RequestBody: anexos

Retorno: Status 200 e no corpo os detalhes dos anexos inseridos (nome dos arquivos, hashes e possíveis erros)