Añadir lista de medidas (reales)

Este endpoint permite registrar una lista de medidas reales para un producto o sección.

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

La URL debe contener el identificador de negocio (businessId) y el identificador de producto o sección (productId).

A continuación, se expone una explicación de cada uno de los campos que conforman el cuerpo de la petición.

Todos los campos de esta petición son obligatorios, por eso están marcados con un asterisco (*).

Cuerpo de la petición

Análisis del JSON 
[
  {
    "value": 0,
    "from": "string",
    "to": "string",
    "measure": "string"
  }
]
Detalles

  • value*: valor numérico de la medida.

  • from*: inicio del intervalo de tiempo en UTC y en formato yyyy-MM-ddTHH:mm:ss.SSSZ.

  • to*: fin del intervalo de tiempo en UTC y en formato yyyy-MM-ddTHH:mm:ss.SSSZ.

  • measure*: nombre configurado en Orquest para la medida.

Ejemplo de la petición

Una vez realizado el análisis de los distintos campos, se muestra un ejemplo de la petición:

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"
  }
]

Si los datos de la petición son correctos, al finalizar el proceso se devolverán los valores de los días involucrados en la operación con los datos desglosados en intervalos de 15 minutos.

Consideraciones

El formato de fecha utilizado es UTC, pero al insertar datos es necesario considerar la zona horaria del servicio.

Cuando se envía un conjunto de medidas para un día, se eliminan todos los valores previamente registrados para ese día y se reemplazan por los de la petición, por eso es fundamental enviar días completos.

Por ejemplo, si se envía un único valor para el día 2024-07-18 de 10:00 a 10:15, se perderán todos los valores registrados anteriormente para ese día y solo se mantendrá el valor enviado en la petición.

El formato de fecha utilizado es UTC y las medidas se deben agrupar por días completos.
Ver ejemplo de un día completo

Si la zona horaria del servicio es UTC+2, los datos transformados a UTC para el día 2024-07-18 deben abarcar desde las 22:00 UTC del día de antes (2024-07-17), hasta las 22:00 UTC del mismo día (2024-07-18). Esto asegura que, al insertar los datos con la hora local, las medidas coincidan correctamente con un día completo en la zona horaria del servicio.

Así, si hay 5 TICKETS a las 00:00 UTC+2 (hora local), este valor debe incluirse en la petición con la hora transformada a UTC, en este caso, las 22:00 UTC del día anterior. Por tanto, el cuerpo de la petición para el día completo sería el siguiente:

[
  {"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"}
]

La inserción de medidas de este ejemplo se realizará en UTC+2 para el día 2024-07-18 completo (de 00:00 a 00:00).

Esta petición tiene un límite de 400 elementos.

El nombre de la medida debe ser exactamente igual que el que está configurado en Orquest a nivel de negocio: Configuración de negocio > Tipos de medidas > Nombre. Es necesario respetar la distinción entre mayúsculas y minúsculas, tildes, etc.

El valor admite decimales, aunque en la aplicación se mostrará solo el número de decimales que se haya configurado para el nivel de precisión de la medida: Configuración de negocio > Tipos de medidas > Precisión.

Orquest siempre almacena los valores de las medidas en intervalos de 15 minutos: si se envía un valor para un periodo de tiempo de una hora, por ejemplo, Orquest dividirá este valor de manera equitativa en cuatro intervalos de 15 minutos.

Códigos de error

Además de los errores comunes, este endpoint puede devolver los siguientes códigos:

Código Mensaje Descripción

400 Bad Request

-

El cuerpo de la petición no tiene un formato JSON válido, o alguno de los campos de fecha (from/to) no cumple el formato yyyy-MM-ddTHH:mm:ss.SSSZ.

406 Not Acceptable

Not a valid demand type: X

El campo measure no coincide con ningún tipo de medida configurado en el negocio.

Value mut be positive or zero

El campo value tiene un valor negativo en uno o más elementos. Literal tal cual lo devuelve el backend, con la errata "mut" en vez de "must".

Measure type cannot be null

Falta el campo measure en uno o más elementos.

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

Falta el campo from o to en uno o más elementos.

Measure time range is invalid

El intervalo definido entre from y to de uno o más elementos no es múltiplo de 15 minutos, o to no es posterior a from.

Overlapped measures

Dos o más elementos de la petición solapan su intervalo de tiempo.

-

La colección enviada supera el límite de 400 elementos permitido. Se recomienda dividir la petición en lotes más pequeños.

Enlaces de interés

¿Qué es una medida?

¿Qué son las medidas reales?

¿Cómo integrar medidas?