Quiero integrar medidas

¿Qué son las medidas?

Tal y como se detalla aquí, las medidas de un negocio son aquellos indicadores cuantitativos utilizados para evaluar diferentes aspectos del rendimiento, como ventas, número de tickets, pedidos, footfall, etc.

¿Cómo integrar medidas?

Para integrar medidas en el sistema, hay dos opciones: vía SFTP y vía API.

  • Vía SFTP. Los archivos CSV se depositan en un directorio SFTP para que se procesen tal y como se detalla aquí.

  • Vía API. La API de Orquest proporciona diferentes endpoints para enviar y consultar las medidas configuradas en un negocio.

A continuación, se presenta un desglose de distintos escenarios y los endpoints que son útiles en cada uno de ellos.

¿Qué operaciones se pueden realizar en la integración de medidas vía API?

Añadir una lista de medidas

Para registrar medidas a través de la API, se pueden utilizar los siguientes endpoints:

La elección de un endpoint u otro dependerá de la información que se quiera integrar en Orquest: si se trata de las medidas reales (datos a pasado) o del forecast (datos a futuro para realizar la previsión).

Añadir lista de medidas de un solo tipo

Considerando las limitaciones de los endpoints del escenario anterior —400 elementos por petición—, la API de Orquest proporciona una alternativa: añadir medidas de un solo tipo (por ejemplo, "TICKETS"). Para ello, las peticiones se deben realizar a los siguientes endpoints:

En estas peticiones, se especifica dentro de la URL el parámetro demandType, es decir, el tipo de medida para el que se insertan los datos.

Como en el escenario anterior, la elección de un endpoint u otro dependerá de la información que se quiera integrar en Orquest: si se trata de las medidas reales (datos a pasado) o del forecast (datos a futuro para realizar la previsión).

Actualizar medidas

Tal y como se detalla en la documentación de cada uno de los endpoints, las medidas se deben agrupar por día. Cuando una petición incluye medidas para un día concreto, se borran todos los valores de ese día registrados anteriormente y se actualizan por aquellos valores que se hayan incluido en la petición.

Por tanto, para esta operación, es necesario realizar una petición con los datos actualizados de un día completo a los siguientes endpoints:

La elección del endpoint dependerá de si son medidas reales o forecast, así como de si se envían las medidas por tipo o no.

Eliminar medidas

Siguiendo la lógica de la actualización de medidas expuesta anteriormente, si la petición incluye una sola medida con valor 0, se perderán todos los valores de ese día registrados anteriormente para esa medida.

Ver ejemplo

Si se realiza la siguiente petición, se borran todos los valores de "TICKETS" para el día 18/07/2024:

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

Al igual que en el escenario anterior, los siguientes endpoints permiten borrar medidas en el sistema:

Consultar medidas

La API de Orquest permite consultar los tres tipos de medidas del sistema, es decir, la proyección, la previsión y las medidas reales:

  • Consultar proyección. Devuelve la proyección de medidas, es decir, la previsión aprobada por el usuario.

  • Consultar previsión (forecast). Devuelve la previsión de medidas, es decir, la estimación que hace Orquest o un sistema externo con base en las medidas reales.

  • Consultar medidas (reales). Devuelve las medidas reales, es decir, los datos existentes que han sido obtenidos de los respectivos indicadores.

En cualquiera de las peticiones, el rango de consulta no debe exceder los 30 días y las medidas siempre se devolverán en UTC y en intervalos de 15 minutos.

Además, es posible filtrar los resultados por tipo de medida, basta con añadir el parámetro demandTypeNames a la URL, tal y como se detalla en la documentación de cada uno de los endpoints listados anteriormente.

Ver ejemplo

A continuación, se expone un ejemplo con la consulta de medidas reales filtrando por el tipo de medida SALES.

GET /api/v1/business/BUSINESSID/product/PRODUCTID/demand/from/2024-07-15/to/2024-07-31?demandTypeNames=SALES

Fragmento de respuesta:

[
    {
        "value": 1.25,
        "from": "2024-07-17T22:00:00.000Z",
        "to": "2024-07-17T22:15:00.000Z",
        "measure": "SALES"
    },
    {
        "value": 1.25,
        "from": "2024-07-17T22:15:00.000Z",
        "to": "2024-07-17T22:30:00.000Z",
        "measure": "SALES"
    },
    {
        "value": 1.25,
        "from": "2024-07-17T22:30:00.000Z",
        "to": "2024-07-17T22:45:00.000Z",
        "measure": "SALES"
    },
    {
        "value": 1.25,
        "from": "2024-07-17T22:45:00.000Z",
        "to": "2024-07-17T23:00:00.000Z",
        "measure": "SALES"
    }
]

Si no se especifica el parámetro demandTypeNames, la respuesta contendrá todas las medidas del producto en el rango de fechas indicado.

Preguntas frecuentes

¿Qué zona horaria se considera para la integración?

En la integración vía SFTP, la columna TIME considera la hora local, es decir, la zona horaria configurada en Orquest para el servicio. Por ejemplo, si la zona horaria de servicio es UTC+2, los datos incluidos para las 10:00 (1000 en formato HHmm) se insertarán a las 10:00 UTC+2.

En la integración vía API, sin embargo, las medidas se envían en UTC. En este sentido, es necesario considerar la zona horaria para la que se van a insertar los datos. Por ejemplo, si la zona horaria de servicio es UTC+2, los datos incluidos en la petición para las 08:00 UTC se insertarán a las 10:00 UTC+2.

Por tanto, para enviar las medidas del día 2024/07/18, habría que enviar los datos 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).

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

Este ejemplo representa las medidas de un día en UTC+2.

¿Es posible añadir vía API datos de medidas para una franja horaria concreta?

Tal y como se especifica en las operaciones detalladas anteriormente, en la integración por API, las peticiones deben contener los datos de días completos. Si solo se incluyen los datos de una franja del día, el resto de los valores para ese día integrados anteriormente desaparecerán del sistema.

¿Qué es más recomendable, SFTP o API?

Aunque la elección entre SFTP y API depende de las necesidades y preferencias del cliente, la integración vía API ofrece una ventaja significativa: proporciona un mayor feedback en la respuesta. En caso de error, la API devuelve información que ayuda a identificar qué ha sucedido con los datos enviados, permitiendo una resolución más rápida y precisa. La integración a través de SFTP no contiene un feedback directo, lo que puede hacer más difícil detectar y solucionar problemas con los datos transferidos.