Filtros de segmento

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.

Filtros de segmentación guardados (los criterios de GET /v1/debts con un nombre), versionados sólo-anexado por tenant. Detrás del indicador debt_segmentation_enabled (ADR #221).

Endpoints

Método	Ruta	Resumen
GET	/v1/segment-filters	Los filtros de segmentación guardados del tenant, cada uno con su versión vigente
POST	/v1/segment-filters	Crear un filtro guardado (versión 1)
GET	/v1/segment-filters/{id}	Un filtro guardado, en su versión vigente
PATCH	/v1/segment-filters/{id}	Renombrar un filtro, o editar sus criterios en una versión NUEVA
DELETE	/v1/segment-filters/{id}	Archivar un filtro guardado
POST	/v1/segment-filters/{id}/to-list	Congelar en una lista lo que un filtro guardado selecciona AHORA
POST	/v1/segment-filters/to-list	Congelar en una lista lo que seleccionan AHORA unos criterios en línea

Los filtros de segmentación guardados del tenant, cada uno con su versión vigente

GET /v1/segment-filters

Detrás del indicador debt_segmentation_enabled: con él apagado (el valor por defecto) toda ruta /v1/segment-filters responde 404, sea quien sea el llamante. Por nombre, los vigentes; ?include_archived=true añade los archivados. Cada filtro viene con su versión VIGENTE. Tope de 2 000.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
include_archived	query	boolean	no

Respuestas

200

Los filtros.

Campo	Tipo	Obligatorio	Descripción
segment_filters	arreglo de SegmentFilter	sí
segment_filters[].id	string (uuid)	sí
segment_filters[].tenant_id	string (uuid)	no
segment_filters[].name	string	sí
segment_filters[].archived	boolean	sí
segment_filters[].version	integer	sí	La versión vigente.
segment_filters[].criteria	any	sí	Los criterios de la versión vigente, en forma canónica (listas ordenadas, sin repetidos).
segment_filters[].version_created_at	string (date-time)	no
segment_filters[].created_at	string (date-time)	no
segment_filters[].updated_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.

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

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

Crear un filtro guardado (versión 1)

POST /v1/segment-filters

name va sin espacios en los extremos, no en blanco, con un máximo de 200 caracteres y único entre los filtros VIGENTES del tenant (409). criteria pasa por Dialer.Debts.Segment (ADR #221): un vocabulario cerrado, un valor fuera de él da 400, y phone, consumer_ref, external_ref y debtor_name se rechazan por su nombre. El servidor guarda la forma canónica (listas ordenadas, sin repetidos). Un objeto vacío es válido: toda la cartera. Un tenant tiene como máximo 500 filtros vigentes (422). Requiere el alcance de tenant (403 para un token de agente). Con el indicador apagado, 404.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
name	string	sí
criteria	object (SegmentCriteria)	sí	Criterios que aceptan las escrituras de segment-filter y las rutas to-list (Dialer.Debts.Segment, ADR #221). Un vocabulario cerrado, combinado con AND; un objeto vacío es toda la cartera. state, debt_type, us_state y regf_status admiten un valor o una lista (siempre se devuelven como lista ordenada sin repetidos). phone, consumer_ref, external_ref y debtor_name se rechazan por su nombre.
criteria.campaign_id	string (uuid)	no
criteria.state	open · in_collection · promise_to_pay · paid · settled · disputed · closed | arreglo de open · in_collection · promise_to_pay · paid · settled · disputed · closed	no
criteria.debt_type	other · student_loan | arreglo de other · student_loan	no
criteria.us_state	string | arreglo de string	no
criteria.regf_status	ok · blocked_7in7 · blocked_post_contact · undecidable | arreglo de ok · blocked_7in7 · blocked_post_contact · undecidable	no	Criterio de ADR #221: elegibilidad Reg F vigente derivada por el servidor.
criteria.min_amount_cents	integer	no
criteria.max_amount_cents	integer	no
criteria.min_age_days	integer	no	Criterio de ADR #221: en mora durante al menos este número de días (debts.delinquent_since frente a hoy); una deuda sin delinquent_since nunca coincide.
criteria.max_age_days	integer	no	Criterio de ADR #221: en mora durante como máximo este número de días (debts.delinquent_since frente a hoy); una deuda sin delinquent_since nunca coincide. Se rechaza un min_age_days superior a max_age_days.

{
  "name": "Texas student loans over 500 USD",
  "criteria": {
    "debt_type": [
      "student_loan"
    ],
    "us_state": [
      "TX"
    ],
    "min_amount_cents": 50000
  }
}

Respuestas

201

El filtro, en la versión 1.

Campo	Tipo	Obligatorio	Descripción
segment_filter	object (SegmentFilter)	sí	Un filtro guardado: su cabecera y su versión VIGENTE.
segment_filter.id	string (uuid)	sí
segment_filter.tenant_id	string (uuid)	no
segment_filter.name	string	sí
segment_filter.archived	boolean	sí
segment_filter.version	integer	sí	La versión vigente.
segment_filter.criteria	any	sí	Los criterios de la versión vigente, en forma canónica (listas ordenadas, sin repetidos).
segment_filter.version_created_at	string (date-time)	no
segment_filter.created_at	string (date-time)	no
segment_filter.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).

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

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

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

422 — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

Un filtro guardado, en su versión vigente

GET /v1/segment-filters/{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 filtro (también los archivados, marcados con archived).

Campo	Tipo	Obligatorio	Descripción
segment_filter	object (SegmentFilter)	sí	Un filtro guardado: su cabecera y su versión VIGENTE.
segment_filter.id	string (uuid)	sí
segment_filter.tenant_id	string (uuid)	no
segment_filter.name	string	sí
segment_filter.archived	boolean	sí
segment_filter.version	integer	sí	La versión vigente.
segment_filter.criteria	any	sí	Los criterios de la versión vigente, en forma canónica (listas ordenadas, sin repetidos).
segment_filter.version_created_at	string (date-time)	no
segment_filter.created_at	string (date-time)	no
segment_filter.updated_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.

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

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

Renombrar un filtro, o editar sus criterios en una versión NUEVA

PATCH /v1/segment-filters/{id}

Envía al menos uno de name, criteria. Un cambio de nombre modifica sólo la cabecera. Cambiar criteria añade la versión n+1 y deja la versión n exactamente como estaba: una lista materializada a partir de ella puede haberla usado. criteria REEMPLAZA a los vigentes, no se fusionan. Una edición que no cambia nada no escribe ninguna versión. base_version es opcional y, si se envía, debe ser la versión vigente; si no, 409 y no se escribe nada, de modo que dos personas que editan el mismo filtro no se sobrescriben sin enterarse. Un filtro archivado no se puede editar (409); un filtro tiene como máximo 1 000 versiones (422). Requiere el alcance de tenant. Con el indicador apagado, 404.

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
name	string	no
criteria	object (SegmentCriteria)	no	Criterios que aceptan las escrituras de segment-filter y las rutas to-list (Dialer.Debts.Segment, ADR #221). Un vocabulario cerrado, combinado con AND; un objeto vacío es toda la cartera. state, debt_type, us_state y regf_status admiten un valor o una lista (siempre se devuelven como lista ordenada sin repetidos). phone, consumer_ref, external_ref y debtor_name se rechazan por su nombre.
criteria.campaign_id	string (uuid)	no
criteria.state	open · in_collection · promise_to_pay · paid · settled · disputed · closed | arreglo de open · in_collection · promise_to_pay · paid · settled · disputed · closed	no
criteria.debt_type	other · student_loan | arreglo de other · student_loan	no
criteria.us_state	string | arreglo de string	no
criteria.regf_status	ok · blocked_7in7 · blocked_post_contact · undecidable | arreglo de ok · blocked_7in7 · blocked_post_contact · undecidable	no	Criterio de ADR #221: elegibilidad Reg F vigente derivada por el servidor.
criteria.min_amount_cents	integer	no
criteria.max_amount_cents	integer	no
criteria.min_age_days	integer	no	Criterio de ADR #221: en mora durante al menos este número de días (debts.delinquent_since frente a hoy); una deuda sin delinquent_since nunca coincide.
criteria.max_age_days	integer	no	Criterio de ADR #221: en mora durante como máximo este número de días (debts.delinquent_since frente a hoy); una deuda sin delinquent_since nunca coincide. Se rechaza un min_age_days superior a max_age_days.
base_version	integer	no

{
  "base_version": 1,
  "criteria": {
    "us_state": [
      "TX",
      "NY"
    ]
  }
}

Respuestas

200

El filtro, en su versión vigente tras la edición.

Campo	Tipo	Obligatorio	Descripción
segment_filter	object (SegmentFilter)	sí	Un filtro guardado: su cabecera y su versión VIGENTE.
segment_filter.id	string (uuid)	sí
segment_filter.tenant_id	string (uuid)	no
segment_filter.name	string	sí
segment_filter.archived	boolean	sí
segment_filter.version	integer	sí	La versión vigente.
segment_filter.criteria	any	sí	Los criterios de la versión vigente, en forma canónica (listas ordenadas, sin repetidos).
segment_filter.version_created_at	string (date-time)	no
segment_filter.created_at	string (date-time)	no
segment_filter.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).

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

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

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

422 — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

Archivar un filtro guardado

DELETE /v1/segment-filters/{id}

Los filtros nunca se borran: una versión a partir de la cual se materializó una lista es evidencia. Archivar libera el nombre para un filtro nuevo y saca el filtro de la lista por defecto; ya no se puede editar. Idempotente. Requiere el alcance de tenant. Con el indicador apagado, 404.

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

204

El filtro está archivado.

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

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

Congelar en una lista lo que un filtro guardado selecciona AHORA

POST /v1/segment-filters/{id}/to-list

Una FOTO (ADR #221, core#1687): las deudas que selecciona la versión MÁS RECIENTE del filtro en este momento se colocan en la lista, y la lista no sigue al filtro después. Solo entran las deudas del tenant; los criterios de Reg F usan la lógica real de Reg F. Idempotente por (list_id, debt_id): repetir la solicitud no añade nada (added: 0) y aun así registra su propia fila de evidencia.

El destino es EXACTAMENTE UNO de list_id (una lista existente del tenant: 200) o new_list_name (una lista creada en la misma solicitud, con nombre único: 201); ninguno o ambos es un 400.

El tope de catálogo del tenant debt_segment_max_rows (por defecto 10 000, nunca por encima del techo de candidatos de Reg F) limita cuántas deudas se escriben; alcanzarlo se indica con truncated: true en la respuesta, nunca en silencio, y entonces la foto cubre solo los candidatos más recientes. Un tope de 0 o menos es 422 y no escribe nada. Un filtro archivado, o una lista list_id archivada, es 409. Un list_id o un filtro que no sea del tenant, o que no sea un UUID, es 404. Una solicitud que falla no deja ninguna lista vacía. Requiere el alcance de tenant (403 para un token de agente). Detrás del indicador debt_segmentation_enabled: apagado, 404 y no se lee ni se escribe nada.

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
list_id	string (uuid)	no
new_list_name	string	no

{
  "new_list_name": "Texas student loans",
  "July photo": null
}

Respuestas

200

La foto se escribió en la lista existente.

Campo	Tipo	Obligatorio	Descripción
segment_materialization	object (SegmentMaterialization)	sí	La fila de evidencia de una foto (solo anexa). Las deudas matched fueron seleccionadas (como máximo max_rows), added de ellas eran NUEVAS en la lista y truncated indica que el tope de catálogo recortó el resultado.
segment_materialization.id	string (uuid)	sí
segment_materialization.tenant_id	string (uuid)	no
segment_materialization.list_id	string (uuid)	sí
segment_materialization.filter_id	string (uuid) | null	sí	El filtro guardado, o null cuando los criterios llegaron en línea.
segment_materialization.filter_version	integer | null	sí	La versión del filtro que se usó, o null cuando fue en línea.
segment_materialization.criteria	any	sí	Los criterios que se evaluaron, en forma canónica.
segment_materialization.max_rows	integer	sí	El tope vigente para esta foto.
segment_materialization.matched	integer	sí
segment_materialization.added	integer	sí
segment_materialization.truncated	boolean	sí
segment_materialization.requested_at	string (date-time)	no
debt_list	any	sí	La lista de destino, con su tamaño contado después de la foto.

201

La lista se creó y la foto se escribió en ella.

Campo	Tipo	Obligatorio	Descripción
segment_materialization	object (SegmentMaterialization)	sí	La fila de evidencia de una foto (solo anexa). Las deudas matched fueron seleccionadas (como máximo max_rows), added de ellas eran NUEVAS en la lista y truncated indica que el tope de catálogo recortó el resultado.
segment_materialization.id	string (uuid)	sí
segment_materialization.tenant_id	string (uuid)	no
segment_materialization.list_id	string (uuid)	sí
segment_materialization.filter_id	string (uuid) | null	sí	El filtro guardado, o null cuando los criterios llegaron en línea.
segment_materialization.filter_version	integer | null	sí	La versión del filtro que se usó, o null cuando fue en línea.
segment_materialization.criteria	any	sí	Los criterios que se evaluaron, en forma canónica.
segment_materialization.max_rows	integer	sí	El tope vigente para esta foto.
segment_materialization.matched	integer	sí
segment_materialization.added	integer	sí
segment_materialization.truncated	boolean	sí
segment_materialization.requested_at	string (date-time)	no
debt_list	any	sí	La lista de destino, con su tamaño contado después de la foto.

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

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

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

422 — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

Congelar en una lista lo que seleccionan AHORA unos criterios en línea

POST /v1/segment-filters/to-list

La misma foto que POST /v1/segment-filters/{id}/to-list, con los criterios en el cuerpo en lugar de un filtro guardado (la fila de evidencia entonces no tiene filter_id). criteria pasa por Dialer.Debts.Segment: un valor fuera del vocabulario cerrado, una clave de PII o algo que no sea un objeto es un 400, y no se escribe nada. Un objeto vacío es la cartera completa, aun así acotada por el tope. Destino, tope, alcance e indicador como en la forma con filtro guardado.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
criteria	object (SegmentCriteria)	sí	Criterios que aceptan las escrituras de segment-filter y las rutas to-list (Dialer.Debts.Segment, ADR #221). Un vocabulario cerrado, combinado con AND; un objeto vacío es toda la cartera. state, debt_type, us_state y regf_status admiten un valor o una lista (siempre se devuelven como lista ordenada sin repetidos). phone, consumer_ref, external_ref y debtor_name se rechazan por su nombre.
criteria.campaign_id	string (uuid)	no
criteria.state	open · in_collection · promise_to_pay · paid · settled · disputed · closed | arreglo de open · in_collection · promise_to_pay · paid · settled · disputed · closed	no
criteria.debt_type	other · student_loan | arreglo de other · student_loan	no
criteria.us_state	string | arreglo de string	no
criteria.regf_status	ok · blocked_7in7 · blocked_post_contact · undecidable | arreglo de ok · blocked_7in7 · blocked_post_contact · undecidable	no	Criterio de ADR #221: elegibilidad Reg F vigente derivada por el servidor.
criteria.min_amount_cents	integer	no
criteria.max_amount_cents	integer	no
criteria.min_age_days	integer	no	Criterio de ADR #221: en mora durante al menos este número de días (debts.delinquent_since frente a hoy); una deuda sin delinquent_since nunca coincide.
criteria.max_age_days	integer	no	Criterio de ADR #221: en mora durante como máximo este número de días (debts.delinquent_since frente a hoy); una deuda sin delinquent_since nunca coincide. Se rechaza un min_age_days superior a max_age_days.
list_id	string (uuid)	no
new_list_name	string	no

{
  "criteria": {
    "debt_type": [
      "student_loan"
    ],
    "us_state": [
      "TX"
    ]
  },
  "list_id": "6f1c2a52-3b52-4b3d-9d57-0e5c6a8f1a10"
}

Respuestas

200

La foto se escribió en la lista existente.

Campo	Tipo	Obligatorio	Descripción
segment_materialization	object (SegmentMaterialization)	sí	La fila de evidencia de una foto (solo anexa). Las deudas matched fueron seleccionadas (como máximo max_rows), added de ellas eran NUEVAS en la lista y truncated indica que el tope de catálogo recortó el resultado.
segment_materialization.id	string (uuid)	sí
segment_materialization.tenant_id	string (uuid)	no
segment_materialization.list_id	string (uuid)	sí
segment_materialization.filter_id	string (uuid) | null	sí	El filtro guardado, o null cuando los criterios llegaron en línea.
segment_materialization.filter_version	integer | null	sí	La versión del filtro que se usó, o null cuando fue en línea.
segment_materialization.criteria	any	sí	Los criterios que se evaluaron, en forma canónica.
segment_materialization.max_rows	integer	sí	El tope vigente para esta foto.
segment_materialization.matched	integer	sí
segment_materialization.added	integer	sí
segment_materialization.truncated	boolean	sí
segment_materialization.requested_at	string (date-time)	no
debt_list	any	sí	La lista de destino, con su tamaño contado después de la foto.

201

La lista se creó y la foto se escribió en ella.

Campo	Tipo	Obligatorio	Descripción
segment_materialization	object (SegmentMaterialization)	sí	La fila de evidencia de una foto (solo anexa). Las deudas matched fueron seleccionadas (como máximo max_rows), added de ellas eran NUEVAS en la lista y truncated indica que el tope de catálogo recortó el resultado.
segment_materialization.id	string (uuid)	sí
segment_materialization.tenant_id	string (uuid)	no
segment_materialization.list_id	string (uuid)	sí
segment_materialization.filter_id	string (uuid) | null	sí	El filtro guardado, o null cuando los criterios llegaron en línea.
segment_materialization.filter_version	integer | null	sí	La versión del filtro que se usó, o null cuando fue en línea.
segment_materialization.criteria	any	sí	Los criterios que se evaluaron, en forma canónica.
segment_materialization.max_rows	integer	sí	El tope vigente para esta foto.
segment_materialization.matched	integer	sí
segment_materialization.added	integer	sí
segment_materialization.truncated	boolean	sí
segment_materialization.requested_at	string (date-time)	no
debt_list	any	sí	La lista de destino, con su tamaño contado después de la foto.

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

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

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

422 — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}