Skip to content

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.

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: A dropdown list will be displayed containing the tenants to which the user has access. In this field, the user must select which of the available tenants they want to create the credential for. (The Tenant number to be used in the API will be included in parentheses).

Division: The Reporting APIs are multi-divisional, meaning you can have one or more divisions selected, where the information to be retrieved 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. These divisions will be loaded according to the tenant selected in the previous field.

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

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

Webhook: URL where Lynn notifies messages for clients. This parameter is used for messaging APIs; it does not apply to the Reporting API and should be left blank.

Internal Use: Functions for Lynn's own applications do not apply to the use of 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.

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 description de reportes disponibles

  • Show Dialogs:

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

    o Description: Table with available dialogs.

  • Menu Detail:

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

    o Description: Detail of selected menu options.

  • Show Error:

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

    o Description: Returns errors associated with an action.

  • Detail Performance:

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

    o Description: Returns information on service execution.

  • Productivity Detail:

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

    o Description: Audit information on actions applied to a tenant flow.

  • Survey result:

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

    o Description: Detail of survey results.

  • Current Interactions

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

    o Description: Kyubo indicators include typifications.

  • Mark-NAVIGATION_USER

    o ID: A45EC705-6A38-426A-8D1F-9CAE4D311497 o Description: Navigation mark indicator. o Example: 

        {
        "timestamp": "2024-01-25T19:49:04.70860cccc00Z",
        "session": "2f7bXXX-fff-4363-000-5d418XXXXXX",
        "division": "1",
        "channel_id": "26",
        "reportEnvironment": "testing",
        "intent": "ag_next_day",
        "markName": "END_SESSION",
        "markValue": " -> ag_next_day"
    }

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