Add a list of measures by type (real)

This endpoint allows registering a list of real measures for a product or section, limiting the registration to measures of a single type (e.g., "TICKETS").

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

The URL must contain the following parameters:

Business external identifier (businessId).
Product or section external identifier (productId).
Name of the measure type configured in Orquest (demandType).

Below is an explanation of each of the fields that make 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

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.

[
  {
    "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, here is an example request:

POST /api/v1/import/business/BUSINESSID/product/PRODUCTID/demandtype/TICKETS/measures

[
  {
    "value": 3.0000,
    "from": "2024-07-18T09:00:00.000Z",
    "to": "2024-07-18T09:15:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 4.0000,
    "from": "2024-07-18T09:15:00.000Z",
    "to": "2024-07-18T09:30:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 1.0000,
    "from": "2024-07-18T09:30:00.000Z",
    "to": "2024-07-18T09:45:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 3.0000,
    "from": "2024-07-18T09:45:00.000Z",
    "to": "2024-07-18T10:00:00.000Z",
    "measure": "TICKETS"
  }
]

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 items.

The name of the measure must be exactly the same as configured in Orquest at the business level: Business configuration > Measure types > Name. It is necessary to respect case sensitivity, accents, etc. If the measure name does not match the one configured in Orquest or the one specified in the demandType parameter of the URL, the request will ignore that value.

If the data provided does not correspond to the measure specified in the demandType parameter of the URL, the values will be ignored. For example, if measures for type "SALES" are included in a "TICKETS" request, the "SALES" values will be ignored.

The value allows decimals, although the application will display only the number of decimals configured for the measure’s precision level: 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

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`	Non existent demand type id X	The measure type indicated in the `demandType` parameter of the URL is not 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, including those later ignored for not matching `demandType`.
-	The collection sent exceeds the limit of 400 items allowed. It is recommended to split the request into smaller batches.

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

Non existent demand type id X

The measure type indicated in the demandType parameter of the URL is not 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, including those later ignored for not matching demandType.

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?