Acceso de soporte

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.

Acceso del soporte de la plataforma (ADR 225): el consentimiento del cliente (una concesión con un motivo y una caducidad fija, una viva por tenant, revocable a voluntad) y su registro de solo anexado. Solo account_admin, salvo el banner.

Endpoints

Método	Ruta	Resumen
`POST`	`/v1/support-access/grants`	Dejar entrar al soporte de la plataforma, con un motivo y una caducidad fija
`DELETE`	`/v1/support-access/grants/{id}`	Terminar el consentimiento de inmediato
`GET`	`/v1/support-access/events`	El registro del acceso del soporte de la plataforma, del más reciente al más antiguo
`GET`	`/v1/support-access/active`	Si hay una sesión de soporte abierta ahora mismo (el banner)

Dejar entrar al soporte de la plataforma, con un motivo y una caducidad fija

http

POST /v1/support-access/grants

El consentimiento del cliente al acceso del soporte de la plataforma (ADR 225). Un account_admin indica un reason (un ticket o un motivo, de 1 a 500 caracteres, sin caracteres de control) y, opcionalmente, una duration_minutes (15 a 480, 60 por defecto). La concesión caduca en created_at + duration_minutes y esa caducidad NUNCA se mueve: un acceso más largo es una concesión nueva.

Solo hay una concesión viva por tenant a la vez: mientras una no esté revocada ni caducada la respuesta es 409 grant_already_live, que la nombra. Un evento grant_created se escribe en la misma transacción.

Esta ruta no abre nada por sí misma: una concesión es el consentimiento que necesita una sesión de soporte, y la vía de sesión está protegida por el flag support_access_enabled, que está DESACTIVADO en toda celda. La ruta responde sea cual sea el valor del flag, de modo que un cliente siempre puede conceder, revocar y leer el registro.

Solo inicio de sesión de account_admin en el dashboard (véase 403). El personal de la plataforma no tiene ninguna ruta para escribir una concesión.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`reason`	string	sí
`duration_minutes`	integer	no

Respuestas

`201`

La concesión está viva.

Campo	Tipo	Obligatorio	Descripción
`grant`	object (SupportAccessGrant)	sí
`grant.id`	string (uuid)	sí
`grant.granted_by`	string (uuid)	sí	El `account_admin` que la concedió.
`grant.reason`	string	sí
`grant.duration_minutes`	integer	sí
`grant.created_at`	string (date-time)	sí
`grant.expires_at`	string (date-time)	sí	Siempre `created_at + duration_minutes`; nunca se mueve.
`grant.revoked_at`	string (date-time) \| null	sí
`grant.revoked_by`	string (uuid) \| null	sí

`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`

role_forbidden: cualquier cosa que no sea un inicio de sesión de dashboard (ddu_) cuya persona tenga el rol account_admin — incluidos una clave de API dd_ y un inicio de sesión member; forbidden: un token de widget (ddw_) o un tenant suspendido.

json

{
  "error": {
    "code": "role_forbidden",
    "message": "granting platform-support access takes a dashboard login with the account_admin role"
  }
}

`409`

grant_already_live: el tenant ya tiene una concesión que no está revocada ni caducada; revócala primero.

json

{
  "error": {
    "code": "grant_already_live",
    "message": "a support-access grant is already live for this tenant; revoke it before granting again"
  }
}

`422`

unprocessable: el reason falta, está en blanco, supera los 500 caracteres o tiene caracteres de control, o duration_minutes no es un entero de 15 a 480. No se escribe nada.

json

{
  "error": {
    "code": "unprocessable",
    "message": "duration_minutes must be an integer from 15 to 480"
  }
}

`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-*.

json

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

Terminar el consentimiento de inmediato

http

DELETE /v1/support-access/grants/{id}

Revoca la concesión id. La fila se conserva como evidencia: gana revoked_at y revoked_by, una sola vez, y un evento grant_revoked se escribe en la misma transacción. Una concesión que caducó por sí sola aún puede revocarse. Una concesión revocada da 409 grant_already_revoked.

Un id desconocido, uno mal formado y la concesión de otro tenant dan el mismo 404.

Solo inicio de sesión de account_admin en el dashboard (véase 403).

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí

Respuestas

`200`

La concesión, ahora revocada.

Campo	Tipo	Obligatorio	Descripción
`grant`	object (SupportAccessGrant)	sí
`grant.id`	string (uuid)	sí
`grant.granted_by`	string (uuid)	sí	El `account_admin` que la concedió.
`grant.reason`	string	sí
`grant.duration_minutes`	integer	sí
`grant.created_at`	string (date-time)	sí
`grant.expires_at`	string (date-time)	sí	Siempre `created_at + duration_minutes`; nunca se mueve.
`grant.revoked_at`	string (date-time) \| null	sí
`grant.revoked_by`	string (uuid) \| null	sí

`401` — Unauthorized

json

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

`403`

role_forbidden: cualquier cosa que no sea un inicio de sesión de dashboard (ddu_) cuya persona tenga el rol account_admin.

json

{
  "error": {
    "code": "role_forbidden",
    "message": "revoking platform-support access takes a dashboard login with the account_admin role"
  }
}

`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"
  }
}

`409`

grant_already_revoked: la concesión se revocó antes.

json

{
  "error": {
    "code": "grant_already_revoked",
    "message": "this grant was already revoked"
  }
}

`429` — ApiKeyRateLimited

json

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

El registro del acceso del soporte de la plataforma, del más reciente al más antiguo

http

GET /v1/support-access/events

El registro de solo anexado del consentimiento y de todo lo que el soporte hizo bajo él, paginado por keyset, del más reciente al más antiguo. event es uno de grant_created, grant_revoked, session_opened, session_revoked, request y request_denied. Una fila request nombra el PATRÓN de ruta y el id de la ruta, nunca un cuerpo, una query string ni una respuesta. Las filas nunca se editan ni se eliminan.

Filtros: event, grant_id, since (inclusive) y until (exclusivo), ambos RFC-3339 sobre occurred_at. Un filtro que no se puede interpretar da 400 con los valores aceptados — nunca una página vacía en silencio. Acotado al tenant: las filas de otro tenant nunca son visibles, sea cual sea el filtro.

Solo inicio de sesión de account_admin en el dashboard (véase 403).

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`event`	query	`grant_created` · `grant_revoked` · `session_opened` · `session_revoked` · `request` · `request_denied`	no
`grant_id`	query	string (uuid)	no
`since`	query	string (date-time)	no	Solo eventos en este instante o posteriores.
`until`	query	string (date-time)	no	Solo eventos estrictamente anteriores a este instante.
`limit`	query	integer	no
`cursor`	query	string	no	Cursor keyset opaco: el `next_cursor` de la página anterior.

Respuestas

`200`

Una página del registro, del más reciente al más antiguo.

Campo	Tipo	Obligatorio	Descripción
`events`	arreglo de SupportAccessEvent	sí
`events[].id`	string (uuid)	sí
`events[].grant_id`	string (uuid)	sí
`events[].session_id`	string (uuid) \| null	sí	La sesión de soporte; `null` en `grant_created` y `grant_revoked`.
`events[].event`	`grant_created` · `grant_revoked` · `session_opened` · `session_revoked` · `request` · `request_denied`	sí
`events[].actor_kind`	`customer_user` · `operator`	sí
`events[].actor_ref`	string	sí	El id de la persona cliente, o `operator:<id> (<name>)` para el personal de la plataforma.
`events[].method`	`GET` · `HEAD` \| null	sí	Solo en `request` y `request_denied`.
`events[].route`	string \| null	sí	El PATRÓN de ruta (por ejemplo `/v1/leads/:id`), nunca la ruta con valores; solo en `request` y `request_denied`.
`events[].resource_id`	string \| null	sí	El id de la ruta, solo en filas `request`.
`events[].ip`	string \| null	sí
`events[].occurred_at`	string (date-time)	sí
`next_cursor`	string \| null	sí	Cursor de la página siguiente; `null` en la última.

`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`

role_forbidden: cualquier cosa que no sea un inicio de sesión de dashboard (ddu_) cuya persona tenga el rol account_admin.

json

{
  "error": {
    "code": "role_forbidden",
    "message": "the support-access trail takes a dashboard login with the account_admin role"
  }
}

`429` — ApiKeyRateLimited

json

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

Si hay una sesión de soporte abierta ahora mismo (el banner)

http

GET /v1/support-access/active

Lo que el dashboard muestra a toda persona del tenant: si alguien del soporte de la plataforma está dentro de la cuenta en este momento, hasta cuándo y quién. active es false cuando el flag support_access_enabled está desactivado para el tenant, cuando no hay concesión viva, o cuando ninguna sesión de ella está abierta y sin caducar. Una sesión está abierta desde su evento session_opened hasta uno session_revoked, durante como máximo 60 minutos y nunca más allá de la caducidad de la concesión. La propia sesión de soporte llega con un cambio posterior: hasta entonces esto responde active: false para todos los tenants.

Cualquier inicio de sesión de dashboard (ddu_) del tenant, member incluido. Una clave de API (dd_) da 403.

Respuestas

`200`

La respuesta del banner.

Campo	Tipo	Obligatorio	Descripción
`active`	boolean	sí
`expires_at`	string (date-time) \| null	sí	Cuándo termina la sesión abierta; `null` cuando no está activa.
`operator_name`	string \| null	sí	El nombre de la persona de la plataforma; `null` cuando no está activa o no tiene nombre.

`401` — Unauthorized

json

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

`403`

role_forbidden: una clave de API dd_; forbidden: un token de widget o un tenant suspendido.

json

{
  "error": {
    "code": "role_forbidden",
    "message": "the support-access banner takes a dashboard login"
  }
}

`429` — ApiKeyRateLimited

json

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

Acceso de soporte ​

Endpoints ​

Dejar entrar al soporte de la plataforma, con un motivo y una caducidad fija ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 ​

409 ​

422 ​

429 — ApiKeyRateLimited ​

Terminar el consentimiento de inmediato ​

200 ​

401 — Unauthorized ​

403 ​

404 — NotFound ​

409 ​

429 — ApiKeyRateLimited ​

El registro del acceso del soporte de la plataforma, del más reciente al más antiguo ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 ​

429 — ApiKeyRateLimited ​

Si hay una sesión de soporte abierta ahora mismo (el banner) ​

200 ​

401 — Unauthorized ​

403 ​

429 — ApiKeyRateLimited ​

Acceso de soporte

Endpoints

Dejar entrar al soporte de la plataforma, con un motivo y una caducidad fija

`201`

`400` — BadRequest

`401` — Unauthorized

`403`

`409`

`422`

`429` — ApiKeyRateLimited

Terminar el consentimiento de inmediato

`200`

`401` — Unauthorized

`403`

`404` — NotFound

`409`

`429` — ApiKeyRateLimited

El registro del acceso del soporte de la plataforma, del más reciente al más antiguo

`200`

`400` — BadRequest

`401` — Unauthorized

`403`

`429` — ApiKeyRateLimited

Si hay una sesión de soporte abierta ahora mismo (el banner)

`200`

`401` — Unauthorized

`403`

`429` — ApiKeyRateLimited