Consumidores

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.

Ficha del deudor por consumer_ref: deudas, DNC / cese y desistimiento (cease-and-desist), contador de Reg F y próxima ventana permitida, derivados de las fuentes de sólo anexado.

Endpoints

Método	Ruta	Resumen
GET	/v1/consumers/{id}	Ficha del deudor (deudas, DNC / cese y desistimiento, contador de Reg F, próxima ventana permitida)

Ficha del deudor (deudas, DNC / cese y desistimiento, contador de Reg F, próxima ventana permitida)

GET /v1/consumers/{id}

La ficha de UN deudor, identificado por consumer_ref, la cadena bajo la que core ya cuenta Reg F ({tenant, consumer_ref, debt_key}). core no tiene una entidad consumers y esto no añade ninguna: el id de la ruta es el consumer_ref que el CMS envió en POST /v1/debts/import, de modo que la ficha y la compuerta de Reg F no puedan discrepar sobre quién es "el mismo deudor". "" es la ausencia de un consumidor, nunca una ficha.

Todo se DERIVA en el momento de la petición de las fuentes de sólo anexado (call_attempts, conversations, cease_and_desist, las listas DNC); no se añade ningún contador ni caché. Cada deuda es la proyección pública de GET /v1/debts (teléfono enmascarado, sin account_number) más el nombre del deudor (debtor_name, core#1529), su contador de Reg F y su propia próxima ventana. No se publica ningún número de teléfono: el estado DNC son conteos por lista.

window / next_window responden a "¿cuándo es la próxima vez que se permite llamar a este deudor?", en UTC y en la hora local del destino. Salen de ejecutar las compuertas REALES listadas en evaluated_gates sobre una instantánea de sólo lectura, de modo que el instante indicado es uno que el propio marcador permitiría. NO cubren not_evaluated_gates (consentimiento, voz de IA / artificial, estado de la campaña, pruebas de aprovisionamiento DNC), que dependen de la campaña o de la marcación. La respuesta es fail-closed: permitted_now / scheduled sólo cuando una ejecución de compuertas permitió positivamente ese instante; undecidable (con reason) cuando no puede decidir (zona horaria de destino irresoluble, sin contactos, demasiados números que comprobar, una compuerta que falló, nada permitido dentro del horizonte de 9 días) y suppressed / not_dialable cuando no se debe llamar al deudor.

Un consumidor que existe sólo en otro tenant es 404, indistinguible de uno que no existe.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
id	path	string	sí	El consumer_ref del deudor (de 1 a 128 caracteres, no vacío, sin bytes NUL).

Respuestas

200

La ficha.

Campo	Tipo	Obligatorio	Descripción
consumer	object (ConsumerCard)	sí
consumer.id	string	sí	El consumer_ref.
consumer.identity	consumer_ref	sí	Qué clave identifica al consumidor. core no tiene entidad de consumidores; ésta es la clave bajo la que cuenta Reg F.
consumer.generated_at	string (date-time)	sí	El instante del reloj de cumplimiento en el que se evaluó cada cifra.
consumer.debts	arreglo de ConsumerDebt	sí
consumer.debts_truncated	boolean	sí	Verdadero cuando el consumidor tiene tantas deudas como el tope de página; entonces las ventanas son undecidable (debts_truncated).
consumer.cease_and_desist	object	sí
consumer.cease_and_desist.on_file	boolean	sí	Cualquier registro del consumidor suprime el contacto en todas las deudas, tal como lo lee la compuerta de consentimiento.
consumer.cease_and_desist.records	arreglo de object	sí
consumer.cease_and_desist.records[].scope	consumer · debt	sí
consumer.cease_and_desist.records[].debt_external_ref	string	sí
consumer.cease_and_desist.records[].received_at	string (date-time)	sí
consumer.dnc	object	sí	Conteos de los números de teléfono distintos del consumidor en cada lista. No se publica ningún número.
consumer.dnc.contacts_total	integer	sí
consumer.dnc.contacts_checked	integer	sí
consumer.dnc.contacts_listed	integer	sí
consumer.dnc.lists	object	sí
consumer.dnc.lists.federal	integer	sí
consumer.dnc.lists.state	integer	sí
consumer.dnc.lists.internal_tenant	integer	sí
consumer.dnc.lists.internal_global	integer	sí
consumer.dnc.truncated	boolean	sí	Verdadero cuando el consumidor tiene más números de los que la ficha comprueba.
consumer.next_window	object (ConsumerWindow)	sí	El próximo instante en que las compuertas dependientes del tiempo permiten una llamada (ConsumerCard.evaluated_gates), o por qué no lo hay.
consumer.next_window.status	permitted_now · scheduled · suppressed · not_dialable · undecidable	sí	permitted_now: las compuertas permiten una llamada en generated_at. scheduled: el primer instante permitido es at. suppressed: un listado DNC o un cese y desistimiento prohíbe el contacto. not_dialable: el estado de la deuda no es marcable. undecidable: la ficha no puede decidir y explica por qué en reason; nunca se lee como permiso.
consumer.next_window.reason	string | null	sí	Nulo para permitted_now / scheduled. En otro caso, un código como dnc_listed, cease_and_desist, debt_state_closed, no_contacts, tz_unresolved, too_many_contacts, debts_truncated, none_within_horizon, o el rule_id de la compuerta que bloqueó.
consumer.next_window.at	string (date-time) | null	sí	Primer instante permitido (UTC); nulo cuando no hay ninguno.
consumer.next_window.destination_timezone	string | null	sí	Zona IANA que la compuerta de horario de silencio evaluó primero en at.
consumer.next_window.destination_local_time	string (date-time) | null	sí	at en destination_timezone, con su desfase UTC.
consumer.negotiation_bounds	NegotiationBounds | null	sí	Política de negociación activa del agente de IA de este tenant, o nulo si no hay ninguna.
consumer.promise_max_horizon_days	integer	sí	El promise_max_horizon_days del tenant (90 por defecto): cuántos días hacia adelante puede fecharse una promesa de pago, contados desde el día UTC actual. Permite a un cliente ofrecer sólo las fechas que el cierre de la llamada aceptará.
consumer.evaluated_gates	arreglo de string	sí	Ids de regla de los que se derivan window / next_window.
consumer.not_evaluated_gates	arreglo de string	sí	Compuertas que window / next_window NO cubren.

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

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

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-*.

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}