API Reportería

A continuación detallaremos el consumo de esta API de reportería que permite poder realizar extracción de data. Está compuesta de 2 métodos, el de autenticación y el de Ejecución.

Api CREATETOKEN

La api de autenticación se utiliza para obtener un Token bearer que es de uso obligatorio para consumir la API de ejecución.

• Method: POST
• EndpointTesting: https://premium-testing.lynn.cx/api/LynnReporting/CreateToken
• EndpointProduction: https://premium-production.lynn.cx/api/LynnReporting/CreateToken

  Headers:
      Content-Type: application/json
  Body:
  {
      "accessToken": <<(string)Token>>,
      "accessTokenSecret": <<(string)Secret>>,
      "tenant": <<(int)Tenant>>
  }
  

En donde las credenciales usadas en el Json del Body se obtienen desde la interfaz de Lynn según el ambiente, por un usuario con perfil administrador para Tenant

Buena Práctica 👨‍🏫: se recomienda crear una credencial única para cada aplicación cliente que va consumir las API, esto permitirá dar de baja a una credencial sin afectar a otras aplicaciones.

Para agregar una nueva credencial hacemos click en el icono de Crear (+), ubicado en la esquina superior derecha

el cual abrirá el siguiente formulario:

Nombre: Se debe colocar un nombre descriptivo que identifique la aplicación que consume la API.

Tenant: si el usuario administra múltiples tenant debe seleccionar en cuál de los tenant disponible quiere crear la credencial (Entre Paréntesis el número del Tenant a usar en la API).

Division: Las api de Reportería son mult-division, es decir puedes tener una o más divisiones seleccionadas, en la cual la información a recuperar son filtradas en base a esta configuración, es obligatorio tener al menos una división seleccionada en caso contrario al utilizar el token la API va devolver un error.

Token: Autogenerado (Valor a utilizar en la API).

Token Secreto: Autogenerado (Valor a utilizar en la API).

Webhook: Url en la cual Lynn notifica los mensajes para los clientes, este parámetro se usa para las API de mensajería, en la Api de reportería no aplica se deja vacío.

Uso Interno: funciones de aplicaciones propias de Lynn no aplica para el uso de las API.

Api EXECUTEREPORT

La siguiente API se utiliza para ejecutar un reporte, en la URL se incluye el tenant que estamos trabajando y el la GUID que identifica el reporte a consumir

• Method: POST
• EndpointTesting: https://premium-testing.lynn.cx/api/LynnReporting/ExecuteReport/{{tenant}}/{{idReport}}
• EndpointProduction: https://premium-production.lynn.cx/api/LynnReporting/ExecuteReport/{{tenant}}/{{idReport}}

  Headers:
  Content-Type: application/json
  Authorization: Bearer {{token}}
  
  Body:
  {
      "startDate": "2023-03-01 00:00:00",
      "endDate": "2023-04-01 00:00:00",
      "size": 1000
  }
  

En donde en el Header (Athorization), específicamente {{token}} es reemplazado por la respuesta obtenida en el CreateToken, y el body es un Json en la cual:

• startDate: Obligatorio, es la fecha de origen del Filtro, formato “yyyy-MM-dd hh:mm:ss”

• endDate: Obligatorio, es la fecha de fin del Filtro, formato “yyyy-MM-dd hh:mm:ss”

• size: (Obligatorio) entero que indica el volumen máximo de registro a recuperar teniendo como tope 10000

Ejemplo de ejecución de la API

En la cual en el response obtenemos un JSON con los siguientes Valores.

• isValid: Booleano que indica que si se ejecutó correctamente el reporte.

• executionTime: tiempo que tarda en hacer la query.

• idReporting: idReporte utilizado en la URL.

• NameVisualization: Nombre del Reporte.

• pageCount: cantidad de Querys adicionales que se debe ejecutar para obtener el total de registro.

• result: es un arreglo JSON con el resultado del reporte, es del tipo , en donde cada key representa una columna, y cada objeto json reprenta un registro.

• errors: se muestra errores en caso de que existan.

• lastDocument: registro utilizado para paginar en caso de que sean muchos los registros a recuperar.

Paginación

Cuando un reporte recupera una cantidad muy grande de registros que supera la cantidad configurada en el parámetro size del request, es necesario aplicar paginación para recuperar el total de registro.

Identificamos que necesitamos paginar cuando en el response el parámetro pageCount es mayor a cero (0), este número indica la cantidad de querys adicionales a la original se debe repetir para recuperar el resto de la información en este caso se debe repetir la query original manteniendo los filtros (startDate, endDate, size) y adicional se incorpora el parámetro lastDocument obtenido en el response, y este último debe ser reemplazado con el recuperado en cada ciclo.

En el ejemplo Ejemplo de ejecución de la API, se procesa el resultado de la primera ejecución y luego se repite la búsqueda 2 veces más para obtener el total y la forma de ejecución se muestra en la siguiente imagen

Observar que lastDocument cambia, por ende en la siguiente query se debe actualizar en nuevo valor y repetir query.

ID y descripción de reportes disponibles

• Show Dialogs:

  • ID: B0A26DFF-173F-4138-AB46-61273E52538A.
  • descripción: Tabla con los diálogos disponibles.

• Menu Detail:

  • ID: 542B8262-14EB-4FEF-9873-93EC8B439FB7.
  • descripción: detalle de las opciones seleccionada de los menús.

• Show Error:

  • ID: 192D8D34-2BE0-477D-94EE-C5B3198B15D5.
  • descripción: Devuelve los errores asociados a una acción.

• Detail Performance:

  • ID: CB7D310E-BF08-46ED-A5E9-24C744344018.
  • descripción: devuelve información de la ejecución de los servicios.

• Productivity Detail:

  • ID: 34175227-42BE-4A59-8B95-6F2EE6C14849.
  • descripción: Información de auditoría sobre las acciones aplicadas a un flujo del tenant.

• Survey result:

  • ID: 9C294B80-CCFF-44F7-B9D4-5909058D2513.
  • descripción: Detalle del resultado de la encuesta.

• Current Interactions

  • ID: 615DAD60-6EA5-4E19-AC37-5253170B86C0.
  • descripción: Indicadores de Kyubo incluye tipificaciones.

Limitaciones declaradas

Cuotas de consumo

rate-limit-by-key

• Método '/CreateToken': Corresponde a 3 llamadas a la API cada 60 segundos.
• Todos los otros métodos están limitados a 1 llamada a la API cada 4 segundos.

Cuotas por producto

Existen 2 tipos de producto:

Producto Básico: se activa por defecto al consumir la API. Permite:

• Periodo: 43.200 segundos (12 horas)
• Calls: 10.000
• Bandwidth: 102.400 kilobytes (100 megabytes)

Producto Premium: es necesario solicitarlo a través de partner Lynn o asesor comercial quien sumistrará el Ocp-Apim-Subscription-Key válido. Permite:

• Periodo: 43.200 segundos (12 horas)
• Calls: 20.000
• Bandwidth: 997.200 kilobytes (997.2 megabytes )

Para ejecutar un reporte con el producto Premium es necesario activar en los headers el parámetro Ocp-Apim-Subscription-Key, tal y como se muestra a continuación:

Para validar la cantidad de cuota que hay disponibles se puede utilizar en el POST: {{BaseUrl}}/api/LynnReporting/CreateToken?info

Descripción de errores

Código del error	Descripción
429	rate limit is Exceeded. Try again in T seconds
403	Out of bandwidth quota. Quota will be replenished in T