Appearance
Email
Generado desde
DialerDigital/corecommit0fc18008b3c8— especificaciónopenapi/dialer-v1.yamlv0.134.0. No se edita a mano; consulta Cómo se construye esta referencia. Descargar la especificación OpenAPI.
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.
Direcciones de email de los deudores con su procedencia, el libro de supresiones (lectura) y el libro de emails (lectura).
Endpoints
| Método | Ruta | Resumen |
|---|---|---|
GET | /v1/email/addresses | Las direcciones de email de un contacto |
POST | /v1/email/addresses | Registrar la dirección de email de un deudor CON su procedencia |
GET | /v1/email/addresses/{id} | Una dirección de email con su elegibilidad en el momento de la lectura |
GET | /v1/email/suppressions | El historial de supresión de una dirección (solo lectura) |
GET | /v1/email/messages | Consulta del libro de emails (solo lectura) |
GET | /v1/email/messages/{id} | Vista colapsada de un solo email |
Las direcciones de email de un contacto
http
GET /v1/email/addressesParámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
contact_id | query | string (uuid) | sí |
Respuestas
200
Las direcciones del contacto, de la más antigua a la más reciente, cada una con su elegibilidad en el momento de la lectura.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
email_addresses | arreglo de EmailAddress | sí | |
email_addresses[].id | string (uuid) | sí | |
email_addresses[].contact_id | string (uuid) | sí | |
email_addresses[].address | string | sí | |
email_addresses[].provenance | consumer_replied · consumer_consent · creditor_notice · prior_collector · imported_unverified | sí | |
email_addresses[].provenance_evidence | string | no | |
email_addresses[].notice_sent_at | string (date-time) | null | no | |
email_addresses[].obtained_at | string (date-time) | no | |
email_addresses[].domain_public | boolean | null | no | Derivado del dominio de la dirección; nunca viene de la entrada del cliente. |
email_addresses[].sendable | boolean | sí | |
email_addresses[].ineligible_reason | provenance_not_sendable · evidence_missing · notice_date_missing · notice_period_open · domain_not_public · suppressed · suppression_unreadable | null | sí | |
email_addresses[].created_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"
}
}Registrar la dirección de email de un deudor CON su procedencia
http
POST /v1/email/addressesAlmacena una dirección de un contacto (contact_id) con la procedencia que la hace utilizable o no (12 CFR 1006.6(d)(4)): consumer_replied, consumer_consent, creditor_notice (necesita notice_sent_at; se puede enviar solo 35 días después y para un dominio de correo público) o prior_collector necesitan una provenance_evidence no vacía; imported_unverified se almacena pero NUNCA se puede enviar. sendable / ineligible_reason en la respuesta se calculan en la lectura (procedencia, plazo de aviso, libro de supresiones): ningún campo de la petición puede declarar enviable una dirección. La dirección se normaliza (recortada, en minúsculas); registrar la misma dirección dos veces para un contacto da 409, y un contacto desconocido 400. Requiere el alcance de tenant (una clave dd_ o un login de dashboard).
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
contact_id | string (uuid) | sí | |
address | string (email) | sí | |
provenance | consumer_replied · consumer_consent · creditor_notice · prior_collector · imported_unverified | sí | |
provenance_evidence | string | no | Obligatorio (no vacío) para toda procedencia excepto imported_unverified. |
notice_sent_at | string (date-time) | no | Obligatorio para creditor_notice. |
obtained_at | string (date-time) | sí |
json
{
"contact_id": "00000000-0000-4000-8000-000000000001",
"address": "[email protected]",
"provenance": "consumer_consent",
"provenance_evidence": "Written consent recorded in the account file",
"obtained_at": "2026-10-01T12:00:00Z"
}Respuestas
201
La dirección registrada.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
email_address | object (EmailAddress) | sí | La dirección de email de un deudor con su procedencia. sendable se calcula al leer, nunca se almacena. |
email_address.id | string (uuid) | sí | |
email_address.contact_id | string (uuid) | sí | |
email_address.address | string | sí | |
email_address.provenance | consumer_replied · consumer_consent · creditor_notice · prior_collector · imported_unverified | sí | |
email_address.provenance_evidence | string | no | |
email_address.notice_sent_at | string (date-time) | null | no | |
email_address.obtained_at | string (date-time) | no | |
email_address.domain_public | boolean | null | no | Derivado del dominio de la dirección; nunca viene de la entrada del cliente. |
email_address.sendable | boolean | sí | |
email_address.ineligible_reason | provenance_not_sendable · evidence_missing · notice_date_missing · notice_period_open · domain_not_public · suppressed · suppression_unreadable | null | sí | |
email_address.created_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"
}
}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
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"
}
}Una dirección de email con su elegibilidad en el momento de la lectura
http
GET /v1/email/addresses/{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 dirección.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
email_address | object (EmailAddress) | sí | La dirección de email de un deudor con su procedencia. sendable se calcula al leer, nunca se almacena. |
email_address.id | string (uuid) | sí | |
email_address.contact_id | string (uuid) | sí | |
email_address.address | string | sí | |
email_address.provenance | consumer_replied · consumer_consent · creditor_notice · prior_collector · imported_unverified | sí | |
email_address.provenance_evidence | string | no | |
email_address.notice_sent_at | string (date-time) | null | no | |
email_address.obtained_at | string (date-time) | no | |
email_address.domain_public | boolean | null | no | Derivado del dominio de la dirección; nunca viene de la entrada del cliente. |
email_address.sendable | boolean | sí | |
email_address.ineligible_reason | provenance_not_sendable · evidence_missing · notice_date_missing · notice_period_open · domain_not_public · suppressed · suppression_unreadable | null | sí | |
email_address.created_at | string (date-time) | no |
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"
}
}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
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"
}
}El historial de supresión de una dirección (solo lectura)
http
GET /v1/email/suppressionsEl libro de supresiones de solo anexar de UNA dirección, las más recientes primero, más el status resultante («gana la última fila»: suppressed cuando la fila más reciente es un suppress, si no clear). No hay ruta de escritura: las supresiones las escriben las vías de baja / rebote / queja, y un lift necesita la procedencia propia del consumidor. El resumen de la dirección nunca se devuelve. Una address mal formada da 400.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
address | query | string (email) | sí |
Respuestas
200
Las filas del libro de la dirección (100 como máximo) y su estado actual.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
status | suppressed · clear | sí | |
email_suppressions | arreglo de EmailSuppression | sí | |
email_suppressions[].id | string (uuid) | no | |
email_suppressions[].seq | integer | no | Posición en el libro de la dirección; gana la más alta. |
email_suppressions[].action | suppress · lift | no | |
email_suppressions[].reason | unsubscribe · hard_bounce · complaint · third_party · cease_communication | null | no | Se fija en las filas suppress. |
email_suppressions[].provenance | consumer_consent · consumer_replied | null | no | Se fija en las filas lift. |
email_suppressions[].evidence | string | no | |
email_suppressions[].occurred_at | string (date-time) | no | |
email_suppressions[].recorded_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"
}
}Consulta del libro de emails (solo lectura)
http
GET /v1/email/messagesFILAS del libro (originales Y transiciones de estado; corrects_id las distingue), las más recientes primero, paginadas por keyset como /v1/sms/messages. En las listas, los cuerpos son vistas previas de 40 caracteres. El envío no forma parte de esta superficie: pasa por el Sender con compuertas (campaña send_email), nunca por una ruta.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
direction | query | outbound · inbound | no | |
status | query | queued · sent · delivered · deferred · bounced · complained · failed · received | no | |
campaign_id | query | string (uuid) | no | |
debt_id | query | string (uuid) | no | |
limit | query | integer | no | Tamaño de página (por defecto 100, máximo 1000). |
cursor | query | string | no | Cursor keyset opaco del next_cursor de la página anterior. |
Respuestas
200
Una página de filas del libro mayor.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
email_messages | arreglo de EmailMessage | sí | |
email_messages[].id | string (uuid) | no | |
email_messages[].direction | outbound · inbound | no | |
email_messages[].status | queued · sent · delivered · deferred · bounced · complained · failed · received | no | |
email_messages[].from_address | string | null | no | |
email_messages[].to_address | string | no | |
email_messages[].subject | string | null | no | |
email_messages[].body_preview | string | null | no | |
email_messages[].template_version_id | string (uuid) | null | no | |
email_messages[].region | string | no | |
email_messages[].client_ref | string | no | |
email_messages[].provider_id | string (uuid) | null | no | |
email_messages[].provider_message_id | string | no | |
email_messages[].campaign_id | string (uuid) | null | no | |
email_messages[].debt_id | string (uuid) | null | no | |
email_messages[].contact_id | string (uuid) | null | no | |
email_messages[].occurred_at | string (date-time) | no | |
email_messages[].corrects_id | string (uuid) | null | no | |
email_messages[].recorded_at | string (date-time) | no | |
next_cursor | string | 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 — 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"
}
}Vista colapsada de un solo email
http
GET /v1/email/messages/{id}La identidad del original + el estado VIGENTE, los timestamps por estado, el compliance_snapshot congelado, el subject/body completos y las filas de transitions en orden.
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 vista colapsada.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
email_message | object (EmailMessageView) | sí | La vista COLAPSADA de un solo email: estado vigente, marcas de tiempo por estado, instantánea de cumplimiento congelada, asunto/cuerpo COMPLETOS, transiciones en orden. |
email_message.id | string (uuid) | no | |
email_message.direction | outbound · inbound | no | |
email_message.status | queued · sent · delivered · deferred · bounced · complained · failed · received | no | |
email_message.from_address | string | null | no | |
email_message.to_address | string | no | |
email_message.subject | string | null | no | |
email_message.body | string | null | no | |
email_message.template_version_id | string (uuid) | null | no | |
email_message.region | string | no | |
email_message.client_ref | string | no | |
email_message.provider_id | string (uuid) | null | no | |
email_message.provider_message_id | string | no | |
email_message.campaign_id | string (uuid) | null | no | |
email_message.debt_id | string (uuid) | null | no | |
email_message.contact_id | string (uuid) | null | no | |
email_message.compliance_snapshot | object | null | no | |
email_message.occurred_at | string (date-time) | no | |
email_message.timestamps | object | no | Marcas de tiempo por estado (p. ej. queued, sent, delivered). |
email_message.transitions | arreglo de EmailMessage | no | |
email_message.transitions[].id | string (uuid) | no | |
email_message.transitions[].direction | outbound · inbound | no | |
email_message.transitions[].status | queued · sent · delivered · deferred · bounced · complained · failed · received | no | |
email_message.transitions[].from_address | string | null | no | |
email_message.transitions[].to_address | string | no | |
email_message.transitions[].subject | string | null | no | |
email_message.transitions[].body_preview | string | null | no | |
email_message.transitions[].template_version_id | string (uuid) | null | no | |
email_message.transitions[].region | string | no | |
email_message.transitions[].client_ref | string | no | |
email_message.transitions[].provider_id | string (uuid) | null | no | |
email_message.transitions[].provider_message_id | string | no | |
email_message.transitions[].campaign_id | string (uuid) | null | no | |
email_message.transitions[].debt_id | string (uuid) | null | no | |
email_message.transitions[].contact_id | string (uuid) | null | no | |
email_message.transitions[].occurred_at | string (date-time) | no | |
email_message.transitions[].corrects_id | string (uuid) | null | no | |
email_message.transitions[].recorded_at | string (date-time) | no |
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"
}
}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
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"
}
}