API do Movidesk - Cadastro de contrato de horas
16 min
Criado por Andre Azevedo Vargas em 27/01/2019 16:11
Atualizado por Thiago Tamanini em 28/07/2022 11:43
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

Contrato de horas

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

Layout

timeAgreement

Propriedade Tipo Tamanho Obrigatório Descrição
name string 128   Nome do contrato de horas
id int     Somente leitura 
emailSubject string      Assunto do e-mail
emailDescription string      Descrição do e-mail
emailAccount string      Remetente do e-mail
isActive bool   *  Se o contrato está ou não ativo
differentiateHoursFranchise bool    ✓ Informar se diferencia horas por atividade  
differentiateHoursConsumption bool    ✓ Usada para diferenciar franquia de horas e valores por atividade e tipos de hora

accumulateUnusedHours

bool    ✓  Habilita para acumular horas não utilizadas.
renewalDay int 2    ✓    Dia de renovação de contrato
contractedHours int    *  *Obrigatório quando differenciateHourByFranchise = false
consumptionDeadline int 3  * Quantidade de meses limite para usar horas acumuladas. Obrigatório quando accumulateUnusedHours = true
emailSendDay int 2    Dia para envio do e-mail
baseAmount decimal  18,2    Valor base do contrato
createdOn datetime      Quando o contrato foi criado o contrato. (Gerado automaticamente)
disabledDate datetime      Quando o contrato foi criado o contrato. (Gerado automaticamente)
typeActivities activities    ✓    Lista de atividades do contrato de horas. ver documentação
timeTypeConsumption typeconsumption     Lista de consumo diferenciado por tempo. ver documentação
emailDestinations destination     Lista de destinatários. ver documentação
clients person     ✓   Lista com os clientes do ticket. ver documentação

Contrato de horas » Clientes

timeAgreement.client[n]

Propriedade Tipo Tamanho Obrigatório Descrição
id string 64 Id (Cod. ref.) da empresa, departamento ou pessoa relacionado como cliente. (Somente leitura).
businessName string 128   Nome do cliente (Somente leitura).
email string 128   E-mail principal do cliente (Somente leitura).
phone string 128   Telefone principal do cliente (Somente leitura).
personType int 1 ✓  Pessoa = 1, Empresa = 2, Departamento = 4  (Somente leitura).
profileType int 1 ✓  Agente = 1, Cliente = 2, Agente e Cliente = 3  (Somente leitura).
isDeleted bool     Verdadeiro se o cliente foi deletado (Somente leitura).
organization person     Organização do cliente (Somente leitura). ver documentação

Contrato de horas » Tipo de atividades

timeAgreement.typeActivities[n]

Propriedade Tipo Tamanho Obrigatório Descrição
id int   ✓  Id do item de franquia da atividade.  Para criar um item utilizar id= 0 e para editar utilizar o id coletado através do GET.
workingTimeType string 128    Tipo de hora
activity string 128    Tipo de atividade
franchise int     Franquia de horas por atividade
value decimal     Valor gasto na atividade selecionada
valueExceededHour decimal     Valor das horas excedentes
shootdownContract bool     Abater do contrato de horas
allowHoursExcedent bool     Cobrança de horas excedentes
activityId int     Informar uma atividade ao contrato pelo id da atividade

Contrato de horas » Consumo diferenciado por tempo

timeAgreement.timeTypeConsumption[n]

Propriedade Tipo Tamanho Obrigatório Descrição
id int   ✓   Id do item de franquia da consumo.  Para criar um item utilizar id= 0 e para editar utilizar o id coletado através do GET.
workingTimeType string  128    Tipo de hora
value decimal     Valor do tipo de hora a ser consumida de forma diferenciada.
workingTimeAgreementId int     Contém o Id do contrato daquele consumo de horas.
typeActivities activities   ✓  Lista de atividades do contrato de horas. ver documentação

Contrato de horas » Destinatário

timeAgreement.emailDestinations[n]

Propriedade Tipo Tamanho Obrigatório Descrição
type  object     O tipo pre definido de destinatário.
email  email     Endereço de e-mail do destinatário 

 

Person

timeAgreement[n].organization

Propriedade Tipo Tamanho Obrigatório Descrição
id string 64  ✓  Id (Cod. ref.) da organização (Somente leitura).
businessName string 128   Nome da organização (Somente leitura).
email string 128   E-mail principal da organização (Somente leitura).
phone string 128   Telefone principal da organização (Somente leitura).
personType int 1   Tipo da pessoa: Pessoa = 1, Empresa = 2, Departamento = 4  (Somente leitura).
profileType int 1  

Perfil da pessoa: Agente = 1, Cliente = 2, Agente e Cliente = 3  (Somente leitura).

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

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:

{
"name": "Contrato",
"emailSubject": "Assunto",
"emailDescription": "Email importante",
"emailAccount": "email@movidesk.com",
"isActive": true,
"differentiateHoursFranchise": false,
"differentiateHoursConsumption": true,
"accumulateUnusedHours": false,
"renewalDay": 23,
"contractedHours": 344,
"consumptionDeadline": null,
"emailSendDay": null,
"baseAmount": 420,
"createdOn": "0001-01-01T00:00:00",
"disabledDate": null,
"typeActivities": [
{
"id": 64,
"workingTimeType": "10x5",
"activity": "Atendimento",
"franchise": null,
"value": 22,
"valueExceededHour": 22,
"shootdownContract": true,
"allowHoursExcedent": true
},
{
"id": 76,
"workingTimeType": "24x7",
"activity": "Atendimento",
"franchise": null,
"value": 33,
"valueExceededHour": 44,
"shootdownContract": true,
"allowHoursExcedent": true
}
],
"timeTypeConsumption": [
{
"id": 65,
"workingTimeType": "24x7",
"value": 4.34
}
],
"clients": [
{
"id": "937205263",
"personType": 1,
"profileType": 2,
"businessName": "Cliente 01",
"email": null,
"organization": {
"id": "51",
"personType": 2,
"profileType": 2,
"businessName": "WINDSOFT SISTEMAS",
"email": null,
"phone": "(17 )3215-6809",
"address": null,
"complement": null,
"cep": null,
"city": null,
"bairro": null,
"number": null,
"reference": null
}
},
{
"id": "1604080257",
"personType": 1,
"profileType": 3,
"businessName": "Cliente 02",
"email": "cliente02@movidesk.com",
"organization": {
"id": "1288891306",
"personType": 2,
"profileType": 3,
"businessName": "Movidesk",
"email": null,
"phone": null,
"address": null,
"complement": null,
"cep": null,
"city": null,
"bairro": null,
"number": null,
"reference": null
}
}
],
"emailDestinations": [
{
"type": 0,
"email": null
}
]
}

Obtendo dados

Método GET

Obtendo um único contrato de horas

GET: /timeAgreement
Parâmetros: nome, token

Exemplo:

Obtendo o contrato com o nome contrato

GET: https://api.movidesktest.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5&name=Contrato

Retorno:

  {
   "name": "Contrato",
"emailSubject": "Assunto",
"emailDescription": "Email importante",
"emailAccount": "email@movidesk.com",
"isActive": true,
"differentiateHoursFranchise": false,
"differentiateHoursConsumption": true,
"accumulateUnusedHours": false, ... Demais colunas no formato do layout acima }

Obtendo uma lista de contratos de hora

GET: /timeAgreement
Parametros: token, $select

Exemplo:

Obtendo uma lista de contratos de horas(é obrigatório o uso da cláusula $select)

GET: https://api.movidesktest.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5&$select=renewalDay,name

Retorno:

{
"renewalDay": 23,
"name": "Contrato"
},
{
"renewalDay": 23,
"name": "Contrato1"
},
{
"renewalDay": 5,
"name": "Contrato2"
},
{
"renewalDay": 1,
"name": "Contrato outro"
}, ... Demais itens da lista

Obtendo contratos de horas com filtros

GET: /timeAgreement
Parâmetros: token, $select

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.

Exemplos:

Obtendo o nome e as horas contratadas , onde as horas contratadas são maiores que 61:

GET: https://api.movidesk.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5&$select=name,contractedHours&filter=contractedHours gt 61

Retorno:
[
 {
"contractedHours": 62,
"name": "Contrato B"
}, {
"contractedHours": 65,
"name": "Contrato A"
}, ... Demais itens da lista que possuam as horas contratadas maiores que 61 ]


Obtendo o nome e as horas contratadas , onde as horas contratadas são maiores que 61 e ordenados de forma descendente em relação as horas contratadas:

GET: https://api.movidesk.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5&$select=name,contractedHours&filter=contractedHours gt 61&orderby=contractedHours desc

Retorno:
[
{
"contractedHours": 65,
"name": "Contrato A"
},
{
"contractedHours": 62,
"name": "Contrato B"
}, ... Demais itens da lista que possuam as horas contratadas maiores que 61 e ordenados de forma descendente em relação as horas contratadas ]

 

Inserindo dados

Método POST

POST: /timeAgreement
Parametros: token
Headers: Content-Type: application/json
Corpo do post: {objeto JSON}
Exemplo:
POST: https://api.movidesk.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5
Headers: Content-Type: application/json {
"name": "Contrato Novo",
"emailSubject": null,
"emailDescription": null,
"emailAccount": null,
"isActive": true,
"differentiateHoursFranchise": false,
"differentiateHoursConsumption": true,
"accumulateUnusedHours": false,
"renewalDay": 23,
"contractedHours": 344, ... Demais colunas no formato do layout acima

Retorno: Status 200 e no corpo o nome do contrato(como id).


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


PATCH: /timeAgreement
Parâmetros: token, name
Headers: Content-Type: application/json
Corpo: {objeto JSON}

Exemplos:

Alterando o assunto do email do contrato de horas com nome "Contrato"

PATCH:  https://api.movidesk.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5&name=Contrato 
Headers: Content-Type: application/json
RequestBody:
{
  "subjectEmail": "Contrato novo"
}

Retorno: Status 200

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

Removendo os consumos do contrato de horas diferenciados por tempo com nome "Contrato novo".

PATCH: https://api.movidesk.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5&name=Contrato novo 
Headers: Content-Type: application/json
RequestBody:
{
  "timeTypeConsumption": []
}

Retorno: Status 200

Como esses consumos estão em uma lista, no exemplo acima, todos eles serão removidos. Pois os valores informados na lista sempre sobrescrevem os valores previamente gravados.
 

Removendo contratos

Método DELETE

DELETE: /timeAgreement
Parâmetros: token, name
Headers: Content-Type: application/json
Corpo: {objeto JSON}

Exemplos:

Removendo contrato de horas com nome "ContratoErrado" 

PATCH:  https://api.movidesk.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5&name=ContratoErrado
Headers: Content-Type: application/json

Retorno: Status 200

No exemplo acima, é removido o contrato de horas com o nome solicitado.

 

 

 

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

Método POST

try
{
var timeAgreement= new
{
subject = "Novo contrato"
};
var json = JsonConvert.SerializeObject(timeAgreement);

var response = await SendAsync("http://movidesk.localhost/public/v1/timeAgreement?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 contrato de horas 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.



https://api.movidesktest.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5
timeAgreement
Este artigo foi útil para você?
Últimos artigos visitados