Click to call

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.

Click-to-call para el sitio web del cliente (ADR 220): la consola emite y revoca una clave de sitio PUBLICABLE ddc_, y el navegador del visitante la usa para leer la configuración del formulario y dejar una solicitud de llamada. Controlado por click_to_call_enabled.

Endpoints

Método	Ruta	Resumen
`GET`	`/v1/click-to-call/sites`	Listar los sitios de click-to-call del tenant
`POST`	`/v1/click-to-call/sites`	Emitir una clave de sitio de click-to-call
`GET`	`/v1/click-to-call/sites/{id}`	Leer un sitio de click-to-call
`PATCH`	`/v1/click-to-call/sites/{id}`	Configurar un sitio de click-to-call
`DELETE`	`/v1/click-to-call/sites/{id}`	Revocar la clave de un sitio de click-to-call
`GET`	`/v1/public/call-request-config`	Leer la configuración del formulario de solicitud de llamada
`POST`	`/v1/public/call-requests`	Dejar una solicitud de llamada

Listar los sitios de click-to-call del tenant

http

GET /v1/click-to-call/sites

Todos los sitios del tenant, los más recientes primero, incluidos los revocados (revoked_at informado). Cada uno lleva su texto de consentimiento VIGENTE, su versión y su sha256. Nunca lleva la clave (solo se almacena su sha256). Las lecturas no están controladas por click_to_call_enabled.

Respuestas

`200`

Los sitios del tenant.

Campo	Tipo	Obligatorio	Descripción
`sites`	arreglo de ClickToCallSite	sí
`sites[].id`	string (uuid)	no
`sites[].campaign_id`	string (uuid)	no
`sites[].label`	string	no
`sites[].allow_immediate`	boolean	no
`sites[].allow_scheduled`	boolean	no
`sites[].tenant_daily_cap`	integer	no
`sites[].number_daily_cap`	integer	no
`sites[].site_hourly_cap`	integer	no
`sites[].revoked_at`	string (date-time) \| null	no
`sites[].created_at`	string (date-time)	no
`sites[].updated_at`	string (date-time)	no
`sites[].consent_version`	string \| null	no	Versión vigente del texto de consentimiento (cadena decimal, p. ej. "2"); null mientras el sitio no tenga texto.
`sites[].consent_text`	string \| null	no
`sites[].consent_sha256`	string \| null	no	sha256 en hexadecimal minúscula de los bytes de `consent_text`, calculado por el servidor.

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

json

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

json

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

Emitir una clave de sitio de click-to-call

http

POST /v1/click-to-call/sites

Crea un sitio ligado a una campaña y devuelve su clave publicable ddc_. El texto plano se muestra exactamente una vez; solo se almacena su sha256. Requiere click_to_call_enabled para el tenant (403 en caso contrario). Un consent_text indicado aquí pasa a ser la versión 1; sin él, el sitio no tiene texto de consentimiento y rechaza todas las solicitudes (409 consent_version_mismatch) hasta que se configure uno con PATCH /v1/click-to-call/sites/{id}.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`campaign_id`	string (uuid)	sí
`label`	string	no
`allow_immediate`	boolean	no
`allow_scheduled`	boolean	no
`tenant_daily_cap`	integer	no
`number_daily_cap`	integer	no
`site_hourly_cap`	integer	no
`consent_text`	string	no	Pasa a ser la versión 1 del consentimiento del sitio.

json

{
  "campaign_id": "7f1c0b0e-5d3a-4c55-9a3e-0b6f3b1f2a10",
  "label": "Landing de ventas"
}

Respuestas

`201`

El sitio y su clave (se muestra una sola vez).

Campo	Tipo	Obligatorio	Descripción
`site`	object (ClickToCallSite)	sí	Un sitio de click-to-call tal como lo ve la consola. Nunca lleva la clave.
`site.id`	string (uuid)	no
`site.campaign_id`	string (uuid)	no
`site.label`	string	no
`site.allow_immediate`	boolean	no
`site.allow_scheduled`	boolean	no
`site.tenant_daily_cap`	integer	no
`site.number_daily_cap`	integer	no
`site.site_hourly_cap`	integer	no
`site.revoked_at`	string (date-time) \| null	no
`site.created_at`	string (date-time)	no
`site.updated_at`	string (date-time)	no
`site.consent_version`	string \| null	no	Versión vigente del texto de consentimiento (cadena decimal, p. ej. "2"); null mientras el sitio no tenga texto.
`site.consent_text`	string \| null	no
`site.consent_sha256`	string \| null	no	sha256 en hexadecimal minúscula de los bytes de `consent_text`, calculado por el servidor.
`token`	string	sí	Clave de sitio ddc_ en texto plano, mostrada exactamente una vez.

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

json

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

`429` — ApiKeyRateLimited

json

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

Leer un sitio de click-to-call

http

GET /v1/click-to-call/sites/{id}

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`

El sitio con su texto de consentimiento vigente.

Campo	Tipo	Obligatorio	Descripción
`site`	object (ClickToCallSite)	sí	Un sitio de click-to-call tal como lo ve la consola. Nunca lleva la clave.
`site.id`	string (uuid)	no
`site.campaign_id`	string (uuid)	no
`site.label`	string	no
`site.allow_immediate`	boolean	no
`site.allow_scheduled`	boolean	no
`site.tenant_daily_cap`	integer	no
`site.number_daily_cap`	integer	no
`site.site_hourly_cap`	integer	no
`site.revoked_at`	string (date-time) \| null	no
`site.created_at`	string (date-time)	no
`site.updated_at`	string (date-time)	no
`site.consent_version`	string \| null	no	Versión vigente del texto de consentimiento (cadena decimal, p. ej. "2"); null mientras el sitio no tenga texto.
`site.consent_text`	string \| null	no
`site.consent_sha256`	string \| null	no	sha256 en hexadecimal minúscula de los bytes de `consent_text`, calculado por el servidor.

`401` — Unauthorized

json

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

`403` — Forbidden

json

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

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

`429` — ApiKeyRateLimited

json

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

Configurar un sitio de click-to-call

http

PATCH /v1/click-to-call/sites/{id}

Actualización parcial de etiqueta, campaña, modos permitidos, topes y texto de consentimiento. Un consent_text distinto del vigente inserta la versión N+1 (las versiones anteriores son evidencia de solo anexar y nunca se modifican ni se borran); el mismo texto otra vez no cambia nada. La identidad, la clave y revoked_at no se pueden cambiar. Un sitio revocado es de solo lectura (409). No está controlado por click_to_call_enabled.

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
`campaign_id`	string (uuid)	no
`label`	string	no
`allow_immediate`	boolean	no
`allow_scheduled`	boolean	no
`tenant_daily_cap`	integer	no
`number_daily_cap`	integer	no
`site_hourly_cap`	integer	no
`consent_text`	string	no	Un texto distinto del vigente crea la versión N+1.

json

{
  "number_daily_cap": 3,
  "consent_text": "Acepto que me llamen al número indicado."
}

Respuestas

`200`

El sitio actualizado.

Campo	Tipo	Obligatorio	Descripción
`site`	object (ClickToCallSite)	sí	Un sitio de click-to-call tal como lo ve la consola. Nunca lleva la clave.
`site.id`	string (uuid)	no
`site.campaign_id`	string (uuid)	no
`site.label`	string	no
`site.allow_immediate`	boolean	no
`site.allow_scheduled`	boolean	no
`site.tenant_daily_cap`	integer	no
`site.number_daily_cap`	integer	no
`site.site_hourly_cap`	integer	no
`site.revoked_at`	string (date-time) \| null	no
`site.created_at`	string (date-time)	no
`site.updated_at`	string (date-time)	no
`site.consent_version`	string \| null	no	Versión vigente del texto de consentimiento (cadena decimal, p. ej. "2"); null mientras el sitio no tenga texto.
`site.consent_text`	string \| null	no
`site.consent_sha256`	string \| null	no	sha256 en hexadecimal minúscula de los bytes de `consent_text`, calculado por el servidor.

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

json

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

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

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

json

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

`429` — ApiKeyRateLimited

json

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

Revocar la clave de un sitio de click-to-call

http

DELETE /v1/click-to-call/sites/{id}

Revoca la clave (idempotente; una segunda llamada devuelve el mismo sitio revocado). Disponible incluso con click_to_call_enabled apagado: una clave siempre se puede matar. Las solicitudes ya recibidas son evidencia y nunca se borran.

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`

El sitio revocado.

Campo	Tipo	Obligatorio	Descripción
`site`	object (ClickToCallSite)	sí	Un sitio de click-to-call tal como lo ve la consola. Nunca lleva la clave.
`site.id`	string (uuid)	no
`site.campaign_id`	string (uuid)	no
`site.label`	string	no
`site.allow_immediate`	boolean	no
`site.allow_scheduled`	boolean	no
`site.tenant_daily_cap`	integer	no
`site.number_daily_cap`	integer	no
`site.site_hourly_cap`	integer	no
`site.revoked_at`	string (date-time) \| null	no
`site.created_at`	string (date-time)	no
`site.updated_at`	string (date-time)	no
`site.consent_version`	string \| null	no	Versión vigente del texto de consentimiento (cadena decimal, p. ej. "2"); null mientras el sitio no tenga texto.
`site.consent_text`	string \| null	no
`site.consent_sha256`	string \| null	no	sha256 en hexadecimal minúscula de los bytes de `consent_text`, calculado por el servidor.

`401` — Unauthorized

json

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

`403` — Forbidden

json

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

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

`429` — ApiKeyRateLimited

json

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

Leer la configuración del formulario de solicitud de llamada

http

GET /v1/public/call-request-config

Lo que el formulario del visitante necesita para dibujarse. Nada de las interioridades del tenant (ni campaña ni topes). Lleva el texto de consentimiento VIGENTE con su consent_version y su consent_sha256 (sha256 de los bytes del texto, calculado por el servidor): el formulario debe mostrar exactamente ese texto y devolver la versión y el hash en POST /v1/public/call-requests.

Respuestas

`200`

La configuración pública del sitio.

Campo	Tipo	Obligatorio	Descripción
`config`	object (ClickToCallPublicConfig)	sí
`config.site_id`	string (uuid)	no
`config.label`	string	no
`config.allow_immediate`	boolean	no
`config.allow_scheduled`	boolean	no
`config.consent_version`	string \| null	no	Versión vigente del texto de consentimiento (cadena decimal, p. ej. "2"); null mientras el sitio no tenga texto.
`config.consent_text`	string \| null	no
`config.consent_sha256`	string \| null	no	sha256 en hexadecimal minúscula de los bytes de `consent_text`, calculado por el servidor.

`401` — Unauthorized

json

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

`403` — Forbidden

json

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

`404`

El carril está apagado (techo de la celda cerrado o click_to_call_enabled del tenant apagado). Idéntico byte a byte a cualquier ruta desconocida.

Dejar una solicitud de llamada

http

POST /v1/public/call-requests

SOLO INSERCIÓN. Registra la declaración del visitante (nunca un consentimiento) y responde 202 {request_id}: la respuesta no dice nada sobre si el número pertenece a un cliente del tenant.

La consent_text_version y el consent_text_sha256 deben ser los VIGENTES del sitio (el formulario los obtuvo de GET /v1/public/call-request-config); de lo contrario la respuesta es 409 consent_version_mismatch y no se escribe nada (fail-closed). Un sitio sin texto de consentimiento configurado responde siempre 409. La versión aceptada se almacena con la solicitud.

El volumen está acotado por topes DURADEROS contados en la transacción de la inserción (tenant_daily_cap, number_daily_cap y site_hourly_cap del sitio, ventanas móviles) y por un cubo de tasa por sitio. Cada uno responde el mismo 429, no escribe nada y no lleva Retry-After. Si los topes no se pueden leer, la respuesta es 503 y no se escribe nada. Un captcha_token opcional lo comprueba el proveedor configurado (ninguno por defecto).

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`mode`	`immediate` · `scheduled`	sí
`scheduled_for`	string (date-time)	no	Obligatorio cuando `mode` es `scheduled`, prohibido cuando es `immediate`.
`phone`	string	sí	E.164 normalizado, p. ej. +13125550100.
`consent_text_version`	string	sí	La `consent_version` que el formulario obtuvo de la configuración pública.
`consent_text_sha256`	string	sí	El `consent_sha256` que el formulario obtuvo de la configuración pública.
`consent_checked`	boolean	sí	La declaración del visitante. Debe ser `true`: `false` responde `422 consent_not_checked` y no se escribe nada.
`captcha_token`	string	no	Opcional. Lo comprueba el proveedor de captcha cuando la celda configura uno (ninguno por defecto); un token rechazado responde `403 captcha_failed`.

Respuestas

`202`

Recibida.

Campo	Tipo	Obligatorio	Descripción
`request_id`	string (uuid)	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

json

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

`403` — Forbidden

json

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

`404`

El carril está apagado (techo de la celda cerrado o click_to_call_enabled del tenant apagado). Idéntico byte a byte a cualquier ruta desconocida; no se escribe nada.

`409`

consent_version_mismatch: la versión o el hash no coincide con el texto de consentimiento vigente del sitio. No se escribe nada; recarga la configuración del formulario.

`422`

consent_not_checked: la casilla de consentimiento se envió sin marcar (consent_checked: false); una solicitud que dice que el visitante no lo declaró no es una solicitud de llamada. También unprocessable para un modo que el sitio no permite. No se escribe nada.

`429`

Se alcanzó un tope de volumen o el cubo por sitio. Mismo cuerpo para todos los topes; sin Retry-After; no se escribe nada.

`503`

No se pudieron leer los topes (o el proveedor de captcha), así que la solicitud no se admite. No se escribe nada.

Click to call ​

Endpoints ​

Listar los sitios de click-to-call del tenant ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

429 — ApiKeyRateLimited ​

Emitir una clave de sitio de click-to-call ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

429 — ApiKeyRateLimited ​

Leer un sitio de click-to-call ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Configurar un sitio de click-to-call ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Revocar la clave de un sitio de click-to-call ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Leer la configuración del formulario de solicitud de llamada ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

404 ​

Dejar una solicitud de llamada ​

202 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 ​

409 ​

422 ​

429 ​

503 ​

Click to call

Endpoints

Listar los sitios de click-to-call del tenant

`200`

`401` — Unauthorized

`403` — Forbidden

`429` — ApiKeyRateLimited

Emitir una clave de sitio de click-to-call

`201`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`429` — ApiKeyRateLimited

Leer un sitio de click-to-call

`200`

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`429` — ApiKeyRateLimited

Configurar un sitio de click-to-call

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited

Revocar la clave de un sitio de click-to-call

`200`

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`429` — ApiKeyRateLimited

Leer la configuración del formulario de solicitud de llamada

`200`

`401` — Unauthorized

`403` — Forbidden

`404`

Dejar una solicitud de llamada

`202`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404`

`409`

`422`

`429`

`503`