Plantillas de SMS

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.

Plantillas de SMS por tenant con variables tipadas, aprobación y el ajuste «solo plantillas».

Endpoints

Método	Ruta	Resumen
`GET`	`/v1/sms-templates`	Versiones de plantillas de SMS
`POST`	`/v1/sms-templates`	Crear un borrador (la siguiente versión cuando `name` ya existe)
`GET`	`/v1/sms-templates/{id}`	Una versión de plantilla
`PATCH`	`/v1/sms-templates/{id}`	Editar un borrador (`body` / `variables`)
`POST`	`/v1/sms-templates/{id}/approve`	Aprobar un borrador (solo account_admin)
`POST`	`/v1/sms-templates/{id}/retire`	Retirar una versión (un borrador se descarta retirándolo)
`GET`	`/v1/sms/template-policy`	El ajuste «solo plantillas» del tenant
`PUT`	`/v1/sms/template-policy`	Activar o desactivar «solo plantillas» (solo account_admin)

Versiones de plantillas de SMS

http

GET /v1/sms-templates

Todas las versiones de todas las plantillas del tenant, la versión más reciente primero por name.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`status`	query	`draft` · `approved` · `retired`	no
`name`	query	string	no

Respuestas

`200`

Las versiones de plantilla del tenant.

Campo	Tipo	Obligatorio	Descripción
`sms_templates`	arreglo de SmsTemplate	sí
`sms_templates[].id`	string (uuid)	no
`sms_templates[].name`	string	no
`sms_templates[].version`	integer	no
`sms_templates[].status`	`draft` · `approved` · `retired`	no
`sms_templates[].body`	string	no
`sms_templates[].variables`	arreglo de SmsTemplateVariable	no
`sms_templates[].variables[].name`	string	sí
`sms_templates[].variables[].type`	`string` · `number` · `date`	sí
`sms_templates[].variables[].required`	boolean	no	Una variable opcional que no se envía se renderiza vacía.
`sms_templates[].approved_by`	string (uuid) \| null	no
`sms_templates[].approved_at`	string (date-time) \| null	no
`sms_templates[].retired_at`	string (date-time) \| null	no
`sms_templates[].created_at`	string (date-time)	no
`sms_templates[].updated_at`	string (date-time)	no

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

Crear un borrador (la siguiente versión cuando `name` ya existe)

http

POST /v1/sms-templates

El cuerpo usa marcadores {{variable}}; cada marcador debe declararse en variables y cada variable declarada debe usarse. El texto estático debe llevar ya el aviso de baja y ningún término prohibido por los carriers (las mismas reglas que aplica el envío). Tipos de variable: string (de 1 a 160 caracteres, sin caracteres de control), number, date (ISO-8601). Un name que ya tiene versiones abre la siguiente versión como un borrador nuevo: una versión aprobada nunca se edita. tenant_id, version y status nunca son entrada del cuerpo.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`name`	string	sí	Familia de plantilla; un nombre existente abre su siguiente versión.
`body`	string	sí
`variables`	arreglo de SmsTemplateVariable	no
`variables[].name`	string	sí
`variables[].type`	`string` · `number` · `date`	sí
`variables[].required`	boolean	no	Una variable opcional que no se envía se renderiza vacía.

json

{
  "name": "payment-reminder",
  "body": "Hi {{first_name}}, your balance of {{amount}} is due {{due_date}}. Reply STOP to opt out.",
  "variables": [
    {
      "name": "first_name",
      "type": "string"
    },
    {
      "name": "amount",
      "type": "number"
    },
    {
      "name": "due_date",
      "type": "date"
    }
  ]
}

Respuestas

`201`

El nuevo borrador.

Campo	Tipo	Obligatorio	Descripción
`sms_template`	object (SmsTemplate)	sí
`sms_template.id`	string (uuid)	no
`sms_template.name`	string	no
`sms_template.version`	integer	no
`sms_template.status`	`draft` · `approved` · `retired`	no
`sms_template.body`	string	no
`sms_template.variables`	arreglo de SmsTemplateVariable	no
`sms_template.variables[].name`	string	sí
`sms_template.variables[].type`	`string` · `number` · `date`	sí
`sms_template.variables[].required`	boolean	no	Una variable opcional que no se envía se renderiza vacía.
`sms_template.approved_by`	string (uuid) \| null	no
`sms_template.approved_at`	string (date-time) \| null	no
`sms_template.retired_at`	string (date-time) \| null	no
`sms_template.created_at`	string (date-time)	no
`sms_template.updated_at`	string (date-time)	no

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

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

Una versión de plantilla

http

GET /v1/sms-templates/{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`

La versión.

Campo	Tipo	Obligatorio	Descripción
`sms_template`	object (SmsTemplate)	sí
`sms_template.id`	string (uuid)	no
`sms_template.name`	string	no
`sms_template.version`	integer	no
`sms_template.status`	`draft` · `approved` · `retired`	no
`sms_template.body`	string	no
`sms_template.variables`	arreglo de SmsTemplateVariable	no
`sms_template.variables[].name`	string	sí
`sms_template.variables[].type`	`string` · `number` · `date`	sí
`sms_template.variables[].required`	boolean	no	Una variable opcional que no se envía se renderiza vacía.
`sms_template.approved_by`	string (uuid) \| null	no
`sms_template.approved_at`	string (date-time) \| null	no
`sms_template.retired_at`	string (date-time) \| null	no
`sms_template.created_at`	string (date-time)	no
`sms_template.updated_at`	string (date-time)	no

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

Editar un borrador (`body` / `variables`)

http

PATCH /v1/sms-templates/{id}

Solo un draft puede cambiar; una versión aprobada o retirada responde 409 (crea una versión nueva en su lugar).

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
`body`	string	no
`variables`	arreglo de SmsTemplateVariable	no
`variables[].name`	string	sí
`variables[].type`	`string` · `number` · `date`	sí
`variables[].required`	boolean	no	Una variable opcional que no se envía se renderiza vacía.

Respuestas

`200`

El borrador actualizado.

Campo	Tipo	Obligatorio	Descripción
`sms_template`	object (SmsTemplate)	sí
`sms_template.id`	string (uuid)	no
`sms_template.name`	string	no
`sms_template.version`	integer	no
`sms_template.status`	`draft` · `approved` · `retired`	no
`sms_template.body`	string	no
`sms_template.variables`	arreglo de SmsTemplateVariable	no
`sms_template.variables[].name`	string	sí
`sms_template.variables[].type`	`string` · `number` · `date`	sí
`sms_template.variables[].required`	boolean	no	Una variable opcional que no se envía se renderiza vacía.
`sms_template.approved_by`	string (uuid) \| null	no
`sms_template.approved_at`	string (date-time) \| null	no
`sms_template.retired_at`	string (date-time) \| null	no
`sms_template.created_at`	string (date-time)	no
`sms_template.updated_at`	string (date-time)	no

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

Aprobar un borrador (solo account_admin)

http

POST /v1/sms-templates/{id}/approve

Aprueba el borrador exactamente como está y registra quién y cuándo (approved_by, approved_at). Solo un login account_admin puede aprobar: un member o una clave de máquina dd_ recibe 403. La base de datos también lo hace cumplir. Una versión que no es un borrador responde 409.

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`

La versión aprobada.

Campo	Tipo	Obligatorio	Descripción
`sms_template`	object (SmsTemplate)	sí
`sms_template.id`	string (uuid)	no
`sms_template.name`	string	no
`sms_template.version`	integer	no
`sms_template.status`	`draft` · `approved` · `retired`	no
`sms_template.body`	string	no
`sms_template.variables`	arreglo de SmsTemplateVariable	no
`sms_template.variables[].name`	string	sí
`sms_template.variables[].type`	`string` · `number` · `date`	sí
`sms_template.variables[].required`	boolean	no	Una variable opcional que no se envía se renderiza vacía.
`sms_template.approved_by`	string (uuid) \| null	no
`sms_template.approved_at`	string (date-time) \| null	no
`sms_template.retired_at`	string (date-time) \| null	no
`sms_template.created_at`	string (date-time)	no
`sms_template.updated_at`	string (date-time)	no

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

Retirar una versión (un borrador se descarta retirándolo)

http

POST /v1/sms-templates/{id}/retire

Terminal. Una versión retirada ya no se puede enviar; una ya retirada responde 409.

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`

La versión retirada.

Campo	Tipo	Obligatorio	Descripción
`sms_template`	object (SmsTemplate)	sí
`sms_template.id`	string (uuid)	no
`sms_template.name`	string	no
`sms_template.version`	integer	no
`sms_template.status`	`draft` · `approved` · `retired`	no
`sms_template.body`	string	no
`sms_template.variables`	arreglo de SmsTemplateVariable	no
`sms_template.variables[].name`	string	sí
`sms_template.variables[].type`	`string` · `number` · `date`	sí
`sms_template.variables[].required`	boolean	no	Una variable opcional que no se envía se renderiza vacía.
`sms_template.approved_by`	string (uuid) \| null	no
`sms_template.approved_at`	string (date-time) \| null	no
`sms_template.retired_at`	string (date-time) \| null	no
`sms_template.created_at`	string (date-time)	no
`sms_template.updated_at`	string (date-time)	no

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

El ajuste «solo plantillas» del tenant

http

GET /v1/sms/template-policy

Desactivado (false) hasta que un account_admin lo activa.

Respuestas

`200`

El ajuste vigente.

Campo	Tipo	Obligatorio	Descripción
`sms_template_policy`	object (SmsTemplatePolicy)	sí
`sms_template_policy.templates_only`	boolean	sí

`401` — Unauthorized

json

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

`403` — Forbidden

json

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

Activar o desactivar «solo plantillas» (solo account_admin)

http

PUT /v1/sms/template-policy

Con él activado, POST /v1/sms/messages rechaza el texto libre (422 sms_templates_only) y solo se envían plantillas aprobadas. Cada cambio es una fila del libro de solo anexar; un member o una clave de máquina dd_ recibe 403. El SMS de campaña (sms_body) no queda cubierto por este ajuste.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`templates_only`	boolean	sí

json

{
  "templates_only": true
}

Respuestas

`200`

El ajuste almacenado.

Campo	Tipo	Obligatorio	Descripción
`sms_template_policy`	object (SmsTemplatePolicy)	sí
`sms_template_policy.templates_only`	boolean	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"
  }
}

Plantillas de SMS ​

Endpoints ​

Versiones de plantillas de SMS ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

429 — ApiKeyRateLimited ​

Crear un borrador (la siguiente versión cuando name ya existe) ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Una versión de plantilla ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Editar un borrador (body / variables) ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Aprobar un borrador (solo account_admin) ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Retirar una versión (un borrador se descarta retirándolo) ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

El ajuste «solo plantillas» del tenant ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

Activar o desactivar «solo plantillas» (solo account_admin) ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

Plantillas de SMS

Endpoints

Versiones de plantillas de SMS

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`429` — ApiKeyRateLimited

Crear un borrador (la siguiente versión cuando `name` ya existe)

`201`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`409` — Conflict

`429` — ApiKeyRateLimited

Una versión de plantilla

`200`

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`429` — ApiKeyRateLimited

Editar un borrador (`body` / `variables`)

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited

Aprobar un borrador (solo account_admin)

`200`

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited

Retirar una versión (un borrador se descarta retirándolo)

`200`

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited

El ajuste «solo plantillas» del tenant

`200`

`401` — Unauthorized

`403` — Forbidden

Activar o desactivar «solo plantillas» (solo account_admin)

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden