Hello, how can we help you?

  1. Home page
  2. Return to search
  3. 05. Integrations
  4. API's
Movidesk API - Hour Contract - Hour Consumption
21 min
Created by Andre Azevedo Vargas on 1/22/2019 11:01 AM
Updated by Karine Moreira on 9/24/2024 4:27 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, 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 Entries
timeAgreementConsumption.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
  }
Was this article useful?
Recently viewed