Importante: Nossas API's possuem um limite de 10 requisições por minuto para garantir um comportamento saudável no seu uso. Caso você tenha um cenário específico que precise aumentar o uso, entre em contato com o nosso time de atendimento para análise de viabilidade. Saiba mais sobre horários e limites das API's

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

Serviços

  URL:    /services
  Métodos: GET / POST / PATCH / DELETE

Layout

service

Propriedade	Tipo	Tamanho	Obrigatório	Descrição
id	int			Campo Identificador único do serviço (somente leitura).
name	string	128	✓	Campo Nome do serviço.
description	string			Campo descrição.
parentServiceId	int			Campo id que representa o serviço pai.
serviceForTicketType	int		✓	Disponível para tickets do tipo. Público= 0, Interno = 1, Públicos e internos = 2.
isVisible	int		✓	Visível para: Agente = 1, Cliente = 2, Agente e Cliente = 3.
allowSelection	int		✓	Permitir a seleção para: Agente = 1, Cliente = 2, Agente e Cliente = 3.
allowFinishTicket	bool		✓	Ao desmarcar esse parâmetro o ticket não poderá ser concluído se estiver com este item selecionado. O agente precisa escolher um novo item antes de efetuar a conclusão do ticket.
isActive	bool		✓	Serviços desabilitados não estarão visíveis para a seleção dentro dos tickets. Desmarque essa opção caso queira que o serviço não esteja mais disponível no sistema. Observação: Ao consultar os serviços via API, aqueles que estiverem abaixo de um serviço desabilitado também serão considerados desabilitados, mesmo que estejam individualmente habilitados. Por exemplo: Imagine que, ao abrir um ticket, exista a seguinte estrutura de serviços: Atendimento Técnico (desabilitado): ↳ Suporte de Software (habilitado) ↳ Suporte de Hardware (habilitado) Mesmo que os subserviços "Suporte de Software" e "Suporte de Hardware" estejam marcados como habilitados, se o serviço principal "Atendimento Técnico" estiver desabilitado, a API retornará todos eles como desabilitados. Essa lógica é a mesma aplicada durante a exportação na aplicação.
automationMacro	string	64		Nome da macro que deverá ser executada automaticamente ao selecionar o serviço.
defaultCategory	string	128		Nome da categoria que deverá aparecer como padrão ao selecionar o serviço no ticket.
defaultUrgency	string	128		Nome da urgência que deverá aparecer como padrão ao selecionar o serviço no ticket.
allowAllCategories	bool		✓	Permite selecionar todas as categorias.
categories	array	128	*	Lista com os nome das categorias do serviço. Deve ser informado quando o campo allowAllCategories for falso.

Trabalhando com os dados

Para ter acesso aos dados é necessário que previamente seja gerada uma chave para a API

Para gerar uma chave para a API (token), acesse ao Movidesk, vá em Configurações / Conta / Parâmetros e na guia ambiente clique no botão "Gerar nova chave" caso ainda não tenha uma criada.
Você poderá repetir essa operação sempre que quiser gerar uma nova chave de acesso, mas lembre-se que ao gerar uma nova chave, todos os programas que utilizarem a chave antiga irão parar de funcionar.

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

{
    "id": 5778,
    "name": "Demostração",
    "description": "Serviço de teste",
    "parentServiceId": 5707,
    "serviceForTicketType": 1,
    "isVisible": 3,
    "allowSelection": 3,
    "allowFinishTicket": true,
    "isActive": true,
    "automationMacro": "Aplicar anexo",
    "defaultCategory": "Só ações internas",
    "defaultUrgency": "Baixa",
    "allowAllCategories": false,
    "categories": [
       "Só ações internas",
       "Problema",
       "Sugestão"
    ]
}

Obtendo dados

Método GET

Obtendo um único serviço

GET: /services Parametros: id, token

Exemplo:

Obtendo o serviço com o id 5712

GET: https://api.movidesk.com/public/v1/services?token=4242a18d-3e12-498c-937c-930bef3de3fa&id=5712

Retorno:

{
    "id": 5712,
    "name": "TI",
    "description": null,
    "parentServiceId": null,
    "serviceForTicketType": 2,
    "isVisible": 3,
    "allowSelection": 3,
    "allowFinishTicket": true,
    "isActive": true,
    "automationMacro": null,
    "defaultCategory": "Problema",
    "defaultUrgency": "Média",
    "allowAllCategories": true,
    "categories": []
}

Obtendo uma lista de serviços

GET: /services Parametros: token

Exemplo:

Obtendo uma lista de serviços

GET: https://api.movidesk.com/public/v1/services?token=4242a18d-3e12-498c-937c-930bef3de3fa

Retorno:

[
  {
    "id": 5711,
    "name": "SAC",
    "description": null,
    "parentServiceId": null,
    "serviceForTicketType": 2,
    "isVisible": 3,
    "allowSelection": 1,
    "allowFinishTicket": true,
    "isActive": true,
    "automationMacro": null,
    "defaultCategory": null,
    "defaultUrgency": null,
    "allowAllCategories": true,
    "categories": []
  },
  {
    "id": 5712,
    "name": "TI",
    "description": null,
    "parentServiceId": null,
    "serviceForTicketType": 2,
    "isVisible": 3,
    "allowSelection": 3,
    "allowFinishTicket": true,
    "isActive": true,
    "automationMacro": null,
    "defaultCategory": "Problema",
    "defaultUrgency": "Média",
    "allowAllCategories": true,
    "categories": []
  }
    ... Demais itens da lista 
]

Obtendo serviços com filtros

GET: /services Parametros: tokenPara permitir e simplificar consultas com filtros, a API utiliza o protocolo aberto OData. Os filtros possíveis são:
• $filter: a expressão especificada com esse filtro é avaliada para cada item do retorno da consulta e somente os itens em que o resultado da expressão for verdadeiro serão incluídos no retorno final;
• $orderby: permite que os itens do retorno da consulta sejam ordenados de forma ascendente (asc) ou descendente (desc). Se não for especificado asc ou desc, o padrão será asc;
• $top: permite especificar o número de itens que devem ser incluídos no retorno da consulta;
• $skip: permite especificar a quantidade de itens que devem ser ignorados e não incluídos no retorno da consulta;
• $select: permite especificar propriedades especificas dos itens que devem ser preenchidas no retorno da consulta;
• $expand: permite expandir as coleções filhas dos itens consultados.

Exemplos:

Obtendo lista de serviços que tenha um determinado id:

GET: https://api.movidesk.com/public/v1/services?token=4242a18d-3e12-498c-937c-930bef3de3fa&$filter=id eq 5779

Retorno:

[
 {
    "id": 5779,
    "name": "5779",
    "description": null,
    "parentServiceId": 5778,
    "serviceForTicketType": 0,
    "isVisible": 0,
    "allowSelection": 0,
    "allowFinishTicket": false,
    "isActive": true,
    "automationMacro": null,
    "defaultCategory": null,
    "defaultUrgency": null,
    "allowAllCategories": false,
    "categories": []
 }
]

Obtendo lista de serviços que não estejam ativos, ordenados de forma descendente em relação ao id:

GET: https://api.movidesk.com/public/v1/services?token=4242a18d-3e12-498c-937c-930bef3de3fa&$filter=isActive eq false&$orderby=id desc

Retorno:

[
   {
      "id": 5788,
      "name": "teste 1",
      "description": null,
      "parentServiceId": 5785,
      "serviceForTicketType": 0,
      "isVisible": 0,
      "allowSelection": 0,
      "allowFinishTicket": false,
      "isActive": false,
      "automationMacro": null,
      "defaultCategory": null,
      "defaultUrgency": null,
      "allowAllCategories": false,
      "categories": []
   },
   {
      "id": 5787,
      "name": "teste 1",
      "description": null,
      "parentServiceId": 5785,
      "serviceForTicketType": 0,
      "isVisible": 0,
      "allowSelection": 0,
      "allowFinishTicket": false,
      "isActive": false,
      "automationMacro": null,
      "defaultCategory": null,
      "defaultUrgency": null,
      "allowAllCategories": false,
      "categories": []
   }
]

Obtendo lista de serviços que não estejam ativos e ordenados de forma descendente em relação ao id e filtrando o retorno para obter apenas 10 serviços, mas pulando as primeiras 10 (utilizado para paginação do retorno, no caso para obter a segunda página):

GET: https://api.movidesk.com/public/v1/services?token=4242a18d-3e12-498c-937c-930bef3de3fa&$filter=isActive eq false&$orderby=id desc&$top=100&$skip=10

Retorno:

[
    { 
       {
         "id": 102,
         "name": "teste 1",
         "description": null,
         "parentServiceId": 5785,
         "serviceForTicketType": 0,
         "isVisible": 0,
         "allowSelection": 0,
         "allowFinishTicket": false,
         "isActive": false,
         "automationMacro": null,
         "defaultCategory": null,
         "defaultUrgency": null,
         "allowAllCategories": false,
         "categories": []
       },
       {
         "id": 101,
         "name": "teste 1",
         "description": null,
         "parentServiceId": 5785,
         "serviceForTicketType": 0,
         "isVisible": 0,
         "allowSelection": 0,
         "allowFinishTicket": false,
         "isActive": false,
         "automationMacro": null,
         "defaultCategory": null,
         "defaultUrgency": null,
         "allowAllCategories": false,
         "categories": []
     },
    ... Demais 8 itens da lista ordenados de forma descendente em relação ao id e que não estejam ativos.
  ]

Obtendo id e o nome dos serviços que não estejam ativos, ordenados de forma descendente em relação ao id e filtrando o retorno para obter apenas 10 serviços, mas pulando as primeiras 10 (utilizado para paginação do retorno, no caso para obter a segunda página):

GET: https://api.movidesk.com/public/v1/services?token=4242a18d-3e12-498c-937c-930bef3de3fa&$filter=isActive eq false&$select=name,id&$orderby=id desc&$top=10&$skip=10

Retorno:

[
    {
       "id": 102,
       "name": "Demostração"
    },
    {
       "id": 101,
       "name": "Décimo terceiro"
    }  
    ... Demais 8 itens da lista ordenados de forma descendente em relação ao id e que não estejam ativos.
]

Inserindo dados

Método POST

POST: /services Parametros: token, returnAllProperties (valor default é false) Headers: Content-Type: application/json Corpo do post: {objeto JSON}

Exemplo:

POST: https://api.movidesk.com/public/v1/services?token=4242a18d-3e12-498c-937c-930bef3de3fa&returnAllProperties=false
Headers: Content-Type: application/json
RequestBody:
 {
   "id": 5707,
   "name": "Teste 01",
   "description": "Teste do serviço",
   "parentServiceId": 5707,
   "serviceForTicketType": 1,
   "isVisible": 3,
   "allowSelection": 3,
   "allowFinishTicket": true,
   "isActive": true,
   "automationMacro": "Aplicar anexo",
   "defaultCategory": "Problema",
   "defaultUrgency": "Média",
   "allowAllCategories": false,
   "categories": [
      "Problema",
      "Sugestão",
      "Não adiciona ação",
      "Solicitação de serviço"
    ]
 }

Retorno: Status 200 e no corpo o id do serviço inserido.

Atualizando dados

Método PATCH

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.

Entretanto a alteração das listas (objetos filhos) sempre sobrescreve a todos os itens da lista.

PATCH: /services Parametros: token, id Headers: Content-Type: application/json Corpo: {objeto JSON}

Exemplos:

Alterando o nome do serviço com id 1

PATCH: https://api.movidesk.com/public/v1/services?token=4242a18d-3e12-498c-937c-930bef3de3fa&id=1
Headers: Content-Type: application/json
RequestBody:
{
  "name": "teste"
}

Retorno: Status 200

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

Excluindo serviços

Método DELETE

DELETE: /services Parametros: token, id Headers: Content-Type: application/json Corpo o post: {objeto JSON}

Exemplos:

Excluindo o serviço com id 1

DELETE: https://api.movidesk.com/public/v1/services?token=4242a18d-3e12-498c-937c-930bef3de3fa&id=1
Headers: Content-Type: application/json

Retorno: Status 200

Exemplo de código fonte na linguagem C# da chamada da API

Método POST

try
{
   var servico = new
   {
     isActive = true
   };
   var json = JsonConvert.SerializeObject(servico);

   var response = await SendAsync("https://api.movidesk.com/public/v1/services?token=SEUTOKEN",
 json, "POST", "application/json"); 
}
catch (WebException ex)
{
 var response = new StreamReader(ex.Response.GetResponseStream()).ReadToEnd();
}

public static async Task<string> SendAsync(string uri, string content, string method, string contentType)
{
 var req = WebRequest.Create(uri);
 req.ContentType = contentType;
 req.Method = method;

 using (var stream = await req.GetRequestStreamAsync())
 using (var streamWriter = new StreamWriter(stream))
 {
 await streamWriter.WriteAsync(content);
 }

 var httpResponse = (HttpWebResponse)await req.GetResponseAsync();
 using (var stream = httpResponse.GetResponseStream())
 {
 if (stream == null)
 return null;

 using (var streamReader = new StreamReader(stream))
 { 
 return await streamReader.ReadToEndAsync();
 }
 }
}

No exemplo acima, a inserção do serviço não será realizada pois existem vários erros no corpo da requisição. Os erros são detalhados na variável response e devem ser corrigidos seguindo essa documentação.

💡 Dica: O time de suporte da Zenvia não atua na construção/montagem das requisições de API, conseguimos apoiar apenas em casos de erro.

Institucional

Conteúdo

O Software

Módulos extras

Olá, como podemos ajudar você?

Serviços

Layout

Trabalhando com os dados

Obtendo dados

Obtendo um único serviço

Exemplo:

Obtendo uma lista de serviços

Exemplo:

Obtendo serviços com filtros

Exemplos:

Retorno:

Retorno:

Retorno:

Retorno:

Inserindo dados

Exemplo:

Atualizando dados

Exemplos:

Excluindo serviços

Exemplos:

Exemplo de código fonte na linguagem C# da chamada da API