Destinos de transferencia

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.

El registro del tenant de los números externos a los que se puede transferir una llamada en curso.

Endpoints

Método	Ruta	Resumen
GET	/v1/transfer-destinations	Los destinos de transferencia externos vigentes del tenant
POST	/v1/transfer-destinations	Registrar un destino de transferencia externo
PATCH	/v1/transfer-destinations/{id}	Declarar el tipo de línea de un destino de transferencia externo registrado
DELETE	/v1/transfer-destinations/{id}	Retirar un destino de transferencia externo
GET	/v1/transfer/targets	A dónde se puede transferir una llamada en curso, tal como lo necesita un selector

Los destinos de transferencia externos vigentes del tenant

GET /v1/transfer-destinations

Los números registrados hacia los que puede salir una transferencia ciega, del registro más antiguo al más reciente. Los destinos retirados no se listan. Lo puede leer una clave dd_ y cualquier login de dashboard; un token de widget (ddw_) recibe 403 forbidden.

Respuestas

200

Los registros vigentes.

Campo	Tipo	Obligatorio	Descripción
transfer_destinations	arreglo de TransferDestination	sí
transfer_destinations[].id	string (uuid)	sí	El registro; el id con el que retirarlo.
transfer_destinations[].number	string	sí	E.164 estricto.
transfer_destinations[].label	string	sí
transfer_destinations[].line_type	mobile · landline · voip · unknown	sí	Lo que el tenant declara que es la línea: los mismos valores y el mismo valor por defecto que el line_type de un contacto al importarlo. La compuerta de consentimiento lo lee para una transferencia a ese número: landline levanta el requisito de consentimiento expreso previo; unknown, mobile y voip lo mantienen.
transfer_destinations[].line_type_declared_at	string (date-time)	sí	Cuándo se declaró el line_type vigente: registered_at hasta que un PATCH lo cambia.
transfer_destinations[].line_type_declared_by	string	sí	Quién declaró el line_type vigente (misma forma que registered_by).
transfer_destinations[].registered_at	string (date-time)	sí	Cuándo se registró; el ancla con la que se consulta el RND para este número.
transfer_destinations[].registered_by	string	sí	El id de usuario o de agente de la credencial que lo registró, o tenant-api-key.

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

Registrar un destino de transferencia externo

POST /v1/transfer-destinations

Registra number (E.164 estricto) con una label. A partir de entonces una transferencia ciega puede dirigirse a él; sigue pasando toda la cadena GATE_PRE_DIAL. El instante del registro es también el ancla con la que se consulta la Base de Datos de Números Reasignados (RND) para este número, y registrarlo programa esa consulta (una transferencia a él se bloquea con rnd.no_current_result.v1 hasta que llega la respuesta, en una celda con un proveedor de RND real).

Solo gestión del tenant: una clave dd_ o un login account_admin. Un login member recibe 403 role_forbidden; un token de widget (ddw_) recibe 403 forbidden. Quién lo registró se toma de la credencial, nunca del cuerpo. Un número que ya es un registro VIGENTE de este tenant da 409 conflict; retíralo primero para volver a registrarlo.

line_type es lo que el tenant declara que es la línea, exactamente como lo declara para un consumidor que importa (mismos valores, mismo valor por defecto unknown). Es lo que lee la compuerta de consentimiento para una transferencia a este número: landline levanta el requisito de consentimiento expreso previo, y nada más: todas las demás compuertas siguen ejecutándose. Un valor vacío o ausente es unknown. Cámbialo después con PATCH.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
number	string	sí	E.164 estricto.
label	string	sí	Qué es el número, para el operador (recortado; un valor vacío se rechaza).
line_type	mobile · landline · voip · unknown	no	Lo que el tenant declara que es la línea: los mismos valores y el mismo valor por defecto que el line_type de un contacto al importarlo. La compuerta de consentimiento lo lee para una transferencia a ese número: landline levanta el requisito de consentimiento expreso previo; unknown, mobile y voip lo mantienen.

{
  "number": "+13125550170",
  "label": "Legal department",
  "line_type": "landline"
}

Respuestas

201

Registrado.

Campo	Tipo	Obligatorio	Descripción
transfer_destination	object (TransferDestination)	sí
transfer_destination.id	string (uuid)	sí	El registro; el id con el que retirarlo.
transfer_destination.number	string	sí	E.164 estricto.
transfer_destination.label	string	sí
transfer_destination.line_type	mobile · landline · voip · unknown	sí	Lo que el tenant declara que es la línea: los mismos valores y el mismo valor por defecto que el line_type de un contacto al importarlo. La compuerta de consentimiento lo lee para una transferencia a ese número: landline levanta el requisito de consentimiento expreso previo; unknown, mobile y voip lo mantienen.
transfer_destination.line_type_declared_at	string (date-time)	sí	Cuándo se declaró el line_type vigente: registered_at hasta que un PATCH lo cambia.
transfer_destination.line_type_declared_by	string	sí	Quién declaró el line_type vigente (misma forma que registered_by).
transfer_destination.registered_at	string (date-time)	sí	Cuándo se registró; el ancla con la que se consulta el RND para este número.
transfer_destination.registered_by	string	sí	El id de usuario o de agente de la credencial que lo registró, o tenant-api-key.

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

role_forbidden: un inicio de sesión de dashboard sin el rol account_admin; forbidden: un token de widget o un tenant suspendido.

{
  "error": {
    "code": "role_forbidden",
    "message": "a dashboard login needs the account_admin role to manage transfer destinations"
  }
}

409 — Conflict

Transición de estado no válida, conflicto de unicidad, o un asiento que está ocupado/reservado.

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

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

Declarar el tipo de línea de un destino de transferencia externo registrado

PATCH /v1/transfer-destinations/{id}

Cambia el line_type del registro VIGENTE id. El cambio es un hecho nuevo en el historial de solo anexar del registro, con quién lo hizo (tomado de la credencial) y cuándo; la respuesta lleva ambos como line_type_declared_by / line_type_declared_at. El registro en sí no se mueve: mismo id, mismo registered_at, así que el ancla de RND del número no cambia. Declarar el valor que ya tiene no escribe nada.

La siguiente transferencia al número lee el valor nuevo. landline levanta el requisito de consentimiento expreso previo de la compuerta de consentimiento y nada más; unknown, mobile y voip lo mantienen.

Solo se acepta line_type (el número y la etiqueta son el registro: retira y registra de nuevo para cambiarlos); cualquier otra clave da 400. Un valor fuera de la lista da 400. Un id que no es un registro vigente de este tenant (desconocido, retirado o de otro tenant) da 404. Mismos roles que el registro.

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.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
line_type	mobile · landline · voip · unknown	sí	Lo que el tenant declara que es la línea: los mismos valores y el mismo valor por defecto que el line_type de un contacto al importarlo. La compuerta de consentimiento lo lee para una transferencia a ese número: landline levanta el requisito de consentimiento expreso previo; unknown, mobile y voip lo mantienen.

{
  "line_type": "landline"
}

Respuestas

200

El destino con su tipo de línea vigente.

Campo	Tipo	Obligatorio	Descripción
transfer_destination	object (TransferDestination)	sí
transfer_destination.id	string (uuid)	sí	El registro; el id con el que retirarlo.
transfer_destination.number	string	sí	E.164 estricto.
transfer_destination.label	string	sí
transfer_destination.line_type	mobile · landline · voip · unknown	sí	Lo que el tenant declara que es la línea: los mismos valores y el mismo valor por defecto que el line_type de un contacto al importarlo. La compuerta de consentimiento lo lee para una transferencia a ese número: landline levanta el requisito de consentimiento expreso previo; unknown, mobile y voip lo mantienen.
transfer_destination.line_type_declared_at	string (date-time)	sí	Cuándo se declaró el line_type vigente: registered_at hasta que un PATCH lo cambia.
transfer_destination.line_type_declared_by	string	sí	Quién declaró el line_type vigente (misma forma que registered_by).
transfer_destination.registered_at	string (date-time)	sí	Cuándo se registró; el ancla con la que se consulta el RND para este número.
transfer_destination.registered_by	string	sí	El id de usuario o de agente de la credencial que lo registró, o tenant-api-key.

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

role_forbidden: un inicio de sesión de dashboard sin el rol account_admin; forbidden: un token de widget o un tenant suspendido.

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).

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

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

Retirar un destino de transferencia externo

DELETE /v1/transfer-destinations/{id}

Retira el registro VIGENTE id: una transferencia ciega a ese número se vuelve a rechazar con transfer.destination_unregistered.v1. El historial es de solo anexar: la retirada es un hecho nuevo, y la respuesta es el destino que se retiró. Un id que no es un registro vigente de este tenant (desconocido, ya retirado o de otro tenant) da 404. Mismos roles que el registro.

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

Retirado.

Campo	Tipo	Obligatorio	Descripción
transfer_destination	object (TransferDestination)	sí
transfer_destination.id	string (uuid)	sí	El registro; el id con el que retirarlo.
transfer_destination.number	string	sí	E.164 estricto.
transfer_destination.label	string	sí
transfer_destination.line_type	mobile · landline · voip · unknown	sí	Lo que el tenant declara que es la línea: los mismos valores y el mismo valor por defecto que el line_type de un contacto al importarlo. La compuerta de consentimiento lo lee para una transferencia a ese número: landline levanta el requisito de consentimiento expreso previo; unknown, mobile y voip lo mantienen.
transfer_destination.line_type_declared_at	string (date-time)	sí	Cuándo se declaró el line_type vigente: registered_at hasta que un PATCH lo cambia.
transfer_destination.line_type_declared_by	string	sí	Quién declaró el line_type vigente (misma forma que registered_by).
transfer_destination.registered_at	string (date-time)	sí	Cuándo se registró; el ancla con la que se consulta el RND para este número.
transfer_destination.registered_by	string	sí	El id de usuario o de agente de la credencial que lo registró, o tenant-api-key.

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

role_forbidden: un inicio de sesión de dashboard sin el rol account_admin; forbidden: un token de widget o un tenant suspendido.

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).

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

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

A dónde se puede transferir una llamada en curso, tal como lo necesita un selector

GET /v1/transfer/targets

La ÚNICA lectura que necesita un selector de transferencia, y la única de su clase a la que puede acceder un token de widget (ddw_): la lista (GET /v1/agents) y el registro (GET /v1/transfer-destinations) siguen dando 403 para él, porque responden más de lo que pinta un selector (emails, roles, estado de credenciales, el E.164) y el widget vive dentro de CRMs de terceros. Solo lectura, acotada al tenant de quien llama. Tres clases, cada elemento con solo lo que muestra el selector y el valor que su verbo de transferencia toma como destination:

• agents: agentes ACTIVOS con un sip_extension; envía el id (o la extensión). presence es el estado del puesto AHORA y es informativo: si el puesto está libre lo dice la propia respuesta de la transferencia (422 destination_unavailable). Un token de widget no ve a su propio agente.
• extensions: extensiones de la lista sin ningún agente detrás; envía el sip_extension. Siempre vacía hoy: la lista no tiene ninguna extensión aparte de las de sus agentes. La clase está en la respuesta para que un selector no cambie de forma cuando aparezca una.
• external_destinations: los destinos externos registrados VIGENTES del tenant, solo id y label, nunca el número. Envía el id a POST /v1/calls/{call_id}/transfer; core resuelve el E.164 por sí mismo y la transferencia pasa todas las compuertas que pasa una transferencia a ese número. La transferencia asistida no los admite.

Fail-closed: si no se puede leer la lista, el estado del puesto o el registro, la respuesta es 503 transfer_targets_unavailable, nunca una lista vacía que se leería como «no hay a dónde transferir».

Respuestas

200

Las tres clases (cualquiera de ellas puede estar vacía).

Campo	Tipo	Obligatorio	Descripción
agents	arreglo de object	sí
agents[].id	string (uuid)	sí	El agente; un destination de transferencia válido.
agents[].name	string	sí
agents[].sip_extension	string	sí
agents[].presence	offline · available · ringing · on_call · wrap_up · paused	sí	El estado del puesto ahora, como en la lista; solo informativo.
extensions	arreglo de object	sí	Extensiones de la lista sin ningún agente detrás. Siempre vacía hoy.
extensions[].sip_extension	string	sí	Un destination de transferencia válido.
extensions[].label	string	sí
external_destinations	arreglo de object	sí	Los destinos externos registrados vigentes. Nunca lleva el número.
external_destinations[].id	string (uuid)	sí	El registro; un destination de transferencia ciega válido, que core resuelve a su E.164.
external_destinations[].label	string	sí

{
  "agents": [
    {
      "id": "2f1c9a2e-6b3d-4c1e-9a7f-0d4e5b6c7a81",
      "name": "Ana Ruiz",
      "sip_extension": "1002",
      "presence": "available"
    }
  ],
  "extensions": [],
  "external_destinations": [
    {
      "id": "7b0e1f3a-2c4d-4e5f-8a9b-1c2d3e4f5a6b",
      "label": "Legal department"
    }
  ]
}

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

503

transfer_targets_unavailable: no se pudo leer la lista, el estado del puesto o el registro. Reintenta; nunca se usa una clase vacía para decir esto.

{
  "error": {
    "code": "transfer_targets_unavailable",
    "message": "transfer targets could not be read, retry"
  }
}