Get assignments by service

This endpoint returns the assignments of a service within a period not exceeding 31 days.

GET /api/v2/business/{businessId}/services/{serviceId}/assignments/from/{yyyy-MM-dd}/to/{yyyy-MM-dd}

If the data included in the request is correct —businessId and serviceId— the response will contain the service assignments for that period.

Response example

[
    {
        "product": "0001-G",
        "blockedType": "NONE",
        "person": "1006355",
        "day": "2024-05-02",
        "presence": {
            "worked": false,
            "timeFrames": [
                {
                    "startMinuteDay": 0,
                    "duration": 1425,
                    "paid": false,
                    "worked": false
                }
            ]
        },
        "virtual": false
    },
    {
        "product": "0001-G",
        "blockedType": "NONE",
        "person": "1006355",
        "day": "2024-05-04",
        "presence": {
            "worked": true,
            "timeFrames": [
                {
                    "startMinuteDay": 450,
                    "duration": 240,
                    "paid": true,
                    "location": {
                        "color": "#fed46b",
                        "description": "Perform commercial tasks: customer service, collection, orders at the point of sale...",
                        "name": "Sales",
                        "shortName": "S",
                        "requiredLevel": 1,
                        "priority": 5,
                        "type": "VARIABLE",
                        "shouldAvoidOvercover": false,
                        "system": false,
                        "category": "Operational",
                        "product": "0001-G",
                        "id": "03",
                        "zone": "General"
                    },
                    "worked": true
                },
                {
                    "startMinuteDay": 780,
                    "duration": 300,
                    "paid": true,
                    "location": {
                        "color": "#7f7f7f",
                        "description": "Creation of the workshop opening checklist",
                        "name": "Opening",
                        "shortName": "OP",
                        "requiredLevel": 1,
                        "priority": 5,
                        "type": "FIXED",
                        "shouldAvoidOvercover": false,
                        "system": false,
                        "category": "Operational",
                        "product": "0001-G",
                        "id": "01",
                        "zone": "General"
                    },
                    "worked": true
                }
            ]
        },
        "virtual": false
    }
]
Details

  • product: external identifier of the product (section) to which the assignment belongs.

  • blockedType: if the assignment is blocked and how (NONE, EXTENSIBLE_WORK, NON_EXTENSIBLE_WORK, EXTENSIBLE_TIME, NON_EXTENSIBLE_TIME, DAILY_WORKED).

  • person: employee external identifier.

  • day: day of the assignment in yyyy-MM-dd format.

  • presence: type of assignment that contains the work periods (timeFrames) with their locations. It contains the following fields:

    • startTime: the start time of the presence in minutes from the beginning of the day (00:00). It can be null, as the actual start time can be calculated as the sum of the durations of its time periods (timeFrames).

    • duration: the duration in minutes of the entire presence. Can be null, as the actual duration can be calculated as the sum of the durations of its timeFrames.

    • worked: whether the type of assignment or presence is worked (true) or if it is a rest day (false).

    • timeFrames: set of time intervals that contain the tasks to be performed. For each interval, the following information is included:

      • startMinuteDay: start of the interval in minutes elapsed since the beginning of the day (00:00).

      • duration: duration of the interval in minutes.

      • paid: whether the interval, whether work or rest, is paid (true) or not (false).

      • worked: determines if the timeFrame has an assigned task (true) or not (false).

      • location: task to be performed in the defined interval. For each task, the following information is included:

        • color: color configured in Orquest for the task.

        • description: description of the task defined in Orquest.

        • name: name of the task in Orquest.

        • shortName: task abbreviation in Orquest.

        • requiredLevel: skill level required to perform the task. Ranges from 0 (no training needed) to 3 (maximum training level) and must be previously configured in Orquest.

        • priority: priority of task coverage. Ranges from 0 (low) to 5 (high) and must be previously configured in Orquest.

        • maxResources: limit of people for the task.

        • type: type of task, whether it is fixed, variable, or non-plannable (FIXED, VARIABLE, NON_PLANIFIABLE).

        • shouldAvoidOvercover: if this parameter is true, the task will not be overcovered.

        • system: determines if the task was created by the system (true) or by the user (false).

        • category: category of the task previously configured in Orquest.

        • product: external identifier of the product or section.

        • id: external identifier of the task.

        • metadata: any additional data that has been previously configured for the task in Orquest. The metadata structure must be previously configured.

        • zone: physical place in the service (store, restaurant, etc.) where the location is carried out.

  • virtual: indicates whether the employee is virtual (true) or real (false).

The first assignment in the example corresponds to a day off, as the worked field in the presence is false. Additionally, it only has one timeFrame with no associated task, covering the entire day, and both the paid and worked fields are also false.

In the second assignment example, the worked field in the presence is true and it indicates the characteristics of the tasks performed by the employee in each timeFrame. The level of detail in the response will depend on the business configuration for the different tasks.

Considerations

If there are no assignments for the indicated period, the request will return an empty array [].

If the service specified in the URL does not exist in the business, the request will return a 404 Not Found error, specifying in the message not exists.

If the interval specified in the URL exceeds 31 days, the request will return a 406 Not Acceptable error, specifying in the message The request exceeded the maximum number of days allowed.

Useful links

What is an assignment?

What is a task?