Wfm

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.

Gestión de la fuerza laboral: la cobertura por intervalo de un día (pronóstico a partir del CDR, agentes requeridos según Erlang C frente al objetivo de servicio del tenant, agentes planificados en turnos R11). Una lectura derivada; no se persiste nada.

Endpoints

Método	Ruta	Resumen
GET	/v1/wfm/coverage	Pronóstico, agentes requeridos y planificados por intervalo de 30 minutos de un día

Pronóstico, agentes requeridos y planificados por intervalo de 30 minutos de un día

GET /v1/wfm/coverage

Superficie de gestión del tenant (dd_ o ddu_; un ddw_ de agente recibe 403). Una lectura derivada (ADR #241): no se almacena nada y cada llamada recalcula a partir de los streams de solo anexado.

Pronóstico. El mismo día de la semana de las 4 semanas anteriores (solo los días que ya terminaron), promediado por intervalo de 30 minutos del día UTC. Un intento entrante es una fila ORIGINAL de call_attempts (corrects_id IS NULL) marcada direction=inbound que no fue corregida después a not_placed; lo que se cuenta es lo OFRECIDO. El AHT es (conversación + wrap_up) / contestadas; wrap_up proviene de los agent_state_intervals cerrados de los puestos, por lo que para un puesto que también marca hacia afuera es una cota superior. Con menos de 2 días de referencia o menos de 30 llamadas ofrecidas, source es estimate (6 llamadas fijas por intervalo, AHT 300 s: un valor provisional, no una predicción) en lugar de history.

Agentes requeridos. Erlang C frente al objetivo de servicio del tenant. El objetivo nace ausente y ausente es inerte: sin él, target y el staffing de cada intervalo llevan {inert: <reason>} y coverage es null. Pasar AMBOS threshold_ms y target_percent simula un objetivo solo para esta respuesta (nunca se persiste; simulated: true). La búsqueda está limitada a 5000 agentes; un objetivo no alcanzado antes del tope dice reachable: false, y también lo dice un objetivo del 100 % (el modelo solo se aproxima a él de forma asintótica).

Agentes planificados. Equivalentes a tiempo completo del intervalo a partir de los turnos planificados R11 (los turnos paused se excluyen; los turnos superpuestos de un mismo agente cuentan una sola vez). coverage.gap es planificados menos requeridos.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
date	query	string (date)	sí	Día calendario UTC, YYYY-MM-DD, dentro de los 366 días a partir de hoy.
threshold_ms	query	integer	no	Umbral de espera simulado en ms (como máximo un día). Solo válido junto con target_percent.
target_percent	query	integer	no	Objetivo simulado, porcentaje de llamadas contestadas dentro de threshold_ms. Solo válido junto con threshold_ms.

Respuestas

200

Los 48 intervalos del día.

Campo	Tipo	Obligatorio	Descripción
date	string (date)	sí
interval_minutes	30	sí
source	history · estimate	sí	history cuando la ventana alcanzó el mínimo de muestra; estimate es el valor plano por defecto.
simulated	boolean	sí	Verdadero cuando el objetivo es el de la consulta, no el del tenant.
history	object	sí
history.reference_days	arreglo de string (date)	sí	Los días pasados (mismo día de la semana) sobre los que se promedió el pronóstico.
history.offered_sample	integer	sí
history.min_reference_days	integer	sí
history.min_sample_calls	integer	sí
target	object | WfmInert	sí
intervals	arreglo de WfmCoverageInterval	sí
intervals[].start	string (date-time)	sí
intervals[].end	string (date-time)	sí
intervals[].forecast	object	sí
intervals[].forecast.volume	number	sí	Llamadas ofrecidas esperadas en el intervalo.
intervals[].forecast.aht_ms	integer	sí
intervals[].forecast.aht_source	slot · pooled · estimate	sí	slot a partir del historial propio de este intervalo; pooled el AHT de toda la ventana; estimate el valor por defecto.
intervals[].staffing	object | WfmInert	sí
intervals[].scheduled_agents	number	sí	Equivalentes a tiempo completo planificados en el intervalo (turnos R11).
intervals[].coverage	object,null	sí	Null cuando el objetivo es inerte.
intervals[].coverage.gap	number	sí	Planificados menos requeridos; negativo es un déficit.
intervals[].coverage.ratio	number,null	sí	Planificados / requeridos; null cuando no se requiere nada.

400 — BadRequest

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

{
  "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.

{
  "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.

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

429 — ApiKeyRateLimited

Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}