Cobertura WFM

English version: WFM coverage.

GET /v1/wfm/coverage devuelve una vista de dotación derivada para un día calendario UTC. No persiste ningún pronóstico: cada petición recalcula el resultado a partir de los flujos de sólo anexar. El endpoint acepta credenciales dd_ y ddu_; una credencial de widget (ddw_) está prohibida.

Petición

date es obligatorio y debe ser una fecha UTC YYYY-MM-DD dentro de los 366 días contados desde hoy. La respuesta siempre contiene 48 intervalos de media hora (interval_minutes: 30). Estas reglas y la frontera de autenticación salen de la operación getWfmCoverage del openapi/dialer-v1.yaml vendorizado.

Opcionalmente puedes simular un objetivo para esta respuesta enviando a la vez threshold_ms y target_percent. threshold_ms acepta de 1 a 86.400.000 milisegundos; target_percent acepta de 1 a 100. Enviar sólo uno no es válido. El objetivo simulado no se persiste y la respuesta pone simulated a true.

curl -sG "$API/v1/wfm/coverage" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "date=2026-10-12" \
  --data-urlencode "threshold_ms=20000" \
  --data-urlencode "target_percent=80"

Los parámetros de consulta, los límites y las respuestas 400/401/403/429 los define getWfmCoverage en la especificación vendorizada.

Qué significa el pronóstico

El pronóstico promedia el mismo día de la semana de las cuatro semanas anteriores que ya terminaron, en franjas UTC de 30 minutos. Cuenta los intentos entrantes ofrecidos: una fila original de call_attempts con corrects_id sin fijar y direction=inbound, salvo que una corrección posterior la marque not_placed.

El tiempo medio de gestión combina el tiempo de conversación y el wrap_up del agente. Para los puestos que también hacen llamadas salientes, ese wrap_up es una cota superior, porque el intervalo de origen no está asociado a una llamada concreta.

La respuesta usa source: "history" sólo tras alcanzar los dos mínimos de muestra: al menos dos días de referencia y al menos 30 llamadas ofrecidas. En caso contrario usa source: "estimate", un valor plano de seis llamadas ofrecidas por intervalo con un AHT de 300 segundos. Es explícitamente un marcador de posición, no una predicción.

Forma de la respuesta

La respuesta de nivel superior contiene date, interval_minutes, source, simulated, history, target e intervals. Los nombres y tipos obligatorios exactos salen del esquema WfmCoverageResponse de la especificación vendorizada.

Cada intervalo contiene:

• start y end, como valores date-time;
• forecast.volume, forecast.aht_ms y forecast.aht_source (slot, pooled o estimate);
• staffing, con required_agents, service_level, occupancy y reachable, o un motivo inert;
• scheduled_agents, los equivalentes a tiempo completo planificados;
• coverage.gap (planificado menos requerido) y coverage.ratio, o null cuando el objetivo es inerte.

La dotación requerida usa Erlang C contra el objetivo de servicio del tenant. El cálculo busca hasta 5.000 agentes. Si el objetivo no puede alcanzarse antes de ese tope — o el objetivo es 100% —, reachable es false y el número requerido queda topado. Cuando el tenant no tiene un objetivo de servicio utilizable, target y el staffing de cada intervalo informan un motivo inert y coverage es null.

La dotación planificada sale de los turnos planificados de R11: los turnos en pausa se excluyen y los turnos solapados de un mismo agente cuentan una vez. Estos significados, el tope, los motivos inertes y los campos del intervalo los definen WfmCoverageResponse, WfmCoverageInterval y WfmInert en la especificación vendorizada; las reglas del pronóstico y de Erlang C también constan en el ADR #241 de core.