Hello, how can we help you?

  1. Home page
  2. Return to search
  3. 05. Integrations
  4. API's
Movidesk API - Hour contract registration
19 min
Created by Andre Azevedo Vargas on 1/27/2019 4:11 PM
Updated by Karine Moreira on 9/24/2024 4:20 PM
Important: Our APIs have a limit of 10 requests per minute to ensure healthy usage. If you have a specific scenario that requires increased usage, please contact our support team for a feasibility analysis. Learn more about API schedules and limits
https://api.movidesk.com/public/v1

Hour Contract

  URL:    /timeAgreement
  Methods: GET / POST / PATCH / DELETE

Layout

timeAgreement

Property Type Size Required Description
name string 128  ✓  Hour contract name
id int     Read-only 
emailSubject string      Email subject
emailDescription string     Email description
emailAccount string     Email sender
isActive bool   * Whether the contract is active or not
differentiateHoursFranchise bool   ✓ Indicate whether hours are differentiated by activity
differentiateHoursConsumption bool   ✓ Used to differentiate hour franchise and values by activity and hour types

accumulateUnusedHours

 bool   ✓ Enable to accumulate unused hours.
renewalDay int 2 ✓ Contract renewal day
contractedHours int   * *Required when differentiateHoursByFranchise = false
consumptionDeadline int 3 * Number of months allowed to use accumulated hours. Required when accumulateUnusedHours = true
emailSendDay int 2   Email sending day
baseAmount decimal  18.2   Base value of the contract
createdOn datetime     When the contract was created. (Generated automatically)
disabledDate datetime     When the contract was created. (Generated automatically)
typeActivities activities   ✓ List of activities for the hourly contract. see documentation
timeTypeConsumption typeconsumption     List of consumption differentiated by time. see documentation
emailDestinations destination     List of recipients. see documentation
clients person     ✓   List of ticket clients. see documentation

Hourly Contract » Clients

timeAgreement.client[n]

Property Type Size Required Description
id string 64 ✓ Id (Ref. code) of the company, department, or person listed as a client. (Read-only).
businessName string 128   Client's name (Read-only).
email string 128   Client's main email (Read-only).
phone string 128   Client's main phone (Read-only).
personType int 1 ✓  Person = 1, Company = 2, Department = 4 (Read-only).
profileType int 1 ✓  Agent = 1, Client = 2, Agent and Client = 3 (Read-only).
isDeleted bool     True if the client has been deleted (Read-only).
organization person     Client's organization (Read-only). see documentation

Hourly Contract » Activity Types

timeAgreement.typeActivities[n]

Property Type Size Required Description
id int   ✓  ID of the franchise item for the activity. To create an item use id= 0 and to edit use the id obtained via GET.
workingTimeType string 128    Type of hour
activity string 128    Activity type
franchise int     Franchise of hours per activity
value decimal     Amount spent on the selected activity
valueExceededHour decimal     Amount of excess hours
shootdownContract bool     Deduct from the hourly contract
allowHoursExcedent bool     Charge for excess hours
activityId int     Specify an activity to the contract by the activity id

Hourly Contract » Differentiated Time Consumption

timeAgreement.timeTypeConsumption[n]

Property Type Size Required Description
id int   ✓   ID of the consumption franchise item. To create an item use id= 0 and to edit use the id obtained via GET.
workingTimeType string  128    Type of hour
value decimal     Value of the hour type to be consumed in a differentiated manner.
workingTimeAgreementId int     Contains the ID of the contract for that time consumption.
typeActivities activities   ✓  List of activities in the hourly contract. view documentation

Hourly Contract » Recipient

timeAgreement.emailDestinations[n]

Property Type Size Required Description
type  object     The predefined recipient type.
email  email     Recipient's email address 

 

Person

timeAgreement[n].organization

Property Type Size Required Description
id string 64  ✓  Id (Ref. code) of the organization (Read-only).
businessName string 128   Name of the organization (Read-only).
email string 128   Primary email of the organization (Read-only).
phone string 128   Primary phone of the organization (Read-only).
personType int 1   Type of person: Person = 1, Company = 2, Department = 4  (Read-only).
profileType int 1  

Profile of the person: Agent = 1, Client = 2, Agent and Client = 3  (Read-only).

*UTC: Coordinated Universal Time (UTC) is the reference time zone from which all other time zones in the world are calculated. E.g.: If your time zone is Brasília (UTC-03:00) and the current time is 15:30, the UTC time will be 18:30.

Working with Data

To access the data, you need to first generate an API key

To generate an API key (token), access Movidesk, go to Settings / Account / Parameters, and in the environment tab, click the "Generate new key" button if you don't have one created yet.
You can repeat this process whenever you want to generate a new access key, but remember that generating a new key will cause all programs using the old key to stop functioning.

All data flows (View/Insert/Update) must be in JSON format as shown in the example below:

{
 "name": "Contract",
 "emailSubject": "Subject",
 "emailDescription": "Important email",
 "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": "Support",
 "franchise": null,
 "value": 22,
 "valueExceededHour": 22,
 "shootdownContract": true,
 "allowHoursExcedent": true
 },
 {
 "id": 76,
 "workingTimeType": "24x7",
 "activity": "Support",
 "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": "Client 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,
 "neighborhood": null,
 "number": null,
 "reference": null
 }
 },
 {
 "id": "1604080257",
 "personType": 1,
 "profileType": 3,
 "businessName": "Client 02",
 "email": "client02@movidesk.com",
 "organization": {
 "id": "1288891306",
 "personType": 2,
 "profileType": 3,
 "businessName": "Movidesk",
 "email": null,
 "phone": null,
 "address": null,
 "complement": null,
 "cep": null,
 "city": null,
 "neighborhood": null,
 "number": null,
 "reference": null
 }
 }
 ],
 "emailDestinations": [
 {
 "type": 0,
 "email": null
 }
 ]
}

Obtaining Data

Method GET

Getting a single hour contract

GET: /timeAgreement
Parameters: name, token

Example:

Getting the contract with the name "contract"

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

Return:

  {
   "name": "Contract",
   "emailSubject": "Subject",
   "emailDescription": "Important email",
   "emailAccount": "email@movidesk.com",
   "isActive": true,
   "differentiateHoursFranchise": false,
   "differentiateHoursConsumption": true,
   "accumulateUnusedHours": false,
    ... Other columns in the format of the above layout
  }

Getting a list of hour contracts

GET: /timeAgreement
Parameters: token, $select

Example:

Getting a list of hour contracts (using the $select clause is mandatory)

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

Return:

{
 "renewalDay": 23,
 "name": "Contract"
 },
 {
 "renewalDay": 23,
 "name": "Contract1"
 },
 {
 "renewalDay": 5,
 "name": "Contract2"
 },
 {
 "renewalDay": 1,
 "name": "Another Contract"
 },
 ... Other items in the list

Getting hour contracts with filters

GET: /timeAgreement
Parameters: token, $select

To allow and simplify queries with filters, the API uses the open protocol OData. Possible filters are:
• $filter: the expression specified with this filter is evaluated for each item in the query result, and only items where the expression result is true will be included in the final result;
• $orderby: allows the items in the query result to be ordered in ascending (asc) or descending (desc) order. If asc or desc is not specified, the default will be asc;
• $top: allows specifying the number of items that should be included in the query result;
• $skip: allows specifying the number of items to be skipped and not included in the query result;
• $select: allows specifying specific properties of the items that should be included in the query result;
• $expand: allows expanding the child collections of the queried items.

Examples:

Getting the name and contracted hours, where the contracted hours are greater than 61:

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

Return:
[
 {
 "contractedHours": 62,
 "name": "Contract B"
 },
 {
  "contractedHours": 65,
  "name": "Contract A"
  },
    ... Other items in the list with contracted hours greater than 61
]


Getting the name and contracted hours, where the contracted hours are greater than 61 and ordered in descending order with respect to contracted hours:

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

Return:
[
{
 "contractedHours": 65,
 "name": "Contract A"
 },
 {
 "contractedHours": 62,
 "name": "Contract B"
 },
    ... Other items in the list with contracted hours greater than 61 and ordered in descending order with respect to contracted hours
]

 

Inserting Data

Method POST

POST: /timeAgreement
Parameters: token
Headers: Content-Type: application/json
Request Body: {JSON object}
Example:
POST: https://api.movidesk.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5

Headers: Content-Type: application/json
{
 "name": "New Contract",
 "emailSubject": null,
 "emailDescription": null,
 "emailAccount": null,
 "isActive": true,
 "differentiateHoursFranchise": false,
 "differentiateHoursConsumption": true,
 "accumulateUnusedHours": false,
 "renewalDay": 23,
 "contractedHours": 344,

  ... Other columns in the format of the above layout

Return: Status 200 and in the body the name of the contract (as id).

Updating Data

Method PATCH

Unlike data insertion (POST), updating is done partially. Therefore, it is necessary to send only the data you want to change to the server.
However, updating lists (child objects) always overwrites all items in the list.


PATCH: /timeAgreement
Parameters: token, name
Headers: Content-Type: application/json
Body: {JSON object}

Examples:

Changing the email subject of the time agreement contract named "Contract"

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

Return: Status 200

In the above example, only the subjectEmail field is changed; other fields remain unchanged.

Removing time-type consumption from the time agreement contract named "New Contract".

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

Return: Status 200

Since these consumptions are in a list, in the example above, all of them will be removed. The values specified in the list always overwrite previously stored values.
 

Removing Contracts

Method DELETE

DELETE: /timeAgreement
Parameters: token, name
Headers: Content-Type: application/json
Body: {JSON object}

Examples:

Removing the time agreement contract with the name "WrongContract"

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

Return: Status 200

In the above example, the time agreement contract with the requested name is removed.

 

 

 

Example of source code in C# for calling the API

Method POST

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

   var response = await SendAsync("http://movidesk.localhost/public/v1/timeAgreement?token=YOURTOKEN",
   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();
    }
  }
}

In the above example, the insertion of the time agreement contract will not occur due to several errors in the request body. The errors are detailed in the response variable and should be corrected according to this documentation.



https://api.movidesktest.com/public/v1/timeAgreement?token=3bd53482-72b0-4057-9545-3975a3423ec5
timeAgreement
Was this article useful?
Recently viewed