WebSocket

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.

Endpoints

Método	Ruta	Resumen
POST	/v1/ws/ticket	Emitir un ticket de WebSocket efímero de un solo uso

Emitir un ticket de WebSocket efímero de un solo uso

POST /v1/ws/ticket

Emite la ÚNICA credencial que acepta GET /v1/ws (MT-SEC-05 / MT-SEC-10).

Los navegadores no pueden fijar cabeceras en un handshake de WebSocket, así que la credencial debe viajar en la cadena de consulta, donde acaba en los logs de acceso, el historial y el Referer. Este endpoint hace que lo que viaja ahí no valga nada: el ticket caduca en segundos y se QUEMA en el primer canje. El bearer de larga duración se queda donde puede ir: la cabecera Authorization de esta petición.

El ticket hereda el principal EXACTO del bearer que lo emitió: un bearer de agente ddw_ emite un ticket del carril de agente, nunca uno de tenant. El carril se codifica en el prefijo (ddta_ agente, ddtt_ tenant) para que el borde público pueda admitir solo el carril de agente sin consultar la base de datos.

El canje es de un solo uso: un segundo GET /v1/ws con el mismo ticket se rechaza, igual que uno caducado. Ambos responden el mismo 401 que un ticket desconocido: el cliente no aprende nada de la diferencia.

Tope de sockets (core#1285): un handshake rechazado con 429 llega a un navegador como un cierre 1006 pelado, indistinguible de una caída de red. Por eso este endpoint lee los MISMOS topes que la puerta de actualización (primero el del token de widget en el carril ddw_, luego el del tenant) y, cuando uno está lleno, responde 429 too_many_connections con un scope legible por máquina y no emite nada. Es un aviso temprano, no el control: un ticket emitido con holgura se sigue rechazando en la actualización si el tope se llena antes de canjearlo.

Respuestas

201

Un ticket recién emitido. Es válido durante expires_in segundos y para UN handshake.

Campo	Tipo	Obligatorio	Descripción
ticket	string	sí	Preséntalo como GET /v1/ws?ticket=…. Nunca reutilizable.
expires_at	string (date-time)	sí	Caducidad absoluta (RFC-3339).
expires_in	integer	sí	Segundos de vida. Deliberadamente pequeño.

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

El tope de sockets del piso en vivo está lleno (too_many_connections); no se emite ningún ticket. scope dice qué tope: widget_token (este ddw_ ya tiene sus sockets) o tenant (el tope del tenant). Reintenta cuando se cierre un socket, no en bucle.

tenant

{
  "error": {
    "code": "too_many_connections",
    "message": "live-floor connection limit reached for this tenant",
    "scope": "tenant"
  }
}

widget_token

{
  "error": {
    "code": "too_many_connections",
    "message": "live-floor connection limit reached for this widget token",
    "scope": "widget_token"
  }
}

503

No se pudo emitir el ticket (almacenamiento no disponible). Fail-closed: no se abre ningún socket.

{
  "error": {
    "code": "unavailable",
    "message": "could not mint a websocket ticket"
  }
}