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

Pessoas

Observação: A senha criada para esta API deve conter pelo menos 8 dígitos.

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

Layout

person

Pessoas » Endereços

person.addresses[n]

Pessoas » Contatos

person.contacts[n]

Pessoas » Emails

person.emails[n]

Pessoas » Organizações

person.relationships[n]

Pessoas » Organização » Serviços

person.relationships[n].services[n]

Pessoas » Campos adicionais

person.customfieldvalues[n]

Pessoas » Campos adicionais » Itens

person.customfieldvalues.items[n]

Pessoas » Ativos

person.atAssets[n]

*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",
    "codeReferenceAdditional": "33B",
    "isActive": true,
    "personType": 1,
    "profileType": 3,
    "accessProfile": "Administradores",
    "businessName": "Movidesk",
    "corporateName": "Movimentti sistemas",
    "cpfCnpj": "012345678900",
    "userName": "admin",
    "password": null,
    "role": null,
    "bossId": null,
    "classification": null,
    "cultureId": "pt-BR",
    "timeZoneId": "America/Sao_Paulo",
    "createdDate": "2014-12-17T18:00:43.3339728",
    "observations": "Cadastro realizado via api de pessoas.",
    "addresses": [
      {
        "addressType": "Comercial",
        "country": "Brasil",
        "postalCode": "89035200",
        "state": "Santa Catarina",
        "district": "Vila Nova",
        "street": "Rua Joinville",
        "number": "209",
        "complement": "Sala 201",
        "reference": "Próximo a FURB",
        "isDefault": true
      }
    ],
    "contacts": [
      {
        "contactType": "Telefone comercial",
        "contact": "(47) 3035-4150",
        "isDefault": true
      },
      {
        "contactType": "Telefone celular",
        "contact": "(47) 9999-9999",
        "isDefault": false
      }
    ],
    "emails": [
      {
        "emailType": "Profissional",
        "email": "atendimento@movimentti.movidesk.com",
        "isDefault": true
      }
    ],
    "teams": [
      "Administradores",
      "Consultoria"
    ],
    "relationships": [
      {
        "id": "2113",
        "name": "Movimentti",
        "slaAgreement": "Contrato de SLA padrão",
        "forceChildrenToHaveSomeAgreement": false,
        "allowAllServices": false,
        "services": [
         {
           "id": 5706,
           "name": "Suporte"
         }
       ]
      }
    ],
    "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 uma única pessoa

GET: /persons
 Parametros: id, token

Exemplo:

Obtendo a pessoa com o id 1

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

Retorno:

  {
    "id": "1",
    "codeReferenceAdditional": "33B",
    "isActive": true,
    "personType": 1,
    "profileType": 3,
    "accessProfile": "Administradores",
    "businessName": "Movidesk",
    "corporateName": "Movimentti sistemas",
    "cpfCnpj": "012345678900",
    "userName": "admin",
    ... Demais colunas no formato do layout acima
  }

Obtendo uma lista de pessoas

GET: /persons
 Parametros: token

Exemplo:

Obtendo uma lista de pessoas

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

Retorno:

  [
    {
      "id": "1",
      "codeReferenceAdditional": "33B",
      "isActive": true,
      "personType": 2,
      "profileType": 3,
      "accessProfile": "Administradores",
      "businessName": "Movidesk",
      "corporateName": "Movimentti sistemas",
      "cpfCnpj": "012345678900",
      "userName": "admin",
      ... Demais colunas no formato do layout acima
    },
    {
      "id": "2",
      "codeReferenceAdditional": "34B",
      "isActive": true,
      "personType": 1,
      "profileType": 1,
      "accessProfile": "Clientes",
      "businessName": "Cliente A",
      "corporateName": "Cliente A",
      "cpfCnpj": "012345678901",
      "userName": "clienteA",
      ... Demais colunas no formato do layout acima
    }
    ... Demais itens da lista 
  ]

Obtendo pessoas com filtros

GET: /persons
Parametros: token

Para 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.

Observação: cláusulas $select sempre são ignoradas quando estão dentro de um $expand. Ou seja, quando existe um $expand, a API retorna todos os parâmetros disponíveis no array, não é possível limitar.

Exemplos:

Obtendo lista de pessoas que sejam do tipo de perfil cliente:

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$filter=profileType eq 2

Retorno:

[
    {
      "id": "1",
      "codeReferenceAdditional": "33B",
      "isActive": true,
      "personType": 2,
      "profileType": 2,
      "accessProfile": "Clientes",
      "businessName": "Cliente A",
      "corporateName": "Cliente A",
      "cpfCnpj": "012345678900",
      "userName": "clienteA",
      ... Demais colunas no formato do layout acima
    },
    {
      "id": "2",
      "codeReferenceAdditional": "34B",
      "isActive": true,
      "personType": 1,
      "profileType": 2,
      "accessProfile": "Clientes",
      "businessName": "Cliente B",
      "corporateName": "Cliente B",
      "cpfCnpj": "012345678901",
      "userName": "clienteB",
      ... Demais colunas no formato do layout acima
    }
    ... Demais itens da lista que possuam o profileType igual a 2
  ]

Obtendo lista de pessoas que sejam do tipo cliente e ordenadas de forma descendente em relação ao id:

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$filter=profileType eq 2&$orderby=id desc

Retorno:

[
    { 
      "id": "2",
      "codeReferenceAdditional": "34B",
      "isActive": true, "personType": 1,
      "profileType": 2, "accessProfile": "Clientes",
      "businessName": "Cliente B",
      "corporateName": "Cliente B",
      "cpfCnpj": "012345678901",
      "userName": "clienteB",
       ... Demais colunas no formato do layout acima },    
    {
      "id": "1",
      "codeReferenceAdditional": "33B",
      "isActive": true,
      "personType": 2,
      "profileType": 2,
      "accessProfile": "Clientes",
      "businessName": "Cliente A",
      "corporateName": "Cliente A",
      "cpfCnpj": "012345678900",
      "userName": "clienteA",
      ... Demais colunas no formato do layout acima
    }    
    ... Demais itens da lista ordenados de forma descendente em relação ao id e que possuam o profileType igual a 2
  ]

Obtendo lista de pessoas que sejam do tipo cliente, ordenadas de forma descendente em relação ao id e filtrando o retorno para obter apenas 100 pessoas, mas pulando as primeiras 100 (utilizado para paginação do retorno, no caso para obter a segunda página):

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$filter=profileType eq 2&$orderby=id desc&$top=100&$skip=100

Retorno:

[
    { 
      "id": "102",
      "codeReferenceAdditional": "134B",
      "isActive": true, 
      "personType": 1,
      "profileType": 2, 
      "accessProfile": "Clientes",
      "businessName": "Cliente B",
      "corporateName": "Cliente B",
      "cpfCnpj": "012345678901",
      "userName": "clienteB",
       ... Demais colunas no formato do layout acima },    
    {
      "id": "101",
      "codeReferenceAdditional": "133B",
      "isActive": true,
      "personType": 2,
      "profileType": 2,
      "accessProfile": "Clientes",
      "businessName": "Cliente A",
      "corporateName": "Cliente A",
      "cpfCnpj": "012345678900",
      "userName": "clienteA",
      ... Demais colunas no formato do layout acima
    }    
    ... Demais 98 itens da lista ordenados de forma descendente em relação ao id e que possuam o profileType igual a 2
  ]

Obtendo o id e o nome de pessoas que sejam do tipo cliente, ordenadas de forma descendente em relação ao id e filtrando o retorno para obter apenas 100 pessoas, mas pulando as primeiras 100 (utilizado para paginação do retorno, no caso para obter a segunda página):

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$select=businessName,id&$filter=profileType eq 2&$orderby=id desc&$top=100&$skip=100

Retorno:

[
    { 
      "id": "102", 
      "businessName": "Cliente B"
    },    
    {
      "id": "101",     
      "businessName": "Cliente A"    
    }    
    ... Demais 98 itens da lista ordenados de forma descendente em relação ao id e que possuam o profileType igual a 2
  ]

Obtendo o id, o nome, as organizações e os serviços permitidos das pessoas que sejam do tipo cliente, ordenadas de forma descendente em relação ao id e filtrando o retorno para obter apenas 100 pessoas, mas pulando as primeiras 100 (utilizado para paginação do retorno, no caso para obter a segunda página):

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$select=businessName,id&$expand=relationships($expand=services)&$filter=profileType eq 2&$orderby=id desc&$top=100&$skip=100

Retorno:

[
    { 
      "id": "102", 
      "businessName": "Cliente B",  
      "relationships": [
      {
        "id": "2113",
        "name": "Movimentti",
        "slaAgreement": "Contrato de SLA padrão",
        "forceChildrenToHaveSomeAgreement": false,
        "allowAllServices": false,
        "services": [
         {
           "id": 5706,
           "name": "Suporte"
         }
       ]
      }
    ]},    
    {
      "id": "101",     
      "businessName": "Cliente A",  
      "relationships": [
      {     
        "slaAgreement": "Contrato de SLA padrão",
        "forceChildrenToHaveSomeAgreement": false,
        "allowAllServices": true,
        "services": []
      }
    ]}
    }    
    ... Demais 98 itens da lista ordenados de forma descendente em relação ao id e que possuam o profileType igual a 2
]

Obtendo as pessoas que contenham ao menos um e-mail igual a "email@movidesk.com":

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$filter=Emails/any(e: e/email eq 'email@movidesk.com')

Retorno:

[
    { 
      "id": "102", 
      "businessName": "Cliente B",  
      ... Demais propriedades da pessoa  
      "emails": [
      {
       "emailType": "Comercial",
       "email": "email@movidesk.com",
       "isDefault": true
      },
      {
       "emailType": "Pessoal",
       "email": "outro.email@movidesk.com",
       "isDefault": false
      }],    
    {
      "id": "101",     
      "businessName": "Cliente A",
      ... Demais propriedades da pessoa  
      "emails": [
      {
       "emailType": "Comercial",
       "email": "email@movidesk.com",
       "isDefault": true
      }
    ]}
    }    
    ... Demais itens da lista que contenham um dos e-mails igual a "email@movidesk.com"
]

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

Exemplo:

POST: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&returnAllProperties=false
Headers: Content-Type: application/json
RequestBody:
{
  "id": "1",
  "codeRefAdditional": "33B",
  "isActive": true,
  "personType": 2,
  "profileType": 3,
  "accessProfile": "Administradores",
  "businessName": "Movidesk",
  "corporateName": "Movimentti sistemas",
  "cpfCnpj": "012345678900",
  "userName": "admin",
  ... Demais colunas no formato do layout acima
}

Retorno: Status 200 e no corpo o id (código de referência) da pessoa inserida.

POST: /persons/relationships
 Parametros: token, id
 Headers: Content-Type: application/json
 Corpo do post: {objeto JSON}

Exemplo:

Incluindo relacionamento de pessoa de id 1 com organização de id 123

POST: https://api.movidesk.com/public/v1/persons/relationships?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1
Headers: Content-Type: application/json
RequestBody:
{
  "relationships": [
        {
             "id": "123",
             "allowAllServices": true
        }
  ]
}

Retorno: Status 200 

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 todos os itens da lista.

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

Exemplos:

Alterando o nome da pessoa com id 1

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

Retorno: Status 200

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

Removendo os emails da pessoa com id 1

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

Retorno: Status 200

Como os emails estão em uma lista, no exemplo acima, todos os emails são removidos. Pois os valores informados na lista sempre sobrescrevem os valores previamente gravados.

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

Exemplos:

Excluindo a pessoa com id 1

DELETE: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1
Headers: Content-Type: application/json

Retorno: Status 200

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

   var response = await SendAsync("https://api.movidesk.com/public/v1/persons?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();
    }
  }
}