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

Personas

Observación: La contraseña creada para esta API debe contener al menos 8 dígitos.

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

Diseño

persona

Personas » Direcciones

person.addresses[n]

Personas » Contactos

person.contacts[n]

Personas » Correos Electrónicos

person.emails[n]

Personas » Organizaciones

person.relationships[n]

Personas » Organización » Servicios

person.relationships[n].services[n]

Personas » Campos adicionales

person.customfieldvalues[n]

Personas » Campos adicionales » Ítems

person.customfieldvalues.items[n]

Personas » Activos

person.atAssets[n]

*UTC: El Tiempo Universal Coordinado (del inglés Universal Time Coordinated) es la zona horaria de referencia a partir de la cual se calculan todas las demás zonas horarias del mundo. Ej: Si tu zona horaria es la de Brasilia (UTC-03:00) y la hora actual es 15:30, la hora UTC será 18:30.

Todo el flujo de datos (Visualización/Inserción/Modificación) debe tener el formato JSON conforme al siguiente ejemplo:

Obteniendo una única persona

GET: /persons
 Parámetros: id, token

Ejemplo:

Obteniendo la persona con el id 1

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

Respuesta:

  {
    "id": "1",
    "codeReferenceAdditional": "33B",
    "isActive": true,
    "personType": 1,
    "profileType": 3,
    "accessProfile": "Administradores",
    "businessName": "Movidesk",
    "corporateName": "Movimentti sistemas",
    "cpfCnpj": "012345678900",
    "userName": "admin",
    ... Otras columnas en el formato del diseño anterior
  }

Obteniendo una lista de personas

GET: /persons
 Parámetros: token

Ejemplo:

Obteniendo una lista de personas

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

Respuesta:

  [
    {
      "id": "1",
      "codeReferenceAdditional": "33B",
      "isActive": true,
      "personType": 2,
      "profileType": 3,
      "accessProfile": "Administradores",
      "businessName": "Movidesk",
      "corporateName": "Movimentti sistemas",
      "cpfCnpj": "012345678900",
      "userName": "admin",
      ... Otras columnas en el formato del diseño anterior
    },
    {
      "id": "2",
      "codeReferenceAdditional": "34B",
      "isActive": true,
      "personType": 1,
      "profileType": 1,
      "accessProfile": "Clientes",
      "businessName": "Cliente A",
      "corporateName": "Cliente A",
      "cpfCnpj": "012345678901",
      "userName": "clienteA",
      ... Otras columnas en el formato del diseño anterior
    }
    ... Otros ítems de la lista 
  ]

Obteniendo personas con filtros

GET: /persons
Parámetros: token

Para permitir y simplificar consultas con filtros, la API utiliza el protocolo abierto OData. Los filtros posibles son:
• $filter: la expresión especificada con este filtro se evalúa para cada ítem del resultado de la consulta y solo los ítems en los que el resultado de la expresión sea verdadero serán incluidos en el resultado final;
• $orderby: permite que los ítems del resultado de la consulta se ordenen de forma ascendente (asc) o descendente (desc). Si no se especifica asc o desc, el valor predeterminado será asc;
• $top: permite especificar el número de ítems que deben ser incluidos en el resultado de la consulta;
• $skip: permite especificar la cantidad de ítems que deben ser ignorados y no incluidos en el resultado de la consulta;
• $select: permite especificar propiedades específicas de los ítems que deben ser llenadas en el resultado de la consulta;
• $expand: permite expandir las colecciones secundarias de los ítems consultados.

Nota: las cláusulas $select siempre se ignoran cuando están dentro de un $expand. Es decir, cuando existe un $expand, la API devuelve todos los parámetros disponibles en el array, no es posible limitar.

Ejemplos:

Obteniendo lista de personas que sean del tipo de perfil cliente:

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

Respuesta:

[
    {
      "id": "1",
      "codeReferenceAdditional": "33B",
      "isActive": true,
      "personType": 2,
      "profileType": 2,
      "accessProfile": "Clientes",
      "businessName": "Cliente A",
      "corporateName": "Cliente A",
      "cpfCnpj": "012345678900",
      "userName": "clienteA",
      ... Otras columnas en el formato del diseño anterior
    },
    {
      "id": "2",
      "codeReferenceAdditional": "34B",
      "isActive": true,
      "personType": 1,
      "profileType": 2,
      "accessProfile": "Clientes",
      "businessName": "Cliente B",
      "corporateName": "Cliente B",
      "cpfCnpj": "012345678901",
      "userName": "clienteB",
      ... Otras columnas en el formato del diseño anterior
    }
    ... Otros ítems de la lista que tengan profileType igual a 2
  ]

Obteniendo lista de personas que sean del tipo cliente y ordenadas de forma descendente respecto al id:

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

Respuesta:

[
    { 
      "id": "2",
      "codeReferenceAdditional": "34B",
      "isActive": true, "personType": 1,
      "profileType": 2, "accessProfile": "Clientes",
      "businessName": "Cliente B",
      "corporateName": "Cliente B",
      "cpfCnpj": "012345678901",
      "userName": "clienteB",
       ... Otras columnas en el formato del diseño anterior },    
    {
      "id": "1",
      "codeReferenceAdditional": "33B",
      "isActive": true,
      "personType": 2,
      "profileType": 2,
      "accessProfile": "Clientes",
      "businessName": "Cliente A",
      "corporateName": "Cliente A",
      "cpfCnpj": "012345678900",
      "userName": "clienteA",
      ... Otras columnas en el formato del diseño anterior
    }    
    ... Otros ítems de la lista ordenados de forma descendente respecto al id y que tengan profileType igual a 2
  ]

Obteniendo una lista de personas que sean del tipo cliente, ordenadas de forma descendente respecto al id y filtrando el resultado para obtener solo 100 personas, pero omitiendo las primeras 100 (utilizado para la paginación del resultado, en este caso para obtener la 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

Respuesta:

[
    { 
      "id": "102",
      "codeReferenceAdditional": "134B",
      "isActive": true, 
      "personType": 1,
      "profileType": 2, 
      "accessProfile": "Clientes",
      "businessName": "Cliente B",
      "corporateName": "Cliente B",
      "cpfCnpj": "012345678901",
      "userName": "clienteB",
       ... Otras columnas en el formato del diseño anterior },    
    {
      "id": "101",
      "codeReferenceAdditional": "133B",
      "isActive": true,
      "personType": 2,
      "profileType": 2,
      "accessProfile": "Clientes",
      "businessName": "Cliente A",
      "corporateName": "Cliente A",
      "cpfCnpj": "012345678900",
      "userName": "clienteA",
      ... Otras columnas en el formato del diseño anterior
    }    
    ... Otros 98 ítems de la lista ordenados de forma descendente respecto al id y que tengan profileType igual a 2
  ]

Obteniendo el id y el nombre de personas que sean del tipo cliente, ordenadas de forma descendente respecto al id y filtrando el resultado para obtener solo 100 personas, pero omitiendo las primeras 100 (utilizado para la paginación del resultado, en este caso para obtener la 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

Respuesta:

[
    { 
      "id": "102", 
      "businessName": "Cliente B"
    },    
    {
      "id": "101",     
      "businessName": "Cliente A"    
    }    
    ... Otros 98 ítems de la lista ordenados de forma descendente respecto al id y con profileType igual a 2
  ]

Obteniendo el id, el nombre, las organizaciones y los servicios permitidos de las personas que sean del tipo cliente, ordenadas de forma descendente respecto al id y filtrando el resultado para obtener solo 100 personas, pero omitiendo las primeras 100 (utilizado para la paginación del resultado, en este caso para obtener la 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

Respuesta:

[
    { 
      "id": "102", 
      "businessName": "Cliente B",  
      "relationships": [
      {
        "id": "2113",
        "name": "Movimentti",
        "slaAgreement": "Contrato de SLA estándar",
        "forceChildrenToHaveSomeAgreement": false,
        "allowAllServices": false,
        "services": [
         {
           "id": 5706,
           "name": "Soporte"
         }
       ]
      }
    ]},    
    {
      "id": "101",     
      "businessName": "Cliente A",  
      "relationships": [
      {     
        "slaAgreement": "Contrato de SLA estándar",
        "forceChildrenToHaveSomeAgreement": false,
        "allowAllServices": true,
        "services": []
      }
    ]}
    }    
    ... Otros 98 ítems de la lista ordenados de forma descendente respecto al id y con profileType igual a 2
]

Obteniendo las personas que contengan al menos un correo electrónico 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')

Respuesta:

[
    { 
      "id": "102", 
      "businessName": "Cliente B",  
      ... Otras propiedades de la persona  
      "emails": [
      {
       "emailType": "Comercial",
       "email": "email@movidesk.com",
       "isDefault": true
      },
      {
       "emailType": "Personal",
       "email": "otro.email@movidesk.com",
       "isDefault": false
      }],    
    {
      "id": "101",     
      "businessName": "Cliente A",
      ... Otras propiedades de la persona  
      "emails": [
      {
       "emailType": "Comercial",
       "email": "email@movidesk.com",
       "isDefault": true
      }
    ]}
    }    
    ... Otros ítems de la lista que contengan uno de los correos electrónicos igual a "email@movidesk.com"
]

POST: /persons
 Parámetros: token, returnAllProperties (valor por defecto es false)
 Headers: Content-Type: application/json
 Cuerpo del post: {objeto JSON}

Ejemplo:

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",
  ... Otras columnas en el formato del layout anterior
}

Respuesta: Estado 200 y en el cuerpo el id (código de referencia) de la persona insertada.

POST: /persons/relationships
 Parámetros: token, id
 Headers: Content-Type: application/json
 Cuerpo del post: {objeto JSON}

Ejemplo:

Incluyendo la relación de la persona con id 1 con la organización con 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
        }
  ]
}

Respuesta: Estado 200 

A diferencia de la inserción de datos (POST), la actualización se realiza de forma parcial. Por lo tanto, es necesario enviar al servidor solo los datos que se desean modificar.

Sin embargo, la modificación de listas (objetos hijos) siempre sobrescribe todos los ítems de la lista.

PATCH: /persons
 Parámetros: token, id
 Headers: Content-Type: application/json
 Cuerpo: {objeto JSON}

Ejemplos:

Modificando el nombre de la persona con 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"
}

Respuesta: Estado 200

En el ejemplo anterior, solo se modifica el campo businessName, los demás campos permanecen inalterados

Eliminando los correos electrónicos de la persona con 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": []
}

Respuesta: Estado 200

Dado que los correos electrónicos están en una lista, en el ejemplo anterior, todos los correos electrónicos se eliminan. Esto ocurre porque los valores proporcionados en la lista siempre sobrescriben los valores previamente almacenados.

DELETE: /persons
Parámetros: token, id
Headers: Content-Type: application/json
Cuerpo del post: {objeto JSON}

Ejemplos:

Eliminando la persona con id 1

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

Respuesta: Estado 200

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

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