Add a list of measures (real)

This endpoint allows registering a list of real measures for a product or section.

POST /api/v1/import/business/{businessId}/product/{productId}/measures

The URL must contain the business identifier (businessId) and the product or section identifier (productId).

Below is an explanation of each field that makes up the body of the request.

All fields in this request are mandatory, which is why they are marked with an asterisk (*).

Request body

JSON Analysis 
[
  {
    "value": 0,
    "from": "string",
    "to": "string",
    "measure": "string"
  }
]
Details

  • value*: numerical value of the measure.

  • from*: start of the time interval in UTC format yyyy-MM-ddTHH:mm:ss.SSSZ.

  • to*: end of the time interval in UTC format yyyy-MM-ddTHH:mm:ss.SSSZ.

  • measure*: name configured in Orquest for the measure.

Request example

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

POST /api/v1/import/business/BUSINESSID/product/PRODUCTID/measures
[
  {
    "value": 12.0000,
    "from": "2024-07-18T07:00:00.000Z",
    "to": "2024-07-18T08:00:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 16.0000,
    "from": "2024-07-18T08:00:00.000Z",
    "to": "2024-07-18T09:00:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 110.0000,
    "from": "2024-07-18T07:00:00.000Z",
    "to": "2024-07-18T08:00:00.000Z",
    "measure": "SALES"
  },
  {
    "value": 125.0000,
    "from": "2024-07-18T08:00:00.000Z",
    "to": "2024-07-18T09:00:00.000Z",
    "measure": "SALES"
  }
]

If the request data is correct, the process will return the values of the days involved in the operation with the data broken down into 15-minute intervals.

Considerations

The date format used is UTC, but when inserting data, the service time zone must be considered.

When a set of measures is sent for a day, all previously recorded values for that day are deleted and replaced by those in the request. Therefore, it is essential to send complete days.

For example, if a single value is sent for the day 2024-07-18 from 10:00 to 10:15, all previously recorded values for that day will be lost, and only the value sent in the request will remain.

The date format used is UTC, and measures must be grouped by complete days.
Example of a complete day

If the service time zone is UTC+2, the data transformed to UTC for the day 2024-07-18 must span from 22:00 UTC of the previous day (2024-07-17) to 22:00 UTC of the same day (2024-07-18). This ensures that when inserting the data with the local time, the measures correctly match a full day in the service time zone.

Thus, if there are 5 TICKETS at 00:00 UTC+2 (local time), this value must be included in the request with the time converted to UTC, which in this case is 22:00 UTC of the previous day. Therefore, the body of the request for the entire day would be as follows:

[
  {"value": 5.0000, "from": "2024-07-17T22:00:00.000Z", "to": "2024-07-17T23:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-17T23:00:00.000Z", "to": "2024-07-18T00:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T00:00:00.000Z", "to": "2024-07-18T01:00:00.000Z", "measure": "TICKETS"},
  {"value": 2.0000, "from": "2024-07-18T01:00:00.000Z", "to": "2024-07-18T02:00:00.000Z", "measure": "TICKETS"},
  {"value": 6.0000, "from": "2024-07-18T02:00:00.000Z", "to": "2024-07-18T03:00:00.000Z", "measure": "TICKETS"},
  {"value": 5.0000, "from": "2024-07-18T03:00:00.000Z", "to": "2024-07-18T04:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T04:00:00.000Z", "to": "2024-07-18T05:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T05:00:00.000Z", "to": "2024-07-18T06:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T06:00:00.000Z", "to": "2024-07-18T07:00:00.000Z", "measure": "TICKETS"},
  {"value": 2.0000, "from": "2024-07-18T07:00:00.000Z", "to": "2024-07-18T08:00:00.000Z", "measure": "TICKETS"},
  {"value": 6.0000, "from": "2024-07-18T08:00:00.000Z", "to": "2024-07-18T09:00:00.000Z", "measure": "TICKETS"},
  {"value": 5.0000, "from": "2024-07-18T09:00:00.000Z", "to": "2024-07-18T10:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T10:00:00.000Z", "to": "2024-07-18T11:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T11:00:00.000Z", "to": "2024-07-18T12:00:00.000Z", "measure": "TICKETS"},
  {"value": 2.0000, "from": "2024-07-18T12:00:00.000Z", "to": "2024-07-18T13:00:00.000Z", "measure": "TICKETS"},
  {"value": 6.0000, "from": "2024-07-18T13:00:00.000Z", "to": "2024-07-18T14:00:00.000Z", "measure": "TICKETS"},
  {"value": 5.0000, "from": "2024-07-18T14:00:00.000Z", "to": "2024-07-18T15:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T15:00:00.000Z", "to": "2024-07-18T16:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T16:00:00.000Z", "to": "2024-07-18T17:00:00.000Z", "measure": "TICKETS"},
  {"value": 2.0000, "from": "2024-07-18T17:00:00.000Z", "to": "2024-07-18T18:00:00.000Z", "measure": "TICKETS"},
  {"value": 6.0000, "from": "2024-07-18T18:00:00.000Z", "to": "2024-07-18T19:00:00.000Z", "measure": "TICKETS"},
  {"value": 5.0000, "from": "2024-07-18T19:00:00.000Z", "to": "2024-07-18T20:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T20:00:00.000Z", "to": "2024-07-18T21:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T21:00:00.000Z", "to": "2024-07-18T22:00:00.000Z", "measure": "TICKETS"}
]

The insertion of measures from this example will be performed in UTC+2 for the full day of 2024-07-18 (from 00:00 to 00:00).

This request has a limit of 400 elements.

The name of the measure must be exactly as configured in Orquest at the business level: Business configuration > Measure types > Name. It is necessary to respect the distinction between uppercase and lowercase, accents, etc.

The value can accept decimals, although in the application, only the number of decimals configured for the measure’s precision level will be shown: Business configuration > Measure types > Precision.

Orquest always stores measure values in 15-minute intervals: if a value is sent for a one-hour period, for example, Orquest will divide this value equally into four 15-minute intervals.

Error codes

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

Code Message Description

400 Bad Request

-

The request body is not in a valid JSON format, or one of the date fields (from/to) does not follow the yyyy-MM-ddTHH:mm:ss.SSSZ format.

406 Not Acceptable

Not a valid demand type: X

The measure field does not match any measure type configured in the business.

Value mut be positive or zero

The value field has a negative value in one or more items. This is the literal as returned by the backend, with the typo "mut" instead of "must".

Measure type cannot be null

The measure field is missing in one or more items.

From in measure cannot be null / To in measure cannot be null

The from or to field is missing in one or more items.

Measure time range is invalid

The interval defined between from and to of one or more items is not a multiple of 15 minutes, or to is not later than from.

Overlapped measures

Two or more items in the request have overlapping time intervals.

-

The collection sent exceeds the limit of 400 items allowed. It is recommended to split the request into smaller batches.

Useful links

What is a measure?

What are real measures?

How to integrate measures?