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, contact our support team for feasibility analysis. Learn more about API hours and limits

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

Hour Contract Consumption

  URL:    /timeAgreementConsumption
  Methods: GET

Layout

timeAgreementConsumption

Property	Type	Size	Required	Description
id	string	64		Number of the hour contract consumption (read-only). This ID corresponds to the record of the period's closure. In open periods, the returned ID is zero, as the closure has not yet been generated.
name	string	128	✓	Name of the hour contract
startPeriod	DateTime	19	✓	Start of the period (format 2019-10-01T00:00:00). Property related to the "period" field, used only as a filter to search for multiple periods.
endPeriod	DateTime	19		End of the period. Property related to the "period" field, used only as a filter to search for multiple periods.
baseAmount	decimal	18.2		Base value of the contract
exceededHourAmount	decimal			Total amount of exceeded hours
renewalDay	int	2		Contract renewal day
contractedHours	int			Contracted hours
differentiateHoursFranchise	bool			Indicates if hours are differentiated by franchise activity
differentiateHoursConsumption	bool			Used to differentiate franchise hours and values by activity and hour types
period	Datetime			Period of the hour record.
consumedHours	double			Hours consumed in the hour contract. This value is displayed only when the period is closed
discount	decimal	18.2		Discount on the hour contract
discountType	int	1		Percent = 0, Currency = 1
timeAppointments	appointments			List of the hour records for the hour contract. view documentation
expenses	expenses			List of expenses for the hour contract. view documentation
clients	person			List of clients for the hour contract. view documentation

Important Points

Parameter Requirement name: For searches using startPeriod and endPeriod, it is mandatory to specify the name of the hour contract in the name property.
Missing $select error: If name is not specified, the request will return an error indicating that the $select parameter is required.
Priority of the $select parameter: If $select is used in the request, the startPeriod, endPeriod, and period properties will be ignored, and the system will return a 200 - ok status.

Therefore, for a correct request that seeks the consumption of hours, it is necessary:
1. Specify the name with the name of the hours contract.
2. Do not include $select in the request.
3. Use the $filter to define the period in Datetime format.

Contract Hour Consumption > Clients

timeAgreementConsumption.client[n]

Property	Type	Size	Required	Description
id	string	64	✓	Id (Ref. code) of the company, department, or person listed as the ticket client (Read-only).
businessName	string	128		Client's name (Read-only).
email	string	128		Client's primary email (Read-only).
phone	string	128		Client's primary 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). view documentation

Contract Hour Consumption » Time EntriestimeAgreementConsumption.timeAppointments[n]

Property	Type	Size	Required	Description
id	int		*	Id (Code) of the entry (Read-only). *Must be provided when it is necessary to modify an existing entry.
activity	string	128	✓	Must be a pre-registered activity in the system.
date	datetime		✓	Must contain the date with hours set to zero. Ex: 2016-08-24T00:00:00.
periodStart	time		*	Start period of the entry. Ex: 08:00:00. *Required when specified via configuration.
periodEnd	time		*	End period of the entry. Ex: 12:00:00. *Required when specified via configuration.
workTime	time		*	Total time of the entry. Ex: 04:00:00. *Required when specified via configuration.
workTypeName	string		✓	Type of the recorded time.
createdBy	person		✓	Data of the person who created the entry. view documentation
createdByTeam	team		*	Data of the team of the person who recorded the expense. view documentation

Contract Hour Consumption » Expenses

timeAgreementConsumption.expenses[n]

Property	Type	Size	Required	Description
id	int	1		Unique identifier field for the expense.
type	string	128	✓	Description of the expense type related to the entry.
serviceReport	string	128		Number of the service report issued containing the expense. Read-only.
createdBy	person	128	✓	Data of the person who recorded the expense. view documentation
createdByTeam	team	128		Data of the team of the person who recorded the expense. view documentation
date	datetime UTC		✓	Date of the expense creation. Must be less than or equal to the current date. The date should be in UTC format*.
quantity	int	1	*	Quantity of the expense. *Required when the value field is not provided.
value	decimal	18,2	*	Value in currency recorded. *Required when the quantity field is not provided.

Person

timeAgreementConsumption.timeAppointments[n].createdBy

timeAgreementConsumption.expenses[n].createdBy

timeAgreementConsumption.clients[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).

Team

timeAgreementConsumption.timeAppointments[n].createdByTeam timeAgreementConsumption.expenses[n].createdByTeam

Property	Type	Size	Required	Description
id	int		✓	Id (Ref. code) of the team (Read-only).
name	string	128		Name of the team (Read-only).

Working with the Data

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

To generate an API key (token), go to Movidesk, navigate 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 need to generate a new access key, but remember that generating a new key will cause all programs using the old key to stop working.

All data flows (Visualization) must have the JSON format as shown in the example below:

{
 "id": 1,
 "name": "contract",
 "baseAmount": 0,
 "exceededHourAmount": 0,
 "renewalDay": 5,
 "contractedHours": 30,
 "differentiateHoursFranchise": false,
 "differentiateHoursConsumption": false,
 "period": "2018-12-01T00:00:00",
 "consumedHours": 1,
 "discount": null,
 "discountType": null,
 "timeAppointments": [
    {
       "id": 222,
       "activity": "Activity",
       "date": "2018-12-19T00:00:00",
       "periodStart": "10:41:00",
       "periodEnd": "11:41:00",
       "workTime": "01:00:00",
       "workTypeName": "Extra",
       "createdBy": {
             "id": "571AE126-101B-43C7",
             "personType": 1,
             "profileType": 3,
             "businessName": "Luiz",
             "email": "email@movidesk.com",
             "phone": "47983232821",
             "address": null,
             "complement": null,
             "cep": null,
             "city": null,
             "bairro": null,
             "number": null,
             "reference": null
       },
       "createdByTeam": {
             "id": 1755,
             "name": "Name"
       },
       "ticketNumber": "98868",
       "actionNumber": 83
    }
 ],
    "expenses": [
       {
          "id": 74,
          "type": "type",
          "serviceReport": "0",
          "createdBy": {
              "id": "571AE126-101B-43C7",
              "personType": 1,
              "profileType": 3,
              "businessName": "Tatiana ",
              "email": "andre.vargas@movidesk.com",
              "phone": "47-84211821",
              "address": null,
              "complement": null,
              "cep": null,
              "city": null,
              "bairro": null,
              "number": null,
              "reference": null
        },
        "createdByTeam": null,
        "date": "2018-12-18T00:00:00",
        "quantity": 14,
        "value": 70
     }
 ],
 "clients": [
     {
          "id": "123",
          "personType": 2,
          "profileType": 2,
          "businessName": "Maria",
          "email": maria@gmail.com,
          "phone": 48996888222,
          "isDeleted": false,
          "organization": null,
          "address": null,
          "complement": null,
          "cep": null,
          "city": null,
          "bairro": null,
          "number": null,
          "reference": null
     },
     {
          "id": "312",
          "personType": 2,
          "profileType": 2,
          "businessName": "João",
          "email": joao@gmail.com,
          "phone": 48996338222,
          "isDeleted": false,
          "organization": null,
          "address": null,
          "complement": null,
          "cep": null,
          "city": null,
          "bairro": null,
          "number": null,
          "reference": null
       }
    ]
 }

Getting Data

GET Method

Getting a Single Hour Contract

GET: /timeAgreementConsumption Parameters: name, token

Example:

Getting the contract with id 1

GET: https://api.movidesk.com/public/v1/timeAgreementConsumption?token=448f8647-50cb-47e2-995c-b2bbe474486a&name&startPeriod=startperiod&endPeriod=endperiod

Response:

  { 
    "id": 1,
    "name": "contract",
    "baseAmount": 0,
    "exceededHourAmount": 0,
    "renewalDay": 5,
    "contractedHours": 30,
  ... Other columns in the format of the layout above
  }