Segmentación de deuda: filtros guardados e instantáneas de lista

English: Debt segmentation.

Los filtros de segmentación guardados le dan a un tenant un conjunto de criterios de deuda con nombre y reutilizable. Sirven cuando una integración necesita repetir la misma selección de portafolio sin volver a enviar los criterios ni guardar en un objeto valores de búsqueda que identifiquen a una persona.

Esta guía separa la API que está en el último release publicado de core de las operaciones de instantánea de lista que hoy solo existen en core@main.

Contrato que usa esta guía

La API disponible de abajo sale del documento OpenAPI de core v0.94.0, el último release publicado cuando se escribió esta página. La sección de instantáneas de lista está marcada aparte porque esas operaciones no están en ese release.

Antes de empezar

Todas las peticiones usan la autenticación bearer normal descrita en Autenticación. La función es de ámbito tenant y está detrás de debt_segmentation_enabled, que viene apagada por defecto.

Con la bandera apagada, toda ruta /v1/segment-filters responde 404 not_found, sea quien sea quien llame. Es intencional: la superficie deshabilitada se comporta como si no existiera y no lee ni escribe filtros guardados.

Las lecturas están disponibles para cualquier llamante autenticado del tenant. Crear, editar, archivar y materializar requieren ámbito tenant; un token de agente recibe 403 forbidden. Un id mal formado, inexistente o que pertenece a otro tenant devuelve el mismo 404 not_found, de modo que la API no revela si otro tenant lo posee.

Criterios

criteria es un objeto con un vocabulario cerrado. Los campos se combinan con AND; los valores de un arreglo dentro de un mismo campo actúan como alternativas. Un objeto vacío selecciona todo el portafolio.

Campo	Forma	Reglas
campaign_id	cadena UUID	Restringe la selección a una campaña.
state	cadena o arreglo	open, in_collection, promise_to_pay, paid, settled, disputed o closed. Los arreglos contienen de 1 a 100 valores.
debt_type	cadena o arreglo	other o student_loan. Los arreglos contienen de 1 a 100 valores.
us_state	cadena o arreglo	Dos letras mayúsculas. Los arreglos contienen de 1 a 100 valores.
min_amount_cents	entero	Cota inferior inclusiva; cero o mayor.
max_amount_cents	entero	Cota superior inclusiva; cero o mayor.

Los campos desconocidos y los valores fuera de la forma permitida devuelven 400 bad_request. Las claves phone, consumer_ref, external_ref y debtor_name se rechazan de forma explícita. Un segmento guardado describe un grupo por atributos; no es una búsqueda almacenada de una persona.

El servidor guarda los criterios en forma canónica: los valores de los arreglos se ordenan y se eliminan los duplicados.

Crear un filtro guardado

POST /v1/segment-filters acepta name y criteria:

curl -X POST "$DIALER_BASE_URL/v1/segment-filters" \
  -H "Authorization: Bearer $DIALER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Texas student loans over 500 USD",
    "criteria": {
      "debt_type": ["student_loan"],
      "us_state": ["TX"],
      "min_amount_cents": 50000
    }
  }'

Una respuesta exitosa es 201 con un objeto segment_filter. Un filtro recién creado empieza en la versión 1.

name se recorta, no puede quedar en blanco y mide como máximo 200 caracteres. Debe ser único entre los filtros no archivados del tenant. El tenant puede tener hasta 500 filtros no archivados.

Leer filtros

Usa GET /v1/segment-filters para listar por nombre los filtros no archivados. Añade ?include_archived=true para incluir los archivados. Cada resultado contiene su versión actual, y la respuesta está limitada a 2,000 filtros.

Usa GET /v1/segment-filters/{id} para un solo filtro. Esta ruta puede devolver un filtro archivado, con archived: true.

Un segment_filter contiene:

Campo	Significado
id	UUID del filtro.
tenant_id	UUID del tenant propietario.
name	Nombre guardado.
archived	Si el filtro fue archivado.
version	Número de la versión actual.
criteria	Criterios actuales en forma canónica.
version_created_at	Momento de creación de la versión actual.
created_at	Momento de creación del filtro.
updated_at	Último cambio de encabezado o de versión.

Actualizar sin pisar a otro editor

PATCH /v1/segment-filters/{id} acepta al menos uno de name o criteria. Al cambiar los criterios, envía como base_version la versión que leíste:

curl -X PATCH "$DIALER_BASE_URL/v1/segment-filters/$FILTER_ID" \
  -H "Authorization: Bearer $DIALER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "base_version": 1,
    "criteria": {"us_state": ["NY", "TX"]}
  }'

criteria reemplaza al objeto actual; no se mezcla con él. Cambiar los criterios añade la siguiente versión y conserva las anteriores. Renombrar cambia solo el encabezado del filtro. Una edición que no cambia nada no añade una versión.

Si base_version no es la actual, el servidor devuelve 409 conflict y no escribe nada. Un filtro archivado también devuelve 409 conflict. Un filtro puede tener hasta 1,000 versiones; al llegar a ese límite se devuelve 422 unprocessable.

Archivar un filtro

DELETE /v1/segment-filters/{id} devuelve 204 y archiva el filtro. No borra físicamente sus versiones. Archivar es idempotente, saca el filtro de la lista por defecto, impide ediciones posteriores y deja su antiguo nombre disponible para un filtro nuevo.

Manejo de errores

Los errores usan el envoltorio estándar:

{
  "error": {
    "code": "bad_request",
    "message": "..."
  }
}

Ramifica por error.code, no por el mensaje legible.

Estado y código	Cuándo esperarlo
400 bad_request	Cuerpo inválido, criterio desconocido, búsqueda de persona rechazada o un valor fuera del vocabulario del criterio.
401 unauthorized	Credencial ausente, desconocida o revocada.
403 forbidden	Una escritura sin ámbito tenant, o un tenant suspendido.
404 not_found	Bandera apagada; id desconocido o mal formado; o un id oculto por el aislamiento de tenants.
409 conflict	Nombre duplicado entre los filtros vivos, base_version desactualizada o un intento de editar un filtro archivado.
422 unprocessable	Se alcanzó el límite de filtros vivos o de versiones por filtro.

Estos fallos cierran en falso: unos criterios inválidos no se convierten en un filtro vacío, en una consulta más amplia ni en una escritura parcial.

Materializar un segmento en una lista de deudas

Disponible en la próxima versión

Las operaciones de esta sección están en el documento OpenAPI de core@main (0.95.0) pero no en el último release publicado, v0.94.0. Todavía no las llames contra el release publicado.

Materializar crea una instantánea: añade a una lista de deudas normal las deudas que coinciden ahora. La lista no sigue los cambios posteriores del filtro ni del portafolio. Pertenecer a la lista no omite las verificaciones de cumplimiento de la marcación.

El contrato actual de core@main prevé dos operaciones:

Método	Ruta	Origen
POST	/v1/segment-filters/{id}/to-list	Última versión de un filtro guardado.
POST	/v1/segment-filters/to-list	criteria en línea en el cuerpo de la petición.

Elige exactamente un destino:

• list_id: añade las coincidencias a una lista existente del tenant; el éxito devuelve 200.
• new_list_name: crea una lista y le añade las coincidencias en la misma petición; el éxito devuelve 201.

En la operación en línea, envía además criteria. Enviar ningún destino o ambos devuelve 400 bad_request.

La respuesta contiene segment_materialization y debt_list. segment_materialization incluye id, tenant_id, list_id, filter_id, filter_version, criteria, max_rows, matched, added, truncated y requested_at. Los criterios en línea producen null en filter_id y filter_version.

La operación es idempotente para una pertenencia (list_id, debt_id) existente: repetirla no añade un miembro duplicado, pero registra una fila de evidencia aparte. El tope del catálogo del tenant limita cuántas se escriben. Cuando el tope recorta el resultado, la respuesta informa truncated: true; no afirma en silencio que la instantánea contenga todas las coincidencias. Un tope no positivo devuelve 422 unprocessable y no escribe nada. Una petición que falla no deja una lista recién creada vacía.

Los endpoints de instantánea usan los mismos códigos 400, 401, 403, 404, 409 y 422 descritos arriba. Además, un filtro guardado archivado devuelve 409 conflict.

Lista de verificación operativa

1. Confirma que debt_segmentation_enabled esté activa para el tenant.
2. Crea el filtro y conserva su id y su version.
3. Usa base_version en las ediciones para evitar sobrescrituras inadvertidas.
4. Trata el 404 como ambiguo a propósito; no lo uses para deducir datos de otro tenant ni si la función está activa.
5. Cuando las operaciones de instantánea aparezcan en un release publicado, revisa truncated antes de tratar una lista materializada como la selección buscada.