Guiones de divulgación

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.

Biblioteca de guiones de aviso de cobranza (ADR #219): versiones inmutables por tenant, aprobadas mediante un evento sellado.

Endpoints

Método	Ruta	Resumen
`GET`	`/v1/disclosure-scripts`	Las versiones de guiones de aviso de cobranza del tenant, con su estado
`POST`	`/v1/disclosure-scripts`	Escribir una versión BORRADOR de un guion de aviso de cobranza
`POST`	`/v1/disclosure-scripts/{id}/approve`	Aprobar una versión en borrador (sellada en la cadena de cumplimiento)
`POST`	`/v1/disclosure-scripts/{id}/retire`	Retirar una versión aprobada (sellada en la cadena de cumplimiento)

Las versiones de guiones de aviso de cobranza del tenant, con su estado

http

GET /v1/disclosure-scripts

Todas las versiones de todos los selectores, ordenadas por jurisdiction, debt_type y luego la versión más reciente primero. El status sale de los eventos sellados, nunca de la fila de la versión: una versión sin evento approved es un draft y nunca se lee como aprobada. jurisdiction, debt_type y status filtran. Legible por cualquier token de alcance tenant (una clave dd_ o un login del dashboard).

Parámetros

Nombre	En	Tipo	Obligatorio
`jurisdiction`	query	string	no
`debt_type`	query	string	no
`status`	query	`draft` · `approved` · `retired`	no

Respuestas

`200`

Las versiones.

Campo	Tipo	Obligatorio	Descripción
`scripts`	arreglo de DisclosureScript	sí
`scripts[].id`	string (uuid)	sí
`scripts[].tenant_id`	string (uuid)	sí
`scripts[].kind`	`collection_notice`	sí
`scripts[].jurisdiction`	string	sí
`scripts[].debt_type`	string	sí
`scripts[].version`	integer	sí	Por tenant y selector.
`scripts[].text`	string	sí
`scripts[].text_sha256`	string	sí	SHA-256 (hex en minúsculas) de `text`, derivado por core.
`scripts[].legal_ref`	string	sí
`scripts[].authored_by`	string	sí
`scripts[].status`	`draft` · `approved` · `retired`	sí	Se lee de los eventos sellados; si no hay evento `approved`, es `draft`.
`scripts[].approval`	DisclosureScriptEvent \| null	no
`scripts[].retirement`	DisclosureScriptEvent \| null	no
`scripts[].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"
  }
}

Escribir una versión BORRADOR de un guion de aviso de cobranza

http

POST /v1/disclosure-scripts

Crea un borrador inmutable para el selector (jurisdiction, debt_type); core asigna el número de versión (max + 1 por tenant y selector). Un borrador NO es un guion aprobado: necesita POST .../approve. text tiene como máximo 10 000 bytes; text_sha256 lo deriva core del texto y nunca se acepta del cliente. legal_ref (la cita de la norma o dictamen en que se apoya el texto) es obligatorio y no puede estar en blanco. jurisdiction es un código de estado USPS o *; debt_type es other, student_loan o *. Los campos desconocidos dan 400. La plataforma no juzga el contenido legal del texto. Requiere una clave dd_ o un login del dashboard con el rol account_admin.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`kind`	`collection_notice`	no
`jurisdiction`	string	sí	Un código de estado USPS (en mayúsculas) o `*` para cualquiera.
`debt_type`	`other` · `student_loan` · `*`	sí	`*` para cualquiera.
`text`	string	sí	Como máximo 10 000 BYTES; no en blanco.
`legal_ref`	string	sí	La cita de la norma o dictamen en que se apoya el texto; no en blanco.

json

{
  "jurisdiction": "*",
  "debt_type": "*",
  "text": "Texto del aviso redactado y revisado por el despacho del tenant.",
  "legal_ref": "Dictamen interno 2026-10 del despacho"
}

Respuestas

`201`

El borrador.

Campo	Tipo	Obligatorio	Descripción
`script`	object (DisclosureScript)	sí	Una versión inmutable de un guion de aviso de cobranza y su estado.
`script.id`	string (uuid)	sí
`script.tenant_id`	string (uuid)	sí
`script.kind`	`collection_notice`	sí
`script.jurisdiction`	string	sí
`script.debt_type`	string	sí
`script.version`	integer	sí	Por tenant y selector.
`script.text`	string	sí
`script.text_sha256`	string	sí	SHA-256 (hex en minúsculas) de `text`, derivado por core.
`script.legal_ref`	string	sí
`script.authored_by`	string	sí
`script.status`	`draft` · `approved` · `retired`	sí	Se lee de los eventos sellados; si no hay evento `approved`, es `draft`.
`script.approval`	DisclosureScriptEvent \| null	no
`script.retirement`	DisclosureScriptEvent \| null	no
`script.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

json

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

`403` — DisclosureScriptWriteForbidden

Se rechazó una escritura de guion. code role_forbidden: el llamante es un login member (la ruta admite una clave dd_ o un login account_admin). code forbidden: el tenant está suspendido o el token es un token de widget.

json

{
  "error": {
    "code": "role_forbidden",
    "message": "approving a disclosure script takes a dd_ key or a dashboard login with the account_admin role"
  }
}

Aprobar una versión en borrador (sellada en la cadena de cumplimiento)

http

POST /v1/disclosure-scripts/{id}/approve

Escribe un evento approved de sólo anexado y lo sella en la cadena de cumplimiento del tenant en la MISMA transacción: si el sellado falla no se escribe nada y la versión sigue siendo un borrador. reviewed_by (la persona o firma que revisó el texto) es obligatorio. Una versión que ya está aprobada o retirada da 409. La versión de otro tenant, o un id que no es UUID, da 404. Requiere una clave dd_ o un login account_admin.

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
`reviewed_by`	string	sí

json

{
  "reviewed_by": "Despacho de ejemplo"
}

Respuestas

`200`

La versión, ahora approved.

Campo	Tipo	Obligatorio	Descripción
`script`	object (DisclosureScript)	sí	Una versión inmutable de un guion de aviso de cobranza y su estado.
`script.id`	string (uuid)	sí
`script.tenant_id`	string (uuid)	sí
`script.kind`	`collection_notice`	sí
`script.jurisdiction`	string	sí
`script.debt_type`	string	sí
`script.version`	integer	sí	Por tenant y selector.
`script.text`	string	sí
`script.text_sha256`	string	sí	SHA-256 (hex en minúsculas) de `text`, derivado por core.
`script.legal_ref`	string	sí
`script.authored_by`	string	sí
`script.status`	`draft` · `approved` · `retired`	sí	Se lee de los eventos sellados; si no hay evento `approved`, es `draft`.
`script.approval`	DisclosureScriptEvent \| null	no
`script.retirement`	DisclosureScriptEvent \| null	no
`script.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

json

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

`403` — DisclosureScriptWriteForbidden

json

{
  "error": {
    "code": "role_forbidden",
    "message": "approving a disclosure script takes a dd_ key or a dashboard login with the account_admin role"
  }
}

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

Retirar una versión aprobada (sellada en la cadena de cumplimiento)

http

POST /v1/disclosure-scripts/{id}/retire

Escribe un evento retired de sólo anexado y lo sella, igual que la aprobación. Sólo se retira una versión aprobada: un borrador da 409 (nunca se aprobó) y también una ya retirada. reviewed_by es opcional aquí. La versión de otro tenant, o un id que no es UUID, da 404. Requiere una clave dd_ o un login account_admin.

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)

Campo	Tipo	Obligatorio	Descripción
`reviewed_by`	string	no

Respuestas

`200`

La versión, ahora retired.

Campo	Tipo	Obligatorio	Descripción
`script`	object (DisclosureScript)	sí	Una versión inmutable de un guion de aviso de cobranza y su estado.
`script.id`	string (uuid)	sí
`script.tenant_id`	string (uuid)	sí
`script.kind`	`collection_notice`	sí
`script.jurisdiction`	string	sí
`script.debt_type`	string	sí
`script.version`	integer	sí	Por tenant y selector.
`script.text`	string	sí
`script.text_sha256`	string	sí	SHA-256 (hex en minúsculas) de `text`, derivado por core.
`script.legal_ref`	string	sí
`script.authored_by`	string	sí
`script.status`	`draft` · `approved` · `retired`	sí	Se lee de los eventos sellados; si no hay evento `approved`, es `draft`.
`script.approval`	DisclosureScriptEvent \| null	no
`script.retirement`	DisclosureScriptEvent \| null	no
`script.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

json

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

`403` — DisclosureScriptWriteForbidden

json

{
  "error": {
    "code": "role_forbidden",
    "message": "approving a disclosure script takes a dd_ key or a dashboard login with the account_admin role"
  }
}

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

Guiones de divulgación ​

Endpoints ​

Las versiones de guiones de aviso de cobranza del tenant, con su estado ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

Escribir una versión BORRADOR de un guion de aviso de cobranza ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — DisclosureScriptWriteForbidden ​

Aprobar una versión en borrador (sellada en la cadena de cumplimiento) ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — DisclosureScriptWriteForbidden ​

404 — NotFound ​

409 — Conflict ​

Retirar una versión aprobada (sellada en la cadena de cumplimiento) ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — DisclosureScriptWriteForbidden ​

404 — NotFound ​

409 — Conflict ​

Guiones de divulgación

Endpoints

Las versiones de guiones de aviso de cobranza del tenant, con su estado

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

Escribir una versión BORRADOR de un guion de aviso de cobranza

`201`

`400` — BadRequest

`401` — Unauthorized

`403` — DisclosureScriptWriteForbidden

Aprobar una versión en borrador (sellada en la cadena de cumplimiento)

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — DisclosureScriptWriteForbidden

`404` — NotFound

`409` — Conflict

Retirar una versión aprobada (sellada en la cadena de cumplimiento)

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — DisclosureScriptWriteForbidden

`404` — NotFound

`409` — Conflict