Insights

Generado desde DialerDigital/core commit 0fc18008b3c8 — especificación openapi/dialer-v1.yaml v0.134.0. No se edita a mano; consulta Cómo se construye esta referencia. Descargar la especificación OpenAPI.

English version

Traducción en curso

Esta referencia se genera desde la especificación OpenAPI. Las cadenas que todavía no tienen traducción aparecen en inglés.

Evidencia de anomalías del evaluador de insights (core#1983): series de contacto, abandono, coste, bloqueo por compuerta y timeout de medios, cada anomalía con su serie y su umbral. Siempre activo; insights_anomaly_k sólo ajusta la sensibilidad.

Endpoints

Método	Ruta	Resumen
`GET`	`/v1/insights/anomalies`	Anomalías que abrió el evaluador, con su evidencia
`GET`	`/v1/insights/series`	Una métrica en intervalos horarios con la banda que usa la regla
`POST`	`/v1/insights/anomalies/{id}/ack`	Confirmar una anomalía como el usuario que llama

Anomalías que abrió el evaluador, con su evidencia

http

GET /v1/insights/anomalies

Cada anomalía es su fila opened: el valor observado, la línea base contra la que se midió (baseline_mean, baseline_stddev, stddev_floor, baseline_n), el threshold resultante con su k, la muestra del intervalo (sample_n) y la series horaria que dibuja el dashboard. Una fila resolved que la cita hace que state sea resolved y rellena resolution. Las más recientes primero; pagina con cursor.

La confirmación es POR PERSONA: read indica si el usuario que llama confirmó la anomalía, y unread=true conserva sólo las que el llamante no ha confirmado. Una clave dd_ no tiene bandeja: read es null y unread=true es 400. Siempre activo: no hay indicador de activación.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`campaign_id`	query	string (uuid)	no	Sólo la serie de esta campaña.
`metric`	query	`contact_rate` · `abandon_rate` · `cost_per_contact` · `gate_block_rate` · `media_timeout_rate`	no
`state`	query	`open` · `resolved`	no
`unread`	query	boolean	no	`true` conserva las anomalías que el usuario que llama no ha confirmado (sólo un login del dashboard).
`limit`	query	integer	no	Tamaño de página, 50 por defecto y como máximo 200.
`cursor`	query	string	no	El `next_cursor` de la página anterior.

Respuestas

`200`

Una página de anomalías.

Campo	Tipo	Obligatorio	Descripción
`anomalies`	arreglo de InsightsAnomaly	sí
`anomalies[].id`	string (uuid)	sí
`anomalies[].campaign_id`	string,null (uuid)	sí	`null` para la serie de todo el tenant.
`anomalies[].metric`	`contact_rate` · `abandon_rate` · `cost_per_contact` · `gate_block_rate` · `media_timeout_rate`	sí	`contact_rate` alerta a la baja; cualquier otra métrica alerta al alza.
`anomalies[].gate`	string,null	sí	Sólo `gate_block_rate` lleva una compuerta.
`anomalies[].rule`	string	sí	La regla que la produjo, p. ej. `zscore.v1`.
`anomalies[].direction`	`up` · `down`	sí	La dirección dañina que se cruzó.
`anomalies[].state`	`open` · `resolved`	sí
`anomalies[].window_start`	string (date-time)	sí	El intervalo horario que cruzó el umbral (inclusivo).
`anomalies[].window_end`	string (date-time)	sí	El mismo intervalo (exclusivo).
`anomalies[].observed`	number	sí	El valor del intervalo.
`anomalies[].baseline_mean`	number	sí
`anomalies[].baseline_stddev`	number	sí	Desviación estándar muestral de los intervalos de la línea base.
`anomalies[].stddev_floor`	number	sí	El piso aplicado a la desviación para que una serie casi constante no alerte por ruido.
`anomalies[].threshold`	number	sí	`baseline_mean ± k·max(baseline_stddev, stddev_floor)` en el lado dañino.
`anomalies[].k`	number	sí	La sensibilidad vigente cuando se abrió (`insights_anomaly_k`).
`anomalies[].sample_n`	integer	sí	Intentos en el intervalo.
`anomalies[].baseline_n`	integer	sí	Intervalos de línea base usados.
`anomalies[].series`	arreglo de InsightsSeriesPoint	sí	Los intervalos de la línea base seguidos del intervalo que cruzó, del más antiguo al más reciente.
`anomalies[].series[].t`	string (date-time)	sí	Inicio del intervalo horario.
`anomalies[].series[].sample`	integer	sí
`anomalies[].series[].numerator`	number	sí
`anomalies[].series[].denominator`	number	sí
`anomalies[].series[].value`	number,null	sí	`numerator / denominator`.
`anomalies[].opened_at`	string (date-time)	sí
`anomalies[].resolution`	object,null	sí	La fila que la cerró; `null` mientras está abierta.
`anomalies[].resolution.id`	string (uuid)	sí
`anomalies[].resolution.window_start`	string (date-time)	sí
`anomalies[].resolution.window_end`	string (date-time)	sí
`anomalies[].resolution.observed`	number	sí
`anomalies[].resolution.resolved_at`	string (date-time)	sí
`anomalies[].read`	boolean,null	sí	Si el usuario que llama la confirmó; `null` para una clave `dd_`.
`anomalies[].acknowledged_at`	string,null (date-time)	sí
`next_cursor`	string,null	sí	`null` en la última página.

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

El tenant está suspendido. Una sesión del dashboard (ddu_) de un tenant cuya política de inicio de sesión (ADR 227) está en modo enforce responde 403 con el código login_policy_denied ante una solicitud desde una dirección o en una hora que la política no permite — el mismo cuerpo en ambos casos; la sesión no se revoca y una solicitud posterior dentro de la política se procesa. Un token de widget (ddw_) de un puesto queda sujeto a la misma política en cada solicitud (core#2406, indicador widget_login_honors_policy). Un tenant sintético (demo) responde 403 con el código synthetic_tenant en toda ruta que llegaría a un tercero — marcación manual, pierna de transferencia externa o de conferencia, envío de SMS (core#2251, adenda del ADR #280). Ningún pago lo cambia.

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

Una métrica en intervalos horarios con la banda que usa la regla

http

GET /v1/insights/series

Los intervalos horarios de metric en [from, to) y, para cada uno, la banda mean ± k·max(σ, floor) que zscore.v1 calcula a partir de los 7 días anteriores al intervalo, excluido el propio intervalo: la misma aritmética que el evaluador, de modo que el gráfico muestra por qué un punto cruzó o no. band es null mientras el intervalo tiene menos de 24 intervalos de línea base (min_baseline); un intervalo con menos de min_sample intentos se dibuja pero nunca se evalúa. k es el insights_anomaly_k del tenant.

from y to se redondean hacia abajo a la hora; to por defecto es ahora y from 48 horas antes. La ventana no puede superar 14 días. gate es obligatorio para gate_block_rate y se rechaza para cualquier otra métrica.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`metric`	query	`contact_rate` · `abandon_rate` · `cost_per_contact` · `gate_block_rate` · `media_timeout_rate`	sí
`campaign_id`	query	string (uuid)	no	La serie de esta campaña; si se omite, la de todo el tenant.
`gate`	query	string	no	La compuerta de cumplimiento (de 1 a 64 bytes); sólo con `gate_block_rate`.
`from`	query	string (date-time)	no	Cota inferior RFC 3339 (inclusiva), redondeada hacia abajo a la hora.
`to`	query	string (date-time)	no	Cota superior RFC 3339 (exclusiva), redondeada hacia abajo a la hora.

Respuestas

`200`

La serie.

Campo	Tipo	Obligatorio	Descripción
`rule`	string	sí
`metric`	`contact_rate` · `abandon_rate` · `cost_per_contact` · `gate_block_rate` · `media_timeout_rate`	sí	`contact_rate` alerta a la baja; cualquier otra métrica alerta al alza.
`campaign_id`	string,null (uuid)	sí
`gate`	string,null	sí
`direction`	`up` · `down`	sí
`k`	number	sí
`min_sample`	integer	sí	Intentos que necesita un intervalo para ser evaluado.
`min_baseline`	integer	sí	Intervalos de línea base que necesita una serie para ser evaluada.
`from`	string (date-time)	sí
`to`	string (date-time)	sí
`buckets`	arreglo de InsightsSeriesBucket	sí
`buckets[].start`	string (date-time)	sí
`buckets[].sample`	integer	sí
`buckets[].numerator`	number	sí
`buckets[].denominator`	number	sí
`buckets[].value`	number,null	sí
`buckets[].band`	InsightsBand \| null	sí	`null` mientras el intervalo tiene menos de `min_baseline` intervalos de línea base.

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

Confirmar una anomalía como el usuario que llama

http

POST /v1/insights/anomalies/{id}/ack

Escribe la confirmación del usuario que llama (sólo se añade, una por usuario y anomalía). Idempotente: confirmar de nuevo responde 200 con la confirmación que ya existe. Requiere un login del dashboard: una clave dd_ no tiene bandeja y recibe 403. Un id que no es una anomalía del tenant (de otro tenant, una fila de resolución, uno inventado) da 404.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`200`

La confirmación.

Campo	Tipo	Obligatorio
`ack`	object (InsightsAck)	sí
`ack.anomaly_id`	string (uuid)	sí
`ack.user_id`	string (uuid)	sí
`ack.acknowledged_at`	string (date-time)	sí

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

Insights ​

Endpoints ​

Anomalías que abrió el evaluador, con su evidencia ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

Una métrica en intervalos horarios con la banda que usa la regla ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

Confirmar una anomalía como el usuario que llama ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

Insights

Endpoints

Anomalías que abrió el evaluador, con su evidencia

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

Una métrica en intervalos horarios con la banda que usa la regla

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

Confirmar una anomalía como el usuario que llama

`200`

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound