Reporting API

The Reporting API consists of 2 methods: authentication and execution.

CreateToken API

The authentication API is used to obtain a mandatory bearer token for consuming the execution API.

• 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>>
  }
  

The credentials used in the JSON body are obtained from the Lynn interface according to the environment, by an administrator user for the tenant.

Best Practice 👨‍🏫: It is recommended to create a unique credential for each client application that will consume the APIs. This allows deactivating a credential without affecting other applications.

To add a new credential, click on the Create icon (+) located in the upper right corner.

This will open the following form:

Name: Enter a descriptive name that identifies the application consuming the API.

Tenant: If the user manages multiple tenants, select the tenant in which you want to create the credential (Tenant number to be used in the API is indicated in parentheses).

Division: The Reporting API supports multiple divisions, which means you can have one or more divisions selected. The retrieved information is filtered based on this configuration. It is mandatory to have at least one division selected; otherwise, when using the token, the API will return an error.

Token: Auto-generated (Value to be used in the API).

Token Secret: Auto-generated (Value to be used in the API).

Webhook: URL where Lynn sends notifications for client messages. This parameter is used for messaging APIs and does not apply to the Reporting API; leave it empty.

Internal Use: Functions for Lynn's own applications. Not applicable for using the APIs.

Api EXECUTEREPORT

The following API is used to execute a report. The URL includes the tenant we are working with and the GUID that identifies the report to be consumed.

• 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
  }
  

Where in the Header (Authorization), specifically {{token}} is replaced by the response obtained in CreateToken, and the body is a Json in which:

• startDate: Mandatory, it is the start date of the Filter, format "yyyy-MM-dd hh:mm:ss"

• endDate: Mandatory, it is the end date of the Filter, format "yyyy-MM-dd hh:mm:ss"

• size: (Mandatory) integer indicating the maximum volume of records to retrieve, with a limit of 10000.

Example of API execution:

In the response, we obtain a JSON with the following values:

• isValid: A boolean indicating whether the report was executed successfully.

• executionTime: The time taken to perform the query.

• idReporting: The report ID used in the URL.

• NameVisualization: The name of the report.

• pageCount: The number of additional queries that need to be executed to retrieve the total number of records.

• result: A JSON array containing the report results. It is in the form of , where each key represents a column, and each JSON object represents a record.

• errors: Displays errors if any exist.

• lastDocument: The record used for pagination in case there are many records to retrieve.

Pagination

When a report retrieves a large number of records that exceeds the value configured in the size parameter of the request, pagination is necessary to retrieve the total number of records.

We identify the need for pagination when the pageCount parameter in the response is greater than zero (0). This number indicates the number of additional queries that need to be repeated from the original query to retrieve the remaining information. In this case, the original query should be repeated while maintaining the filters (startDate, endDate, size), and the lastDocument parameter obtained from the response should be incorporated. This last parameter should be replaced with the retrieved value in each cycle.

In the example API Execution Example, the result of the first execution is processed, and then the search is repeated 2 more times to obtain the total. The execution process is shown in the following image:

Note that the lastDocument value changes, so in the next query, the new value should be updated and the query should be repeated.

ID y descripción de reportes disponibles

• Show Dialogs:

  o ID: B0A26DFF-173F-4138-AB46-61273E52538A.

  o descripción: Tabla con los diálogos disponibles.

• Menu Detail:

  o ID: 542B8262-14EB-4FEF-9873-93EC8B439FB7.

  o descripción: detalle de las opciones seleccionada de los menús.

• Show Error:

  o ID: 192D8D34-2BE0-477D-94EE-C5B3198B15D5.

  o descripción: Devuelve los errores asociados a una acción.

• Detail Performance:

  o ID: CB7D310E-BF08-46ED-A5E9-24C744344018.

  o descripción: devuelve información de la ejecución de los servicios.

• Productivity Detail:

  o ID: 34175227-42BE-4A59-8B95-6F2EE6C14849.

  o descripción: Información de auditoría sobre las acciones aplicadas a un flujo del tenant.

• Survey result:

  o ID: 9C294B80-CCFF-44F7-B9D4-5909058D2513.

  o descripción: Detalle del resultado de la encuesta.

• Current Interactions

  o ID: 615DAD60-6EA5-4E19-AC37-5253170B86C0.

  o descripción: Indicadores de Kyubo incluye tipificaciones.

Declared Limitations

Consumption Quotas

rate-limit-by-key

Method '/CreateToken': Corresponds to 3 API calls every 60 seconds. All other methods are limited to 1 API call every 4 seconds.

Quotas per Product

Basic Product: Activated by default when consuming the API. Allows:

• Periodo: 43.200 seconds (12 hours)
• Calls: 10.000
• Bandwidth: 102.400 kilobytes (100 megabytes)

Premium Product: Requires requesting it through partner Lynn or a sales advisor, who will provide a valid Ocp-Apim-Subscription-Key. Allows:

• Periodo: 43.200 seconds (12 hours).
• Calls: 20.000
• Bandwidth: 997.200 kilobytes (997.2 megabytes)

To execute a report with the Premium product, it is necessary to activate the Ocp-Apim-Subscription-Key parameter in the headers, as shown below:

To check the available quota amount, you can use the following POST request: {{BaseUrl}}/api/LynnReporting/CreateToken?info.

Error code	Description
429	rate limit is Exceeded. Try again in T seconds
403	Out of bandwidth quota. Quota will be replenished in T