Listas de deudas

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.

Listas reutilizables de deudas, asociadas a campañas (ADR #162).

Endpoints

Método	Ruta	Resumen
`GET`	`/v1/debt-lists`	Las listas reutilizables del tenant, con su tamaño contado al leer
`POST`	`/v1/debt-lists`	Crear una lista reutilizable
`GET`	`/v1/debt-lists/{id}`	Una lista reutilizable
`POST`	`/v1/debt-lists/{id}/archive`	Archivar una lista (terminal, nunca un borrado)
`POST`	`/v1/debt-lists/{id}/import`	Importación masiva EN una lista (el pipeline de /v1/debts/import)
`GET`	`/v1/debt-lists/{id}/members`	Leer los miembros de una lista
`DELETE`	`/v1/debt-lists/{id}/members`	Sacar hasta 500 deudas de una lista en una sola llamada
`DELETE`	`/v1/debt-lists/{id}/members/{debt_id}`	Sacar una deuda de una lista
`PUT`	`/v1/debt-lists/{id}/campaigns/{campaign_id}`	Asociar una lista a una campaña
`DELETE`	`/v1/debt-lists/{id}/campaigns/{campaign_id}`	Disociar una lista de una campaña

Las listas reutilizables del tenant, con su tamaño contado al leer

http

GET /v1/debt-lists

Todas las listas del tenant, por nombre. size (miembros) y campaign_ids (las campañas a las que la lista está asociada) se cuentan cuando se atiende la petición: la plataforma no mantiene contador para ellos, así que la cifra nunca es más antigua que la respuesta. Con tope de 2 000 listas. Las listas archivadas (POST /v1/debt-lists/{id}/archive) se excluyen salvo include_archived=true.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`include_archived`	query	boolean	no	`true` devuelve también las listas archivadas. Cualquier otro valor las deja fuera.

Respuestas

`200`

Las listas.

Campo	Tipo	Obligatorio	Descripción
`debt_lists`	arreglo de DebtList	sí
`debt_lists[].id`	string (uuid)	sí
`debt_lists[].tenant_id`	string (uuid)	no
`debt_lists[].name`	string	sí
`debt_lists[].size`	integer	sí	Miembros de la lista ahora.
`debt_lists[].campaign_ids`	arreglo de string (uuid)	sí	Las campañas a las que está asociada la lista, empezando por la asociación más antigua.
`debt_lists[].archived`	boolean	sí
`debt_lists[].archived_at`	string,null (date-time)	no
`debt_lists[].created_at`	string (date-time)	no
`debt_lists[].updated_at`	string (date-time)	no
`truncated`	boolean	sí	`true` cuando hay más filas que las 2 000 listas que devuelve el listado: la respuesta es un prefijo en el orden documentado, no el conjunto completo.

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

`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 una lista reutilizable

http

POST /v1/debt-lists

Una lista es un conjunto con nombre de deudas del tenant. Se trabaja ASOCIÁNDOLA a campañas (PUT /v1/debt-lists/{id}/campaigns/{campaign_id}), nunca copiando una deuda: una deuda es una cuenta dondequiera que se trabaje. name se recorta, no debe estar vacío (400), tiene como máximo 200 caracteres y es único en el tenant (409).

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`name`	string	sí

json

{
  "name": "Cartera Q3"
}

Respuestas

`201`

La nueva lista (size 0, sin campañas).

Campo	Tipo	Obligatorio	Descripción
`debt_list`	object (DebtList)	sí	Una lista reutilizable. `size` y `campaign_ids` se cuentan cuando se lee la lista, nunca se almacenan. `archived` / `archived_at` son terminales.
`debt_list.id`	string (uuid)	sí
`debt_list.tenant_id`	string (uuid)	no
`debt_list.name`	string	sí
`debt_list.size`	integer	sí	Miembros de la lista ahora.
`debt_list.campaign_ids`	arreglo de string (uuid)	sí	Las campañas a las que está asociada la lista, empezando por la asociación más antigua.
`debt_list.archived`	boolean	sí
`debt_list.archived_at`	string,null (date-time)	no
`debt_list.created_at`	string (date-time)	no
`debt_list.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"
  }
}

`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 lista reutilizable

http

GET /v1/debt-lists/{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 lista, con su tamaño y sus campañas contados al leer.

Campo	Tipo	Obligatorio	Descripción
`debt_list`	object (DebtList)	sí	Una lista reutilizable. `size` y `campaign_ids` se cuentan cuando se lee la lista, nunca se almacenan. `archived` / `archived_at` son terminales.
`debt_list.id`	string (uuid)	sí
`debt_list.tenant_id`	string (uuid)	no
`debt_list.name`	string	sí
`debt_list.size`	integer	sí	Miembros de la lista ahora.
`debt_list.campaign_ids`	arreglo de string (uuid)	sí	Las campañas a las que está asociada la lista, empezando por la asociación más antigua.
`debt_list.archived`	boolean	sí
`debt_list.archived_at`	string,null (date-time)	no
`debt_list.created_at`	string (date-time)	no
`debt_list.updated_at`	string (date-time)	no

`401` — Unauthorized

json

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

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

Archivar una lista (terminal, nunca un borrado)

http

POST /v1/debt-lists/{id}/archive

Una lista es evidencia de a quién trabajó una campaña, por lo que nunca se borra: se archiva (archived_at, terminal, de sólo anexado). GET /v1/debt-lists deja de devolverla salvo include_archived=true; GET /v1/debt-lists/{id} sigue leyéndola, con archived: true. Sus miembros y sus asociaciones pasadas se conservan. Una lista archivada no admite miembros nuevos (importación a la lista, instantánea de segmento) y no puede asociarse a una campaña: 409. IDEMPOTENTE: archivar una lista archivada la devuelve sin cambios. 409 mientras la lista esté asociada a una campaña que no esté archived (fail-closed: disóciala o archiva antes la campaña). 404 cuando la lista no es del tenant. Sin cuerpo.

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 lista, ya archivada.

Campo	Tipo	Obligatorio	Descripción
`debt_list`	object (DebtList)	sí	Una lista reutilizable. `size` y `campaign_ids` se cuentan cuando se lee la lista, nunca se almacenan. `archived` / `archived_at` son terminales.
`debt_list.id`	string (uuid)	sí
`debt_list.tenant_id`	string (uuid)	no
`debt_list.name`	string	sí
`debt_list.size`	integer	sí	Miembros de la lista ahora.
`debt_list.campaign_ids`	arreglo de string (uuid)	sí	Las campañas a las que está asociada la lista, empezando por la asociación más antigua.
`debt_list.archived`	boolean	sí
`debt_list.archived_at`	string,null (date-time)	no
`debt_list.created_at`	string (date-time)	no
`debt_list.updated_at`	string (date-time)	no

`401` — Unauthorized

json

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

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

Importación masiva EN una lista (el pipeline de /v1/debts/import)

http

POST /v1/debt-lists/{id}/import

El MISMO cuerpo, topes, respuesta fail-soft por elemento y reglas de elemento que POST /v1/debts/import (las deudas hacen upsert por external_ref, los contactos por phone_e164, los campos de contacto son aditivos y de tres estados, un null hace fallar el elemento), más dos reglas propias:

cada deuda que se importa entra en la lista, como el ÚLTIMO paso de su elemento: un elemento que falla en cualquier paso no se añade (su deuda puede estar ya escrita, exactamente igual que en /v1/debts/import, pero no entra en ninguna campaña a través de esta lista). Añadir es idempotente: repetir la carga no añade nada dos veces. Ninguna importación saca nunca una deuda de una lista ni de una campaña; DELETE /v1/debt-lists/{id}/members/{debt_id} es el verbo para eso.
un elemento que lleve campaign_id (cualquier valor, null incluido) HACE FALLAR ese elemento, antes de escribir nada para él. Las campañas de las deudas de una lista son las asociaciones de la lista; el campaign_id directo de una deuda se fija en /v1/debts/import.

Todo miembro de la lista, importado ahora o después, forma parte de la población de toda campaña a la que la lista esté asociada. 404 cuando la lista no es del tenant: no se escribe nada, ni siquiera las deudas.

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`.
`mapping_id`	query	string (uuid)	no	La plantilla de mapeo de importación con la que se mapeó el archivo. Se resuelve ANTES de que se importe nada (`404` cuando no es del tenant, `409` cuando está archivada: no se escribe nada) y la versión usada se registra después de la importación (`GET /v1/import-mappings/{id}/uses`). En el formulario multipart de `POST /v1/debts/import` la plantilla reemplaza las partes `mapping` y `separator`. Si se omite, la importación no cambia.
`mapping_version`	query	integer	no	La versión de `mapping_id` que se registra. Por defecto, la actual. Requiere `mapping_id`.
`import_id`	query	string (uuid)	no	Nombra UNA importación que el cliente envía en varias solicitudes (fragmentos). Los usos que esas solicitudes dejan se leen en `GET /v1/import-mappings/{id}/uses` como un único uso — los conteos sumados, `id` = este `import_id` — siempre que compartan la versión y la lista. Requiere `mapping_id` (`400` en caso contrario, y para un valor que no sea un UUID). Si se omite, cada solicitud es su propio uso.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`debts`	arreglo de DebtImportItem	sí
`debts[].external_ref`	string	sí	LA clave del contador de Reg F (clave de upsert).
`debts[].consumer_ref`	string	sí
`debts[].debt_type`	`other` · `student_loan`	no
`debts[].account_number`	string	no
`debts[].debtor_name`	string \| null	no	Nombre completo opcional del deudor, texto libre. Los espacios en blanco se colapsan y se recortan; un valor en blanco se almacena como sin nombre. Más de 200 caracteres hace fallar el ELEMENTO (error de fila `debtor_name should be at most 200 character(s)`), no el lote. Cifrado en reposo, no buscable, y nunca se envía a analítica, webhooks ni registros. Como los demás campos de la deuda es una instantánea: una reimportación que lo omite borra el nombre almacenado.
`debts[].amount_cents`	integer	no
`debts[].currency`	string	no
`debts[].state`	`open` · `in_collection` · `promise_to_pay` · `paid` · `settled` · `disputed` · `closed`	no
`debts[].campaign_id`	string (uuid)	no
`debts[].prior_attempts_7d`	integer	no	Cuántas llamadas sobre ESTA deuda ya realizó el cliente desde su sistema anterior en los últimos 7 días. Sin él, el contador 7-en-7 de Reg F arranca A CIEGAS en una cartera migrada — solo vio los intentos que realizó esta plataforma — y una cartera trasladada a mitad de ciclo puede agotar el tope legal en su primera semana. Se materializa como filas de intento que la compuerta ya lee, de modo que la compuerta en sí no cambia. Es un TOTAL para la ventana, no un delta: reenviar la misma carga no suma nada, y reenviar un número MENOR nunca retracta el historial (el conteo solo sube, como `last_conversation_at`). Los valores superiores a 7 se almacenan como 7 — 7 ya satura todos los topes de frecuencia que tiene el motor, así que el veredicto es idéntico y el tope solo acota la escritura. Un valor que no sea un entero >= 0 hace fallar ESE elemento, como cualquier otro campo incorrecto en esta ruta; omitirlo no cambia nada.
`debts[].last_conversation_at`	string (date-time)	no	Cuándo habló el cliente por última vez con el deudor, según su sistema anterior (RFC 3339 con desfase UTC). Sin él, el periodo de enfriamiento de 7 días posterior al contacto de Reg F (12 CFR 1006.14(b)(2)(i)(B)) arranca A CIEGAS en una cartera migrada: la plataforma solo conoce las conversaciones que registró y podría volver a llamar dentro de la ventana. Se materializa como una fila de `conversations` con `source: cms_import`, que la compuerta ya lee, de modo que la compuerta en sí no cambia; el ancla `last_conversation_at` de la deuda avanza hasta ella. Reenviar la misma carga no suma nada, y una fecha MÁS ANTIGUA nunca retrocede el ancla. Los reportes que miden la actividad de la plataforma (penetración, tasa de abandono, la exportación de intentos) no la cuentan. Un valor mal formado, uno sin desfase UTC o uno en el futuro hace fallar ESE elemento (una fecha futura mantendría abierto el enfriamiento más allá de su ventana); omitirlo no cambia nada.
`debts[].delinquent_since`	string (date)	no	La fecha de calendario en que la deuda entró en mora (`YYYY-MM-DD`), según el sistema anterior del cliente. Es la antigüedad de la deuda: los filtros de segmentación como "en mora de 31 a 90 días" se calculan contra ella. Es una instantánea, como `debtor_name`: reimportar la deuda sin ella la borra. Una deuda sin fecha nunca coincide con un filtro de antigüedad. Cualquier cosa que no sea una fecha de calendario real en ese formato exacto (`null`, una cadena vacía, un número, una marca de tiempo, `2026-02-30`) o una fecha futura hace fallar ESE elemento; omitirla está bien. En una importación CSV una celda en blanco equivale a omitir el campo.
`debts[].contacts`	arreglo de object	no
`debts[].contacts[].phone_e164`	string	sí	E.164 (clave de upsert dentro de la deuda).
`debts[].contacts[].line_type`	`mobile` · `landline` · `voip` · `unknown`	no
`debts[].contacts[].timezone`	string	no	IANA.
`debts[].contacts[].us_state`	string	no
`debts[].contacts[].city`	string	no
`debts[].contacts[].postal_code`	string	no	Código postal del consumidor. Es lo que resuelve el distrito de NYC para el tope por deuda: sin él, un contacto de NY no puede descartarse de la ciudad y recibe el tope estricto. Se actualiza en la reimportación solo cuando la carga lo incluye — omitirlo, o enviarlo como `""`, nunca borra un valor almacenado, y enviarlo como `null` hace fallar el elemento. Misma regla que `consumer_ref`, `timezone`, `us_state` y `city`: el contrato es uno solo, aunque esta columna sea la única anulable de las seis.
`debts[].contacts[].is_primary`	boolean	no	Afirma EL contacto principal de la deuda. En la importación, `true` degrada al principal anterior (se conserva, nunca se borra) y promueve a este; omitido o `false` deja intacto al principal existente. Más de uno por elemento hace fallar el elemento.
`debts[].contacts[].consumer_ref`	string	no

json

{
  "debts": [
    {
      "external_ref": "cms-debt-0002",
      "consumer_ref": "cms-consumer-9002",
      "amount_cents": 48000,
      "currency": "USD",
      "contacts": [
        {
          "phone_e164": "+13125551002",
          "line_type": "landline",
          "timezone": "America/Chicago",
          "is_primary": true
        }
      ]
    }
  ]
}

Respuestas

`200`

Resultado de la importación (tolerancia a fallos por elemento).

Campo	Tipo	Obligatorio	Descripción
`imported`	integer	sí
`failed`	arreglo de object	sí
`failed[].index`	integer	no
`failed[].error`	string	no
`mapping`	object	no	Presente solo cuando la solicitud nombró `mapping_id`: la versión de la plantilla registrada como usada.
`mapping.id`	string (uuid)	sí
`mapping.version`	integer	sí

json

{
  "imported": 1,
  "failed": []
}

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

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

La importación se rechazó ANTES de leer ninguna fila (core#2505). Dos códigos, ambos con Retry-After. import_in_progress: el tenant ya tiene en ejecución su máximo de importaciones (2 por defecto, por nodo); reintenta cuando termine una. rate_limited: más de 10 importaciones en la ventana fija (por defecto) para el tenant, que es un límite por tenant y no por clave porque el pool de conexiones que drena una importación es el de la celda. Se aplica por igual a POST /v1/debts/import y POST /v1/debt-lists/{id}/import. La cuota de solicitudes por clave aún puede responder rate_limited primero.

in_flight

json

{
  "error": {
    "code": "import_in_progress",
    "message": "an import of this tenant is still running; retry when it finishes"
  }
}

window

json

{
  "error": {
    "code": "rate_limited",
    "message": "import rate limit exceeded; retry later"
  }
}

Leer los miembros de una lista

http

GET /v1/debt-lists/{id}/members

Las deudas que están en la lista, de la entrada más antigua a la más reciente, paginadas con un cursor keyset opaco: una página nunca repite ni pierde un miembro. Cada fila lleva debt_id, el external_ref del cliente y added_at, sin teléfono ni nombre del deudor. Una lista archivada sigue siendo legible. 404 cuando la lista no es del tenant. No se registra por miembro qué importación puso una deuda en la lista: una importación se deshace leyendo sus external_ref y quitándolos con DELETE /v1/debt-lists/{id}/members.

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`.
`limit`	query	integer	no	Tamaño de página (un valor por encima del techo se recorta, no se rechaza).
`cursor`	query	string	no	Cursor keyset opaco: el `next_cursor` de la página anterior.

Respuestas

`200`

Una página de miembros.

Campo	Tipo	Obligatorio	Descripción
`members`	arreglo de DebtListMember	sí
`members[].debt_id`	string (uuid)	sí
`members[].external_ref`	string	sí
`members[].added_at`	string (date-time)	sí
`next_cursor`	string \| null	sí	Cursor de la página siguiente; `null` en la última.

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

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

Sacar hasta 500 deudas de una lista en una sola llamada

http

DELETE /v1/debt-lists/{id}/members

El gemelo por lotes de DELETE /v1/debt-lists/{id}/members/{debt_id}, con la misma garantía: las deudas no se tocan, sólo salen de la lista y, por tanto, de la población de las campañas que las tenían a través de ella (salvo que estén en ellas por otra vía: su propio campaign_id, u otra lista). IDEMPOTENTE: un id que no es miembro no quita nada y no es un error; la respuesta cuenta las que SALIERON. Todo o nada en cuanto a la forma: 400 cuando debt_ids está vacío, tiene más de 500 o lleva un valor que no es un UUID, y entonces no sale nada. 404 sólo cuando la lista no es del tenant. El cuerpo viaja en un DELETE.

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
`debt_ids`	arreglo de string (uuid)	sí

json

{
  "debt_ids": [
    "6f1d3b0e-4c1a-4a52-9a43-0a3f6c1d9e11"
  ]
}

Respuestas

`200`

Cuántas deudas salieron de la lista.

Campo	Tipo	Obligatorio	Descripción
`removed`	integer	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"
  }
}

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

Sacar una deuda de una lista

http

DELETE /v1/debt-lists/{id}/members/{debt_id}

La deuda sale de la lista y, con ella, de la población de las campañas a las que la lista está asociada (salvo que esté en ellas por otra vía: su propio campaign_id, u otra lista). La deuda en sí no se toca. 404 cuando no era miembro de la lista del tenant.

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`.
`debt_id`	path	string (uuid)	sí	El UUID de la deuda miembro. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`204`

La deuda ya no es miembro.

`401` — Unauthorized

json

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

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

Asociar una lista a una campaña

http

PUT /v1/debt-lists/{id}/campaigns/{campaign_id}

Todo miembro de la lista, los que están ahora y los que se importen después, entra en la población de la campaña desde su próxima lectura (el siguiente tick de su runner). Por tanto, una deuda puede estar en varias campañas a la vez: cada una la trabaja con sus propias marcas, mientras que el contador 7-en-7 de Reg F, el parking de una regla de disposición y el estado de la deuda siguen siendo por deuda y cruzan campañas, de modo que una segunda campaña nunca añade llamadas por encima del tope. IDEMPOTENTE: un segundo PUT no cambia nada y responde lo mismo. 404 cuando la lista o la campaña no son del tenant; 409 cuando la lista está archivada. Sin cuerpo.

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`.
`campaign_id`	path	string (uuid)	sí	El UUID de la campaña. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`200`

La lista, con sus campañas.

Campo	Tipo	Obligatorio	Descripción
`debt_list`	object (DebtList)	sí	Una lista reutilizable. `size` y `campaign_ids` se cuentan cuando se lee la lista, nunca se almacenan. `archived` / `archived_at` son terminales.
`debt_list.id`	string (uuid)	sí
`debt_list.tenant_id`	string (uuid)	no
`debt_list.name`	string	sí
`debt_list.size`	integer	sí	Miembros de la lista ahora.
`debt_list.campaign_ids`	arreglo de string (uuid)	sí	Las campañas a las que está asociada la lista, empezando por la asociación más antigua.
`debt_list.archived`	boolean	sí
`debt_list.archived_at`	string,null (date-time)	no
`debt_list.created_at`	string (date-time)	no
`debt_list.updated_at`	string (date-time)	no

`401` — Unauthorized

json

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

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

Disociar una lista de una campaña

http

DELETE /v1/debt-lists/{id}/campaigns/{campaign_id}

Los miembros de la lista salen de la población de la campaña desde su próxima lectura (salvo que estén en ella por otra vía). Las deudas, su propio campaign_id y la lista no se tocan. 404 cuando no existía tal asociación en el tenant.

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`.
`campaign_id`	path	string (uuid)	sí	El UUID de la campaña. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`204`

La asociación ya no existe.

`401` — Unauthorized

json

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

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

Listas de deudas ​

Endpoints ​

Las listas reutilizables del tenant, con su tamaño contado al leer ​

200 ​

401 — Unauthorized ​

429 — ApiKeyRateLimited ​

Crear una lista reutilizable ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Una lista reutilizable ​

200 ​

401 — Unauthorized ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Archivar una lista (terminal, nunca un borrado) ​

200 ​

401 — Unauthorized ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Importación masiva EN una lista (el pipeline de /v1/debts/import) ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

404 — NotFound ​

409 — Conflict ​

429 — ImportThrottled ​

Leer los miembros de una lista ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Sacar hasta 500 deudas de una lista en una sola llamada ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Sacar una deuda de una lista ​

204 ​

401 — Unauthorized ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Asociar una lista a una campaña ​

200 ​

401 — Unauthorized ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Disociar una lista de una campaña ​

204 ​

401 — Unauthorized ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Listas de deudas

Endpoints

Las listas reutilizables del tenant, con su tamaño contado al leer

`200`

`401` — Unauthorized

`429` — ApiKeyRateLimited

Crear una lista reutilizable

`201`

`400` — BadRequest

`401` — Unauthorized

`409` — Conflict

`429` — ApiKeyRateLimited

Una lista reutilizable

`200`

`401` — Unauthorized

`404` — NotFound

`429` — ApiKeyRateLimited

Archivar una lista (terminal, nunca un borrado)

`200`

`401` — Unauthorized

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited

Importación masiva EN una lista (el pipeline de /v1/debts/import)

`200`

`400` — BadRequest

`401` — Unauthorized

`404` — NotFound

`409` — Conflict

`429` — ImportThrottled

Leer los miembros de una lista

`200`

`400` — BadRequest

`401` — Unauthorized

`404` — NotFound

`429` — ApiKeyRateLimited

Sacar hasta 500 deudas de una lista en una sola llamada

`200`

`400` — BadRequest

`401` — Unauthorized

`404` — NotFound

`429` — ApiKeyRateLimited

Sacar una deuda de una lista

`204`

`401` — Unauthorized

`404` — NotFound

`429` — ApiKeyRateLimited

Asociar una lista a una campaña

`200`

`401` — Unauthorized

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited

Disociar una lista de una campaña

`204`

`401` — Unauthorized

`404` — NotFound

`429` — ApiKeyRateLimited