Uso de la API Audit

Descripción de los endpoints de la API Audit disponibles para los clientes

Written By Matias Carcamo

Last updated 6 months ago

La API Audit le permite obtener datos respecto a sus flujos en dVirtualUser para ser consumidos por aplicaciones de terceros

URL Base: https://app.dvirtualuser.com/audit

Autenticación & Autorización

La API requiere el uso de un Token con acceso a los datos históricos de monitoreo sintético para poder ejecutar las consultas correspondientes. Para generar uno debe:

Ingresar a la sección API Tokens desde el menú que se despliega al seleccionar su nombre de usuario y, una vez allí, seleccionar el botón Crear Token
En el diálogo que se abre, especifique Nombre del token, Expiración y marque la casilla del permiso report_api para permitir la consulta de datos históricos. Luego, seleccione Crear
Se almacenará el API Token y podrá copiar su valor directamente con el botón en la columna Token

Luego, todas sus peticiones HTTP deben tener la siguiente cabecera:

Key	Value
`Authorization`	API_TOKEN
`Content-Type`	`application/json`

Endpoints

Datos de un flujo

Para obtener el ID de un flujo, diríjase a la sección Flujos en el portal web y verifique los detalles del flujo de su interés. Podrá copiar el ID desde la URL resultante:

GET /audit/getDataOfFlow

Obtiene datos históricos de un flujo en particular dado un periodo de tiempo.

Request body

Ejemplo mínimo:

{
  "id": "27256943",
  "start": 1761252816000,
  "end": 1761339216000
}

Los parámetros de la petición se detallan a continuación:

Propiedad	Tipo	Descripción
id	Primitive (Integer)	Identificador del flujo que se desea consultar sus datos
start	Primitive (Long)	Fecha de inicio del periodo a consultar en formato timestamp (milisegundos)
end	Primitive (Long)	Fecha de término del periodo a consultar en formato timestamp (milisegundos)

Parámetros opcionales:

Propiedad	Tipo	Descripción
addScreenshots	Primitive (Boolean)	Indica si se entregan URLs con screenshots de los pasos con errores. Default: `true`
addHistory	Primitive (Boolean)	Indica si se entrega información del historial de errores. Default: `true`
addUptime	Primitive (Boolean)	Indica si se entrega información relacionada a uptime. Default: `true`
addTrend	Primitive (Boolean)	Indica si se entrega información de tendencia (tiempos de respuesta). Default: `true`
addUserExperience	Primitive (Boolean)	Indica si se entrega información de experiencia de usuario. Default: `true`
timezone	Primitive (String)	Zona horaria en la que se entregarán los timestamps que correspondan. Default: `“UTC”`

Response

dVirtualuser retornará un respuesta con la siguiente estructura JSON por defecto:

{
  "timezone": "Chile/Continental",
  "isProcessing": false,
  "processingMessage": "OK",
  "queryToken": "1767620926806_RAND:458.99506886446653",
  "queryTime": 1767620926806,
  "apiMessage": "OK",
  "id": 627344,
  "start": 1761252816000,
  "end": 1761339216000,
  "addScreenshots": true,
  "addUserExperience": true,
  "addHistory": true,
  "addUptime": true,
  "addTrend": true,
  "trendUnitNames": "responseTime",
  "generalMetrics": {
    "simulationData": [
      {
        "stepName": "01 - Nuevo paso",
        "result": "OK",
        "simulations": 287
      }
    ]
  },
  "userExperience": {
    "apiMessage": "OK",
    "apdexData": [
      {
        "id": 3151069,
        "robotId": 627344,
        "date": "2025-10-24T14:50:29.919-03:00",
        "step": "01 - Nuevo paso",
        "ok": 0,
        "warning": 269,
        "critical": 17,
        "unknown": 0
      },
      {
        "id": 3151070,
        "robotId": 627344,
        "date": "2025-10-24T14:50:29.919-03:00",
        "step": "_total",
        "ok": 0,
        "warning": 269,
        "critical": 17,
        "unknown": 0
      }
    ]
  },
  "history": {
    "apiMessage": "OK",
    "errors": [],
    "customErrors": [
      {
        "id": 6736,
        "keyId": 2499330,
        "key": "responseTime:01 - Nuevo paso",
        "start": "2025-10-24T14:45:13.805-03:00",
        "description": "Valor actual: 52.74 (s). Umbral 30.0 (s) superado.",
        "status": "WARNING",
        "stepId": 1155818,
        "end": "2025-10-24T15:26:01.195-03:00",
        "consecutiveFlows": 8,
        "robotId": 627344,
        "robotDescription": "",
        "robotName": "robot_37",
        "server": "DPA Test",
        "stepName": "01 - Nuevo paso",
        "code": 200,
        "stepScreenshot": "group_37--robot_37--01_-_Nuevo_paso",
        "groupName": "group_37",
        "groupDescription": "01 - test",
        "tags": null,
        "screenshotBase64": null
      },
      ...
    ]
  },
  "uptime": {
    "apiMessage": "OK",
    "uptimeData": [
      {
        "robotUptimeFactor": 1.0,
        "groupUptimeFactor": 0.5,
        "id": 89424,
        "robotId": 627344,
        "start": "2025-10-23T17:53:36-03:00",
        "end": "2025-10-24T10:14:10.03-03:00",
        "status": "UP",
        "message": "OK",
        "isFalsePositive": false
      },
      ...
    ]
  },
  "trend": {
    "apiMessage": "OK",
    "trendData": [
      {
        "date": "2025-10-23T14:57:00-03:00",
        "robotId": 627344,
        "stepName": "01 - Nuevo paso",
        "robotName": "robot_37",
        "server": null,
        "description": "01 - test",
        "unitName": "responseTime",
        "unitValue": 53589.0
      },
      ...
    ]
  },
  "paramsAsString": "[ id = 627344, start = 1761252816000, end = 1761339216000 ]"
}

Las propiedades se detallan a continuación:

Main (Object):

Propiedad	Tipo	Detalle
isProcessing	Primitive (Boolean)	Indica si la consulta sigue procesándose o no
processingMessage	Primitive (String)	Detalle del procesamiento de la consulta. OK si está lista
queryToken	Primitive (String)	Identificador de la consulta. Útil para consultar los resultados posteriormente si `“isProcessing”: true`
queryTime	Primitive (Long)	Timestamp de creación de la consulta
apiMessage	Primitive (String)	Resultado de la consulta. OK si es exitosa.
id	Primitive (Long)	Identificador del flujo en el sistema
start	Primitive (Long)	Fecha de inicio (timestamp)
end	Primitive (Long)	Fecha de termino (timestamp)
trendUnitNames	Primitive (String)	Unidad de medida de las series en trend
generalMetrics	Object	Métricas agregadas de los pasos del flujo
userExperience	Object	Información relacionada a Experiencia de Usuario
history	Object	Información relacionada a Historial de errores
uptime	Object	Información relacionada a Uptime
trend	Object	Información relacionada a Tendencia (tiempos de respuesta)
paramsAsString	Primitive (String)	Representación como string de los parámetros `id`, `start` y `end` de la consulta

timezone, id, start, end, addScreenshots, addUserExperience, addHistory, addUptime y addTrend retornan sus valores por defecto o aquellos establecidos en el cuerpo de la petición HTTP, según corresponda.

generalMetrics (Object):

Propiedad	Tipo	Detalle
simulationData	Array (Object)	Lista con las métricas agregadas de cada paso del flujo

simulationData [Objects in Array]:

Propiedad	Tipo	Detalle
stepName	Primitive (String)	Nombre del paso
result	Primitive (String)	Resultado general de la ejecución del paso
simulations	Primitive (Integer)	Número de simulaciones/ejecuciones

userExperience (Object):

Propiedad	Tipo	Detalle
apiMessage	Primitive (String)	Resultado de la consulta. OK si es exitosa.
apdexData	Array (Object)	Lista con información de apdex por paso. El último objeto agrega la información de todos los pasos y tiene el identificador `“step": "_total"`.

apdexData [Objects in Array]:

Propiedad	Tipo	Detalle
id	Primitive (Long)	Identificador del dato de apdex
robotId	Primitive (Long)	Identificador del flujo
date	Primitive (String)	Fecha de la muestra (fecha de termino de la consulta)
step	Primitive (String)	Nombre del paso
ok	Primitive (Integer)	Cantidad de veces que este paso fue OK
warning	Primitive (Integer)	Cantidad de veces que este paso fue WARNING
critical	Primitive (Integer)	Cantidad de veces que este paso fue CRITICAL
unknown	Primitive (Integer)	Cantidad de veces que este paso fue UNKNOWN

history (Object):

Propiedad	Tipo	Detalle
apiMessage	Primitive (String)	Resultado de la consulta. OK si es exitosa.
errors	Array (Object)	Listado con los errores de tipo interrupción
customErrors	Array (Object)	Listado con los errores por otros criterios

errors [Objects in Array]:

Propiedad	Tipo	Detalle
id	Primitive (Long)	Identificador del error
robotId	Primitive (Integer)	Identificador del flujo consultado
stepName	Primitive (String)	Nombre del paso con el error
robotName	Primitive (String)	Identificador del flujo con el error
server	Primitive (String)	Sonda de la que proviene el flujo
stepMessage	Primitive (String)	Descripción del error
stepScreenshot	Primitive (String)	Nombre de la captura de pantalla al momento del error
stepCode	Primitive (Integer)	Código de respuesta del sitio al momento del error
stepId	Primitive (Long)	Identificador del paso con error
start	Primitive (String)	Inicio del error
end	Primitive (String)	Termino del error
consecutiveFlows	Primitive (Integer)	Veces que el flujo se ejecuto consecutivamente con el error
tags	Primitive (String)	Etiquetas del error
isFalsePositive	Primitive (Boolean)	Indica si es un falso positivo o no
screenshotBase64	Primitive (String)	Screenshot codificado en bytes si `addScreenshots: true` y si está disponible

customErrors [Objects in Array]:

Propiedad	Tipo	Detalle
id	Primitive (Long)	Identificador del error
keyId	Primitive (Long)	Identificador de la key del error
key	Primitive (String)	Identifica el tipo de error y el paso en el que ocurre
description	Primitive (String)	Descripción del error
status	Primitive (String)	Estado del error
stepId	Primitive (Long)	Identificador del paso
start	Primitive (String)	Inicio del error
end	Primitive (String)	Termino del error
consecutiveFlows	Primitive (Integer)	Veces que el flujo se ejecutó consecutivamente con el error
robotId	Primitive (Integer)	Identificador del flujo consultado
robotDescription	Primitive (String)	Descripción del flujo
robotName	Primitive (String)	Nombre del flujo en el sistema
server	Primitive (String)	Sonda de la que proviene el flujo
stepName	Primitive (String)	Nombre del paso con error
code	Primitive (Integer)	Código asociado al error
stepScreenshot	Primitive (String)	Ruta o referencia a screenshot del paso
groupName	Primitive (String)	Nombre del grupo del flujo en el sistema
groupDescription	Primitive (String)	Descripción del grupo al que pertenece el flujo
tags	Primitive (String)	Etiquetas del error
screenshotBase64	Primitive (String)	Screenshot codificado en bytes si `addScreenshots: true` y si está disponible

uptime (Object):

Propiedad	Tipo	Detalle
apiMessage	Primitive (String)	Resultado de la consulta. OK si es exitosa.
uptimeData	Array (Object)	Listado con los cambios de estado (UP o DOWN) del flujo

uptimeData [Objects in Array]:

Propiedad	Tipo	Detalle
robotUptimeFactor	Primitive (Double)	Factor de uptime del flujo
groupUptimeFactor	Primitive (Double)	Factor de uptime del grupo (para grupos con más de 1 flujo)
id	Primitive (Long)	Identificador de la ventana de tiempo
robotId	Primitive (Long)	Identificador del flujo
start	Primitive (String)	Fecha de inicio
end	Primitive (String)	Fecha de termino
status	Primitive (String)	Estado (UP o DOWN)
message	Primitive (String)	Descripción de porque está DOWN, de estarlo
isFalsePositive	Primitive (Boolean)	Indica si es falso positivo o no

trend (Object):

Propiedad	Tipo	Detalle
apiMessage	Primitive (String)	Resultado de la consulta. OK si es exitosa.
trendData	Array (Object)	Listado con tiempos de respuesta del flujo

trendData [Objects in Array]:

Propiedad	Tipo	Detalle
date	Primitive (String)	Fecha en que se capturó el evento
robotId	Primitive (Long)	Identificador del flujo
stepName	Primitive (String)	Nombre del paso
robotName	Primitive (String)	Identificador del flujo
server	Primitive (String)	Sonda de la que proviene el flujo
description	Primitive (String)	Descripción del flujo
unitName	Primitive (String)	Unidad de medida (responseTime, htmlTime, cssTime,...)
unitValue	Primitive (Double)	Tiempo, en milisegundos

Datos de cliente

GET /audit/getClient

Obtiene un arreglo que contiene información de todos los robots/flujos asociados al cliente con el API Token entregado. No necesita un request body.

Response

dVirtualUser retornará una respuesta con una estructura JSON como la siguiente:

{
  "flows": [
    {
      "id": 2609,
      "client": 1018,
      "groupId": 2609,
      "userExpData": "",
      "key": "test_gpu:test_gpu",
      "groupDescription": "",
      "isSmart": false,
      "iaEnabled": false,
      "videoRecording": false,
      "tags": [],
      "location": "",
      "maintenance": 0,
      "autoMaintenance": 0,
      "flowCreatedAt": "2025-12-31T14:20:18.820+00:00",
      "environment": "production",
      "integrations": []
    },
    {
      "id": 72478,
      "client": 1018,
      "groupId": 72478,
      "userExpData": "",
      "key": "listener_1234:listener_1234",
      "groupDescription": "",
      "isSmart": false,
      "iaEnabled": false,
      "videoRecording": false,
      "tags": [],
      "location": "",
      "maintenance": 0,
      "autoMaintenance": 0,
      "flowCreatedAt": "2025-12-31T14:06:16.576+00:00",
      "environment": "production",
      "integrations": []
    },
    ...
  ]
}

El objeto respuesta puede incluir otros campos como client, clientName, robotStats, probeServers y users, pero aparecerán con valor null.

Las propiedades se detallan a continuación:

Main (Object):

Propiedad	Tipo	Detalle
flows	Array (Object)	Lista con datos de todos los flujos asociados al cliente

flows [Objects in Array]:

Propiedad	Tipo	Detalle
id	Primitive (Integer)	Identificador del flujo en el sistema
client	Primitive (Integer)	Identificador del cliente en el sistema
groupId	Primitive (Integer)	Identificador del grupo al que pertenece el flujo
userExpData	Primitive (String)	Concatenación de los pasos del flujo separados por el carácter `\|`
key	Primitive (String)	Identificador del flujo
groupDescription	Primitive (String)	Descripción del grupo al que pertenece el flujo
isSmart	Primitive (Boolean)	Indica si la alerta inteligente está activada para el flujo
iaEnabled	Primitive (Boolean)	Indica si las capacidades de IA están activas para el flujo
videoRecording	Primitive (Boolean)	Indica si el robot ejecuta una grabación de video del flujo
tags	Array (Object)	Lista de etiquetas asociadas a la sonda del flujo (?)
location	Primitive (String)	Ubicación de la sonda asignada al flujo (?)
maintenance	Primitive (Integer)	Indica si el flujo está en mantenimiento manual (`1`) o no (`0`)
autoMaintenance	Primitive (Integer)	Indica si el flujo está en mantenimiento automático (`1`) o no (`0`)
flowCreatedAt	Primitive (String)	Fecha y hora (timestamp) en que se creó el flujo
environment	Primitive (String)	Entorno del flujo
integrations	Array (Object)	Lista de integraciones configuradas para el flujo

integrations [Objects in Array]:

Propiedad	Tipo	Detalle
key	Primitive (String)	Identificador del flujo
type	Primitive (String)	Canal asociado a la integración

Datos históricos de cliente

GET /audit/getHistoricClientData

Resumen de data histórica de cliente dada una ventana de tiempo especificada.

Request body

Example:

{ 
  "start": 1756743104000,
  "end": 1761339216000
}

Los parámetros de la petición se detallan a continuación:

Propiedad	Tipo	Descripción
start	Primitive (Long)	Inicio del periodo a consultar en formato timestamp (milisegundos)
end	Primitive (Long)	Fin del periodo a consultar en formato timestamp (milisegundos)

Response

dVirtualUser retornará una respuesta con una estructura JSON como la siguiente:

{
  "onDemandCalls": [
    {
      "apiAccessKey": "HwMqdtSLpTWL8thXXMJ*****6dS7cu6pwpJqbCDSEMDAu"
    },
    {
      "apiAccessKey": "HwMqdtSLpTWL8thXXMS*****7e4Ln3nPY5Ar/zKx6dS7c"
    },
    ...
  ],
  "executedSteps": [
    {
      "groupName": "group_25",
      "executedSteps": 40708
    },
    {
      "groupName": "group_1",
      "executedSteps": 2390
    },
    ...
  ],
  "executedActions": [
    {
      "groupName": "group_25",
      "executedActions": 61062
    },
    {
      "groupName": "group_1",
      "executedActions": 2390
    },
    ...
  ]
}

Las propiedades se detallan a continuación:

Main (Object):

Propiedad	Tipo	Descripción
onDemandCalls	Array (Object)	Lista de API Access Keys utilizadas por el cliente cada vez que llamó a un flujo de forma on-demand
executedSteps	Array (Object)	Arreglo con el número total de pasos ejecutados por agrupación de flujos
executedActions	Array (Object)	Arreglo con el número total de acciones ejecutadas por agrupación de flujos

onDemandCalls [Objects in Array]:

Propiedad	Tipo	Descripción
apiAccessKey	Primitive (String)	API Access Key asociada a una ejecución de flujo on-demand

executedSteps [Objects in Array]:

Propiedad	Tipo	Descripción
groupName	Primitive (String)	Nombre de una agrupación de flujos
executedSteps	Primitive (Integer?)	Número de pasos ejecutados durante la ventana de tiempo

executedActions [Objects in Array]:

Propiedad	Tipo	Descripción
groupName	Primitive (String)	Nombre de una agrupación de flujos
executedActions	Primitive (Integer?)	Número de acciones ejecutadas durante la ventana de tiempo

Conteo de alertas de cliente

GET /audit/getClientAlertCount

Obtiene cantidad de flujos ejecutados por el cliente y el estado de los mismos (exitoso/fallido) en una ventana de tiempo dada.

Request body

Los tiempos de inicio y final de la ventana de tiempo pueden entregarse como timestamp en milisegundos, o como fecha calendario en el formato yyyy-MM-dd

Ejemplo 1:

{ 
  "start": 1756743104000,
  "end": 1761339216000
}

En detalle:

Propiedad	Tipo	Descripción
start	Primitive (Long)	Fecha de inicio del periodo a consultar en formato timestamp (milisegundos)
end	Primitive (Long)	Fecha de término del periodo a consultar en formato timestamp (milisegundos)

Ejemplo 2:

{ 
  "dateStart": "2025-09-01",
  "dateEnd": "2025-10-24"
}

En detalle:

Propiedad	Tipo	Descripción
dateStart	Primitive (String)	Fecha de inicio del periodo a consultar en formato `YYYY-MM-DD`
dateEnd	Primitive (String)	Fecha de término del periodo a consultar en formato `YYYY-MM-DD`

Si se especifica la ventana de tiempo con ambos formatos en el mismo request, la fecha calendario (dateStart y dateEnd) toma precedencia

Parámetros opcionales:

Propiedad	Tipo	Descripción
useCache	Primitive (Boolean)	Indica si la petición puede intentar leer la respuesta desde la caché del servidor. Default: `true`.
storeDataInCache	Primitive (Boolean)	Indica si el resultado de esta petición debe almacenarse en la caché del servidor. Default: `false`.

Response

dVirtualUser retornará una respuesta con una estructura JSON como la siguiente:

{
  "summary": {
    "ok": 11865,
    "critical": 50353,
    "total": 62218
  },
  "flows": [
    {
      "groupDescription": "Mobile IOS",
      "robotId": 586467,
      "ok": 0,
      "critical": 20,
      "total": 20,
      "lastDate": "2025-09-23T03:00:00.000+00:00",
      "clientId": 1018
    },
    {
      "groupDescription": "Login",
      "robotId": 391281,
      "ok": 5932,
      "critical": 9838,
      "total": 15770,
      "lastDate": "2025-09-24T03:00:00.000+00:00",
      "clientId": 1018
    },
    ...
  ]
}

Propiedad	Tipo	Descripción
summary	Object	Elemento que contiene la información total de flujos ejecutados del cliente en el periodo consultado
flows	Array (Object)	Arreglo con los datos específicos por flujo

summary (Object):

Propiedad	Tipo	Descripción
ok	Primitive (Integer)	Cantidad de ejecuciones de flujos con resultado OK
critical	Primitive (Integer)	Cantidad de ejecuciones de flujos con errores
total	Primitive (Integer)	Cantidad de ejecuciones total como la suma de los dos valores anteriores

flows [Objects in Array]:

Propiedad	Tipo	Descripción
groupDescription	Primitive (String)	Grupo al que pertenece el flujo
robotId	Primitive (Integer)	Identificador del flujo
ok	Primitive (Integer)	Cantidad de ejecuciones con resultado OK del flujo particular
critical	Primitive (Integer)	Cantidad de ejecuciones con errores del flujo particular
total	Primitive (Integer)	Cantidad de ejecuciones total del flujo particular como la suma de los dos valores anteriores
lastDate	Primitive (String)	Fecha y hora de la última ejecución del flujo
clientId	Primitive (Integer)	Identificador del cliente