Create or update needs

This endpoint allows to update or create the needs for a day.

PUT /api/v1/businesses/{businessId}/products/{productId}/needs/{yyyy-MM-dd}

In the request URL, the following parameters must be specified:

  • Business external identifier (businessId).

  • Product or section external identifier (productId).

  • Date for which the needs are created or updated in the yyyy-MM-dd format.

Below are the fields that make up the request body, some of which are mandatory for the request to be successful.

Mandatory fields are marked with an asterisk (*).

Request body

JSON Analysis 
[
  {
    "startMinuteDay": 0,
    "duration": 0,
    "location": "string",
    "value": 0,
    "zone": "string"
  }
]
Details

  • startMinuteDay*: start of the need in minutes from 00:00. For example, 600 for 10:00.

  • duration*: duration of the need period in minutes.

  • location*: external identifier of the task linked to the need.

  • value*: number of people needed to cover the need.

  • zone: external identifier for the zone. If no zone is added, the general zone will be used.

Request example

After analyzing the fields, an example of the request is shown:

PUT /api/v1/businesses/BUSINESSID/products/PRODUCTID/needs/2024-07-19
[
  {
    "startMinuteDay": 600,
    "duration": 60,
    "location": "03",
    "value": 5,
    "zone": "General"
  },
  {
    "startMinuteDay": 540,
    "duration": 120,
    "location": "06",
    "value": 2,
    "zone": "General"
  }
]

If all the request data is correct, the following needs will be created for the day 2024-07-19:

  • Task 03: 5 people at 10:00 with a duration of one hour.

  • Task 06: 2 people at 9:00 with a duration of two hours.

Considerations

The request takes the service time zone into account. For example, if the service is in UTC+2, the startMinuteDay field will consider that time zone.

If an empty array ([]) is sent, all needs for that day are deleted.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

404 Not Found

Location not found

The task specified in location is not registered in the business task catalog or does not have an external identifier.

406 Not Acceptable

Start minute cannot be null

The startMinuteDay field is missing in one or more items.

Start minute should be positive

The startMinuteDay field has a negative value in one or more items.

Duration cannot be null

The duration field is missing in one or more items.

Duration should be positive

The duration field has a negative or zero value in one or more items.

Location cannot be empty

The location field is missing in one or more items.

The value for the need should be positive or zero

The value field has a negative value in one or more items.

409 Conflict

-

A conflict occurred while saving the needs. It is recommended to check that the data sent does not violate any integrity constraint.

Useful links

What are needs?

What is the task catalog?