I want to integrate clockguards

What are clockguards?

As detailed here, clockguards refer to the records of an employee’s entry or exit at their workplace, whether for worked time or breaks.

How to integrate clockguards?

To record new clockguards in the system, you can use the following endpoint:

Add a list of clockguards: allows adding a list of clockguards as long as the employee identifier and the relevant clockguard data (record type, activity type, date, etc.) are included.

These clockguards, by default, will appear as consolidated in the system and should be the grouping of two records, one for entry ("recordType": "IN") and one for exit ("recordType": "OUT").

To change this behavior so that records are not consolidated in the integration, it will be necessary to modify the business configuration (importer properties).

What operations can be performed in clockguards integration?

Add a worked time clockguard

To add a new worked time clockguard, simply indicate it in the activity type of the request: "clockguardType": "WORK".

Example

[
  {
    "employeeId": "1006357",
    "clockguardType": "WORK",
    "recordType": "IN",
    "date": "2024-06-15T09:00:00Z"
  },
  {
    "employeeId": "1006357",
    "clockguardType": "WORK",
    "recordType": "OUT",
    "date": "2024-06-15T14:00:00Z"
  }
]

Add a break clockguard

To add a break, simply indicate it in the activity type of the request: "clockguardType": "REST".

Example

[
  {
    "employeeId": "1006357",
    "clockguardType": "REST",
    "recordType": "IN",
    "date": "2024-06-15T14:00:00Z"
  },
  {
    "employeeId": "1006357",
    "clockguardType": "REST",
    "recordType": "OUT",
    "date": "2024-06-15T16:00:00Z"
  }
]

Delete clockguards

Considering the distinction between record and consolidated clockguards explained here, the options to delete them are as follows:

Delete clockguard records. Allows deleting clockguards records of a product for a given day. If the record has been consolidated, only the record will be deleted, not the consolidation.
Delete consolidated clockguards. Allows deleting consolidated clockguards linked to a product on a specific day. Consolidated clockguards are deleted, but not the records.
Delete a collection of clockguards. Allows deleting consolidated clockguards whose identifiers are indicated in the URL. Consolidated clockguards are deleted, but not the records.
Delete a clockguard. Allows deleting the consolidated clockguard whose identifier is indicated in the URL. The consolidated clockguards is deleted, but not the record.

Get clockguards

To query consolidated clockguards, you can use the following endpoints:

Get clockguard records by service. Returns consolidated clockguards made in a service within a specific period.
Get clockguard records by product. Returns consolidated clockguards of a product within a specific period.

FAQ

What time zone is considered for integration?

Times must be sent in UTC and the publication is made considering the service’s time zone.

For example, in a service with a time zone of UTC+2, the following clockguards are recorded:

[
  {
    "employeeId": "1006357",
    "clockguardType": "WORK",
    "recordType": "IN",
    "date": "2024-06-13T18:00:00Z"
  },
  {
    "employeeId": "1006357",
    "clockguardType": "WORK",
    "recordType": "OUT",
    "date": "2024-06-13T20:00:00Z"
  }
]

The result in the system is a clockguard from 20:00 to 22:00.

The query of this clockguard is also returned in UTC:

[
    {
        "employeeId": "1006357",
        "type": "WORK",
        "checkIn": "2024-06-13T18:00:00.000Z",
        "checkOut": "2024-06-13T20:00:00.000Z",
        "orquestId": 230359810
    }
]

What happens if an erroneous clockguard is created?

If there are errors in the record, for example, the same type of clockguard (IN), the API returns the data as it was recorded. However, that clockguard will not be considered in planning or counters, as it would be incomplete.

What is the difference between get by service and get by product?

The difference between get clockguards by service and by product lies in the level of detail and the segmentation of the obtained data.

Get clockguards by service: focuses on the clockguards of the store/restaurant/workshop, etc., without necessarily distinguishing between the different sections or departments within it. If the task (location) where the clockguard was performed is included at the time of the record, this query will also provide information on the product identifier.
Get clockguards by product: focuses on the clockguards of a specific section. If the task (location) where the clockguard was performed is included at the time of the record, this query will provide detailed information on that task.

Service
Product

[
    {
        "employeeId": "1006357",
        "type": "WORK",
        "checkIn": "2024-06-16T14:00:00.000Z",
        "checkOut": "2024-06-16T19:00:00.000Z",
        "orquestId": 230349899
    },
    {
        "employeeId": "1006356",
        "type": "WORK",
        "checkIn": "2024-06-16T15:00:00.000Z",
        "checkOut": "2024-06-16T19:00:00.000Z",
        "orquestId": 230349904
    },
    {
        "employeeId": "1006357",
        "productId": "0001",
        "locationId": "04",
        "type": "WORK",
        "checkIn": "2024-06-15T09:00:00.000Z",
        "latIn": 37.389091,
        "lonIn": -5.984459,
        "deviceIn": "12345",
        "checkOut": "2024-06-15T14:00:00.000Z",
        "latOut": 37.389091,
        "lonOut": -5.984459,
        "deviceOut": "12345",
        "orquestId": 230349910
    }
]

[
    {
        "employeeId": "1006357",
        "type": "WORK",
        "checkIn": "2024-06-16T14:00:00.000Z",
        "checkOut": "2024-06-16T19:00:00.000Z",
        "orquestId": 230349899
    },
    {
        "employeeId": "1006356",
        "type": "WORK",
        "checkIn": "2024-06-16T15:00:00.000Z",
        "checkOut": "2024-06-16T19:00:00.000Z",
        "orquestId": 230349904
    },
    {
        "employeeId": "1006357",
        "location": {
            "color": "#c5f2ff",
            "description": "annual inventory",
            "name": "INVENTORY",
            "shortName": "INV",
            "requiredLevel": 0,
            "priority": 1,
            "type": "UNPLANNED",
            "shouldAvoidOvercover": false,
            "system": false,
            "product": "0001-G",
            "id": "04"
        },
        "type": "WORK",
        "checkIn": "2024-06-15T09:00:00.000Z",
        "latIn": 37.389091,
        "lonIn": -5.984459,
        "deviceIn": "12345",
        "checkOut": "2024-06-15T14:00:00.000Z",
        "latOut": 37.389091,
        "lonOut": -5.984459,
        "orquestId": 230349910
    }
]

The choice between one query and another will depend on the business analysis and management needs.

Where is the orquestId obtained from?

In the clockguards consultation, both by service and by product, the response contains the orquestId or internal identifier of each clockguard, necessary for the requests in which they are deleted through their identifier.

Best practices

To ensure proper management of clockguard records and avoid inconsistencies in the processed information, it is recommended to follow these best practices when sending data via API:

Avoid duplicate submissions. Each record should ideally be sent only once to prevent duplicate entries that could affect the pairing of clock-in and clock-out records.
Maintain chronological order. Records should be sent in the order they occurred, ensuring that clock-in records precede clock-out records. Disordered data may result in incorrect pairings or processing difficulties.
Ensure data integrity. Incomplete or incorrect records may interfere with the correct identification of paired clockguards.

Following these practices optimizes data processing and ensures that clockguards are registered reliably and consistently in the system.