Rewards

POST salary summary for period

---

This API retrieves the total rewards earned by users for tasks completed during a specified reporting period. The reporting period can either be provided in the request (dateFrom and dateTo) or defaults to the last closed reporting period if not specified. Rewards are only included for tasks marked with “is_reporting_period_closed” = true.

Method

POST /api.hesh.app/api/v1/public/rewards/summary

Method Returns

The method returns a list of rewards data for users within the specified period, including total rewards, time spent, and additional user details.

Permissions required

No specific permissions are mentioned, but the API should be accessed with valid credentials if required.

Request

• Headers:

  • x-tenant-id (string, UUID v4) - Tenant ID Example: 40dd0c53-2fa7-4193-82ae-14d4e62c20fb

• Body (application/json):

  • Body Parameters:

    • external_user_ids (array of strings, optional): An array of unique identifiers assigned to users by an external system or third-party service. If not provided, the response includes data for all users in the system.

  • Query Parameters:

    • dateFrom (date, optional): The start date of the reporting period in ISO 8601 format.

    • dateTo (date, optional): The end date of the reporting period in ISO 8601 format.

{
  "external_user_ids": [
    "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e"
  ]
}

Path parameters

This method does not require any additional path parameters.

Response

• 200 OK: Returns a JSON object containing rewards data for the specified period, including:

  • period: The date range for the reporting period.

  • currency: The type of currency or unit used for rewards (e.g., USD, coins).

  • users_rewards: A list of users and their associated rewards, including user details, total rewards, and time spent.

Response body (application/json):

{
  "period": {
    "date_from": "2024-01-01T09:05:22.553Z",
    "date_to": "2024-01-31T09:05:22.553Z"
  },
  "currency": "USD",
  "users_rewards": [
    {
      "user": {
        "user_id": "84567-83652",
        "external_user_id": "74893u7i8byed",
        "name": "Alia Simple"
      },
      "reward": 500,
      "time_spent": 456789
    }
  ]
}

Error Codes:

• 400 Bad Request — Invalid or missing request parameters, such as an invalid dateFrom and dateTo combination (e.g., dateFrom is later than dateTo)

• 500 Internal Server Error — Internal server error

Notes:

• If dateFrom and dateTo are provided, the system calculates rewards for all full calendar months within the range and returns the total for those months

• If no period is specified, the API defaults to the last closed reporting period

• Pagination is required when external_user_ids is not specified, as the response includes data for all users

• Rewards are only included for tasks with “is_reporting_period_closed” = true

Salary details for the period

---

This API method allows retrieving and updating reward details for users within a specified time period. It supports tracking user activities, task performance, and rewards earned, including bonuses and adjustments. Properties not provided in the request will remain unchanged.

Method

POST /api.hesh.app/api/v1/public/rewards/details?dateFrom={}&dateTo={}

Method Returns

The method returns a list of user reward details, including tasks, rewards, and production-related information.

Permissions required

No specific permissions are mentioned, but the API should be accessed with valid credentials if required.

Request

• Headers:

  • x-tenant-id (string, UUID v4) - Tenant ID Example: 40dd0c53-2fa7-4193-82ae-14d4e62c20fb

• Body (application/json):

  • Body Parameters:

    • user_ids (optional, array of strings): An array of unique identifiers assigned to users within the system. Example: ["04dcae99-2c57-4c02-af58-a5394c9dbacd"]

    • external_user_ids (optional, array of strings): An array of unique identifiers assigned to users by external systems. Example: ["35a90cdd-37f2-4d2b-9f48-5fcbc4ac1882

{
  user_ids?: [],
  external_user_ids?: [],
}

Path parameters

• dateFrom (required): The starting date for the activity tracking period. Must follow ISO 8601 format.

• dateTo (required): The ending date for the activity tracking period. Must follow ISO 8601 format.

Response

• 200 OK:

  Returns the reward details of users, including:

  • period (date range): The duration of tracked activities.

  • currency (string): The currency used for rewards (e.g., USD).

  • user (object):

    • user_id (string): The system-assigned user ID.

    • external_user_id (string): The external system-assigned user ID.

    • name (string): The full name of the user.

    • total_reward (number): The total rewards earned by the user.

    • total_time_spent (number): Time spent on activities in seconds.

    • task_rewards (array):

      • task (object):

        • task_id (string): Task identifier.

        • task_key (string): Task code.

        • title (string): Task name.

        • time_limit (number, optional): Estimated time for task completion (in seconds).

        • basic_reward (number): Standard reward for the task.

        • is_reporting_period_closed (boolean): Whether the reporting period is closed.

        • bonuses (array): List of bonuses:

          • id (string): Bonus ID.

          • name (string): Bonus description.

          • value (number): Bonus amount.

          • bonus_type (string): Type of bonus (percent or fixed).

      • order (object, optional):

        • order_id (string): Order identifier.

        • external_order_id (string): External order identifier.

        • order_key (string): Order code.

      • production (object, optional):

        • production_id (string): Production identifier.

        • production_key (string): Production code.

        • product_id (string): Product identifier.

        • variant (string): Product variant.

        • barcode (string): Product barcode.

      • rewards (object):

        • time_spent (number): Actual time spent on the task.

        • time_correction (number): Adjustments to the time spent.

        • reward (number): Basic reward earned.

        • bonus (number): Bonuses earned.

        • reward_correction (number): Adjustments to the reward.

        • total (number): Total rewards after adjustments.

        • work_periods (array): List of work periods with start and end times (ISO 8601 format).

Response body (application/json):

{
  "period": {
    "date_from": "2024-01-01T09:05:22.553Z",
    "date_to": "2024-01-31T09:05:22.553Z"
  },
  "currency": "USD",
  "users_rewards": [
    {
      "user": {
        "user_id": "84567-83652",
        "external_user_id": "74893u7i8byed",
        "name": "Alia Simple"
      },
      "reward": 500,
      "time_spent": 456789
    }
  ]
}

Error Codes:

• 400 Bad Request — Invalid or missing request parameters, such as an invalid dateFrom and dateTo combination (e.g., dateFrom is later than dateTo)

• 404 Not Found — No users found for the specified IDs

• 500 Internal Server Error — Internal server error

Notes:

• Ensure all date parameters are in ISO 8601 format.

• This endpoint does not modify existing reward data unless explicitly specified in the request body.

• When retrieving rewards, ensure permissions align with the user’s access scope.