Promesas de pago

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.

Pipeline de promesas de pago.

Endpoints

Método	Ruta	Resumen
GET	/v1/promises	Listar promesas (pipeline de PTP)
PATCH	/v1/promises/{id}	Resolver una promesa

Listar promesas (pipeline de PTP)

GET /v1/promises

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
debt_id	query	string (uuid)	no
status	query	pending · kept · broken · cancelled	no
limit	query	integer	no	Tamaño de página (por defecto 100, máximo 1000).

Respuestas

200

Promesas, de la más reciente a la más antigua.

Campo	Tipo	Obligatorio	Descripción
promises	arreglo de Promise	sí
promises[].id	string (uuid)	no
promises[].tenant_id	string (uuid)	no
promises[].debt_id	string (uuid)	no
promises[].call_attempt_id	string (uuid) | null	no
promises[].agent_id	string (uuid) | null	no
promises[].amount_cents	integer	no
promises[].currency	MXN · USD	no
promises[].promised_date	string (date)	no
promises[].status	pending · kept · broken · cancelled	no
promises[].note	string | null	no
promises[].created_at	string (date-time)	no
promises[].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"
  }
}

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

Resolver una promesa

PATCH /v1/promises/{id}

La máquina de estados es pending → kept|broken|cancelled (terminal): nuevas transiciones → 409 conflict; otras cadenas → 400. Las filas nunca se eliminan.

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
status	kept · broken · cancelled	sí

{
  "status": "kept"
}

Respuestas

200

La promesa resuelta.

Campo	Tipo	Obligatorio	Descripción
promise	object (Promise)	sí
promise.id	string (uuid)	no
promise.tenant_id	string (uuid)	no
promise.debt_id	string (uuid)	no
promise.call_attempt_id	string (uuid) | null	no
promise.agent_id	string (uuid) | null	no
promise.amount_cents	integer	no
promise.currency	MXN · USD	no
promise.promised_date	string (date)	no
promise.status	pending · kept · broken · cancelled	no
promise.note	string | null	no
promise.created_at	string (date-time)	no
promise.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"
  }
}

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

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