Añadir lista de medidas (previsión)

Este endpoint permite registrar una lista de medidas de previsión (forecast) para un producto o sección.

PUT /api/v1/businesses/{businessId}/product/{productId}/forecast

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:

PUT /api/v1/businesses/BUSINESSID/product/PRODUCTID/forecast
[
  {
    "value": 14.0000,
    "from": "2024-07-18T07:00:00.000Z",
    "to": "2024-07-18T08:00:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 15.0000,
    "from": "2024-07-18T08:00:00.000Z",
    "to": "2024-07-18T09:00:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 100.0000,
    "from": "2024-07-18T07:00:00.000Z",
    "to": "2024-07-18T08:00:00.000Z",
    "measure": "SALES"
  },
  {
    "value": 120.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, se devolverá un estado 200 OK.

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.

A diferencia de otros endpoints de este dominio, esta petición no valida que el intervalo de cada elemento sea múltiplo de 15 minutos. Un intervalo que no lo sea no da ningún error: los datos previos para ese periodo se eliminan y los nuevos no llegan a guardarse, perdiéndose en silencio. Se recomienda enviar siempre intervalos en múltiplos 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

Bad number of observations

La colección enviada está vacía o supera el límite de 400 elementos permitido.

Demand type not found

El nombre de la medida (measure) de uno o más elementos no coincide con ningún tipo 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 is required / To is required

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

Business id is required / Product id is required

Falta el identificador de negocio o de producto.

Observations are required

Falta la colección de observaciones.

Overlapped measures

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

-

El cuerpo de la petición no tiene un formato JSON válido.

Enlaces de interés

¿Qué es una medida?

¿Qué es el forecast?

¿Cómo integrar medidas?