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 CreateToken y el de Ejecución ExecuteReport.

Base Url / ly_endpoint:

Testing: https://premium-testing.lynn.cx
Production: https://premium-production.lynn.cx

API CreateToken

Para consumir cualquier endpoint de ejecución, es obligatorio obtener un Token Bearer previamente.

Especificación técnica de la API

`POST`	`{{ly_endpoint}}/api/LynnReporting/CreateToken`
Request (Body JSON)	`{ "accessToken": "{{ly_accessToken}}", "accessTokenSecret": "{{ly_accessSecret}}", "tenant": "{{ly_tenant}}" }`
Response	`{ "token": {{var_token}} }`

cURL

    curl --location '{{ly_endpoint}}/api/LynnReporting/CreateToken' \
    --header 'Content-Type: application/json' \
    --data '{
        "accessToken": "{{ly_accessToken}}",
        "accessTokenSecret": "{{ly_accessSecret}}",
        "tenant": "{{ly_tenant}}"
    }'

Parámetros de Ruta (Path Parameters)

Parámetro	Descripción
`ly_endpoint`	Url base, de acuerdo al ambiente: Production: premium-production.lynn.cx Testing: premium-testing.lynn.cx

Parámetros del Body (Request JSON)

Campo	Tipo	Requerido	Descripción
`ly_accessToken`	`string`	✅	Token de acceso utilizado para autenticar las solicitudes a la API. Este valor se obtiene desde la interfaz de Lynn. Ver Obtención de Credenciales de Acceso
`ly_accessSecret`	`string`	✅	Clave secreta asociada al token de acceso, usada en conjunto para la autenticación.Este valor se obtiene desde la interfaz de Lynn. Ver Obtención de Credenciales de Acceso
`ly_tenant`	`string`	✅	Identificador del tenant (cliente/organización) al que pertenece la solicitud.

API ExecuteReport

Una vez obtenido el token, se procede a ejecutar el reporte deseado.

POST {{ly_endpoint}}/api/LynnReporting/ExecuteReport/{{tenant}}/{{idReport}}

Request
(Body JSON)

{
    "startDate": "2023-03-01 00:00:00",
    "endDate": "2023-04-01 00:00:00",
    "size": 1000,
    "lastDocument": ""
}

Response

{
    "isValid": true,
    "errors": [...],
    "executionTime": 752.4835,
    "idReport": "b0a26dff-173f-4138-ab46-61273e52538a",
    "nameVisualization": "Show Dialogs",
    "totalDocument": 0,
    "pageCount": 0,
    "lastDocument": null,
    "requestCharge": 0,
    "result": [...]
}

Headers

Header	Valor	Requerido	Descripción
`Content-Type`	`application/json`	✅	Indica que el cuerpo de la solicitud está en formato JSON.
`Authorization`	`Bearer {{token}}`	✅	Token de autenticación obtenido previamente desde el endpoint `CreateToken`.

Parámetros de Ruta (Path Parameters)

Parámetro	Tipo	Requerido	Descripción
`ly_endpoint`	`string`	✅	Url base, de acuerdo al ambiente: Production: premium-production.lynn.cx Testing: premium-testing.lynn.cx
`tenant`	`string`	✅	Identificador del tenant (cliente/organización) que ejecuta el reporte.
`idReport`	`string`	✅	Identificador único del reporte a ejecutar.

Parámetros del Body (Request JSON)

Parámetro	Tipo	Requerido	Descripción
`startDate`	`string`	✅	Fecha y hora de inicio del rango a consultar, en formato `yyyy-MM-dd HH:mm:ss`.
`endDate`	`string`	✅	Fecha y hora de término del rango a consultar, en formato `yyyy-MM-dd HH:mm:ss`.
`size`	`integer`	✅	Cantidad máxima de registros a retornar en la consulta. Importante: Este parámetro tiene un tope de 10.000.
`lastDocument`	`string`	Opcional	Registro utilizado para paginar en caso de que sean muchos los registros a recuperar.

Campos del Response

Campo	Tipo	Descripción
`isValid`	`boolean`	Indica si la ejecución del reporte fue exitosa.
`errors`	`array`	Arreglo con los errores ocurridos durante la ejecución, si existen.
`executionTime`	`number`	Tiempo que tomó ejecutar el reporte, en milisegundos.
`idReport`	`string`	Identificador único del reporte ejecutado.
`nameVisualization`	`string`	Nombre de la visualización asociada al reporte.
`totalDocument`	`integer`	Cantidad total de documentos/registros retornados en la consulta.
`pageCount`	`integer`	Cantidad de querys adicionales que se debe ejecutar para obtener el total de registro.
`lastDocument`	`string`	Identificador (codificado) del último documento retornado, usado para paginar consultas siguientes.
`requestCharge`	`number`	Costo de la consulta en unidades de solicitud (request units).
`result`	`array`	Arreglo con los datos/resultados del reporte.

Paginación

Si el reporte supera el size configurado, el parámetro pageCount en la respuesta será mayor a 0.

Cómo paginar:

Repite la consulta original.
Mantén los filtros iniciales (startDate, endDate, size).
Incluye el parámetro lastDocument obtenido en la respuesta anterior.
Actualiza el valor de lastDocument en cada ciclo de consulta hasta que pageCount sea 0.

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 (porque pageCount es iguala a 2) 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

Nombre	ID	Descripción
Show Dialogs	`B0A26DFF-173F-4138-AB46-61273E52538A`	Tabla con los diálogos disponibles. IMPORTANTE: Esta API quedará obsoleta. Por favor, contacte con el equipo de soporte para gestionar la migración a la versión actual.
Menu Detail	`542B8262-14EB-4FEF-9873-93EC8B439FB7`	Detalle de las opciones seleccionada de los menús. IMPORTANTE: Esta API sigue funcionando, se recomienda hacer el cambio a una nueva api DIALOGS.
Show Error	`192D8D34-2BE0-477D-94EE-C5B3198B15D5`	Devuelve los errores asociados a una acción. IMPORTANTE: Este reporte ha quedará obsoleto y se eliminará definitivamente el 30 de septiembre de 2026. No existe ningún reemplazo disponible para esta API.
Detail Performance	`CB7D310E-BF08-46ED-A5E9-24C744344018`	Devuelve información de la ejecución de los servicios. IMPORTANTE: Esta API ha quedado obsoleta. Por favor, contacte con el equipo de soporte para gestionar la migración a la versión actual.
Productivity Detail	`34175227-42BE-4A59-8B95-6F2EE6C14849`	Información de auditoría sobre las acciones aplicadas a un flujo del tenant.
Current Interactions	`615DAD60-6EA5-4E19-AC37-5253170B86C0`	Indicadores de Kyubo incluye tipificaciones. IMPORTANTE: Este reporte ha quedado obsoleto y se eliminará definitivamente el 30 de septiembre de 2026. No existe ningún reemplazo disponible para esta API.
Mark-NAVIGATION_USER	`A45EC705-6A38-426A-8D1F-9CAE4D311497`	Indicador de las marcas de navegación. IMPORTANTE: Este reporte ha quedado obsoleto y se eliminará definitivamente el 30 de septiembre de 2026.
Survey Result v2	`468F3FC2-4406-4FD8-BD09-2788FC10A218`	Detalle del resultado de la encuesta V2 que incluye campos Custom.
Get Campaign Results	`9FE42F19-0B8A-43A6-8BB0-604947E85160`	Obtener datos resultantes de la campaña solicitada. En referencia al estado del registro de campaña la API actualmente devuelve solo el último estado del registro.
Get Campaign Results v2 (Para Outbound V2)	`64A004A6-FF90-4908-AB2D-F8103ECA0CEC`	Obtener datos resultantes de la campaña solicitada. En referencia al estado del registro de campaña la API actualmente devuelve solo el último estado del registro.

API ExecuteReport (Nuevos reportes)

Hay un grupo de nuevos reportes asociados a las visualizaciones de la aplicación Lynn Reporting

POST {{ly_endpoint}}/api/LynnReporting/ExecuteReport/{{tenant}}/{{idReport}}

Request
(Body JSON)

{
    "startDate": "2023-03-01 00:00:00",
    "endDate": "2023-04-01 00:00:00".
    "lastDocument": ""
}

Response

{
    "isValid": true,
    "executionTime": 742.7789,
    "idReport": "XXXXXXXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "nameVisualization": "Nombre de la Visualización",
    "totalDocument": 30,
    "pageCount": 0,
    "lastDocument": null,
    "requestCharge": 255.72000000000003,
    "result": [...],
    "errors": [...]
}

Headers

Header	Valor	Requerido	Descripción
`Content-Type`	`application/json`	✅	Indica que el cuerpo de la solicitud está en formato JSON.
`Authorization`	`Bearer {{token}}`	✅	Token de autenticación obtenido previamente desde el endpoint `CreateToken`.

Parámetros de Ruta (Path Parameters)

Parámetro	Tipo	Requerido	Descripción
`ly_endpoint`	Url base, de acuerdo al ambiente: Production: premium-production.lynn.cx Testing: premium-testing.lynn.cx
`tenant`	`string`	✅	Identificador del tenant (cliente/organización) que ejecuta el reporte.
`idReport`	`string`	✅	Identificador único del reporte a ejecutar.

Parámetros del Body (Request JSON)

Parámetro	Tipo	Requerido	Descripción
`startDate`	`string`	✅	Fecha y hora de inicio del rango a consultar, en formato `yyyy-MM-dd HH:mm:ss`.
`endDate`	`string`	✅	Fecha y hora de término del rango a consultar, en formato `yyyy-MM-dd HH:mm:ss`.
`lastDocument`	`string`	Opcional	Registro utilizado para paginar en caso de que sean muchos los registros a recuperar. Se envía vacío (`""`) en la primera consulta.

Campos del Response

Campo	Tipo	Descripción
`isValid`	`boolean`	Indica si la ejecución del reporte fue exitosa.
`executionTime`	`number`	Tiempo que tomó ejecutar el reporte, en milisegundos.
`idReport`	`string`	Identificador único del reporte ejecutado.
`nameVisualization`	`string`	Nombre de la visualización asociada al reporte.
`totalDocument`	`integer`	Cantidad total de documentos/registros retornados en la consulta.
`pageCount`	`integer`	Cantidad de querys adicionales que se debe ejecutar para obtener el total de registro.
`lastDocument`	`string`	Identificador (codificado) del último documento retornado, usado para paginar consultas siguientes. Es `null` cuando no hay más páginas.
`requestCharge`	`number`	Costo de la consulta en unidades de solicitud (request units).
`result`	`array`	Arreglo con los datos/resultados del reporte.
`errors`	`array`	Arreglo con los errores ocurridos durante la ejecución, si existen.

ID y descripción de nuevos reportes

Reportes	ID	Descripción
OUTBOUND GET CAMPAIGN RESULT	`60D12322-2D25-40DE-BFD4-D4DAE7241C43`	Historial detallado y ciclo de vida de los registros de campañas (v1), con visibilidad completa de cada estado de envío y recepción
OUTBOUND CALLS	`EB9B0714-1BC3-460A-8CA1-E2EB55109C30`	Registro detallado de llamadas de salida.
AGENTS STATUS	`94607720-c91c-4dfe-a39f-fdd069cfe585`	Monitoreo del estado en tiempo real y acumulado de los agentes, permitiendo medir tiempos de sesión, disponibilidad (ready59435EB3-3E0F-4005-8BB5-48432DA6364D/not ready) y productividad.
INBOUND CALLS INTERACTIONS	`DB3215A0-1919-4E47-B09A-390E4A2FFE9A`	Análisis integral de las llamadas entrantes, detallando tiempos de espera, duración de la interacción, tasa de abandono y experiencia del cliente.
ACTIVITY TENANT	`34175227-42BE-4A59-8B95-6F2EE6C14849`	Reporte ejecutivo sobre el consumo y uso de la plataforma, detallando el volumen de ejecuciones de informes dentro del tenant para control administrativo.
AUDIO CONNECTOR TRARFFING V2	`68800B36-2D8A-4CB8-BBBD-1DA78A2AA934`	Auditoría y control del tráfico de audio en tiempo real, monitoreando la calidad de la conexión, latencias y consumo de recursos del conector de voz.
SESSIONS	`59435EB3-3E0F-4005-8BB5-48432DA6364D`	Esta API entrega el detalle de todas las sesiones registradas en la plataforma: canal, tiempos, duración e identificación del contacto.
DIALOGS	`9306395D-F645-4597-9563-78DF67836192`	Esta API entrega el detalle de los diálogos registrados en las conversaciones de la plataforma: emisor del mensaje, intención detectada, canal utilizado y metadatos técnicos asociados.
NAVEGATION MARK	`144C6E55-B5FE-4A68-A4A3-1F78B205BAFD`	Indicador de marca de navegación

Paginación

Si el reporte supera el tamaño de página configurado internamente, el parámetro pageCount en la respuesta será mayor a 0.

Cómo paginar:

Repite la consulta original.
Mantén los filtros iniciales (startDate, endDate).
Incluye el parámetro lastDocument obtenido en la respuesta anterior.
Actualiza el valor de lastDocument en cada ciclo de consulta hasta que pageCount sea 0.

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 1 vez más (porque pageCount es igual a 1) para obtener el total. La forma de ejecución se muestra en la siguiente imagen:

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

Limitaciones declaradas

Esta sección describe las cuotas de consumo, límites por producto y códigos de error asociados al uso de la API.

Cuotas de consumo (rate limit por key)

Método	Límite
`/CreateToken`	3 llamadas cada 60 segundos
Todos los demás métodos	1 llamada cada 4 segundos

Cuotas por producto

Existen 2 tipos de producto, cada uno con un límite de período, cantidad de llamadas y ancho de banda disponible:

Producto	Activación	Período	Calls	Bandwidth
Básico	Automática, al consumir la API	43.200 s (12 horas)	10.000	102.400 KB (100 MB)
Premium	Manual, solicitando el `Ocp-Apim-Subscription-Key` a un partner Lynn o asesor comercial	43.200 s (12 horas)	20.000	997.200 KB (997,2 MB)

Activar el producto Premium

Para ejecutar un reporte con el producto Premium, agrega el header Ocp-Apim-Subscription-Key con el valor entregado por tu partner o asesor comercial:

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 HTTP	Descripción
`429`	Rate limit excedido. Reintentar en `T` segundos.
`403`	Cuota de bandwidth agotada. Se renueva en `T`.

Table of Contents

API Reportería

API CreateToken

Especificación técnica de la API

cURL

Parámetros de Ruta (Path Parameters)

Parámetros del Body (Request JSON)

API ExecuteReport

Headers

Parámetros de Ruta (Path Parameters)

Parámetros del Body (Request JSON)

Campos del Response

Paginación

ID y descripción de reportes disponibles

API ExecuteReport (Nuevos reportes)

Headers

Parámetros de Ruta (Path Parameters)

Parámetros del Body (Request JSON)

Campos del Response

ID y descripción de nuevos reportes

Paginación

Limitaciones declaradas

Cuotas de consumo (rate limit por key)

Cuotas por producto

Activar el producto Premium

Descripción de errores