Rellamadas

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.

Citas de remarcación acordadas con el consumidor.

Endpoints

Método	Ruta	Resumen
`GET`	`/v1/callbacks`	Vista de la cola de rellamadas / feed de vencidas
`POST`	`/v1/callbacks`	Programar una remarcación acordada con el consumidor
`POST`	`/v1/callbacks/{id}/complete`	pending → done
`POST`	`/v1/callbacks/{id}/cancel`	pending → cancelled
`POST`	`/v1/callbacks/{id}/miss`	pending → missed

Vista de la cola de rellamadas / feed de vencidas

http

GET /v1/callbacks

due=now (también true/1) es el feed de vencidas para el ejecutor (pendientes Y scheduled_at <= now, por prioridad y luego por orden de tiempo); en otro caso, la vista de cola filtrada por status (por defecto pending, la más próxima primero; done, cancelled y missed listan primero la cita más reciente). agent_id limita a las rellamadas que creó ese agente. La vista de cola pagina por keyset: pasa el next_cursor anterior como cursor (opaco; null en la última página). due=now no se pagina.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`due`	query	`now` · `true` · `1`	no
`status`	query	`pending` · `done` · `cancelled` · `missed`	no
`campaign_id`	query	string (uuid)	no
`debt_id`	query	string (uuid)	no
`agent_id`	query	string (uuid)	no
`limit`	query	integer	no	Tamaño de página (por defecto 100, máximo 1000).
`cursor`	query	string	no	Cursor keyset opaco del `next_cursor` de la página anterior.

Respuestas

`200`

Rellamadas que coinciden con la vista.

Campo	Tipo	Obligatorio	Descripción
`callbacks`	arreglo de Callback	sí
`callbacks[].id`	string (uuid)	no
`callbacks[].tenant_id`	string (uuid)	no
`callbacks[].debt_id`	string (uuid)	no
`callbacks[].contact_phone`	string	no
`callbacks[].campaign_id`	string (uuid) \| null	no
`callbacks[].agent_id`	string (uuid) \| null	no
`callbacks[].scheduled_at`	string (date-time)	no
`callbacks[].note`	string \| null	no
`callbacks[].priority`	integer	no
`callbacks[].status`	`pending` · `done` · `cancelled` · `missed`	no
`callbacks[].created_at`	string (date-time)	no
`callbacks[].updated_at`	string (date-time)	no
`next_cursor`	string,null	no	Cursor opaco para la página siguiente; `null` en la última página.

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

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

Programar una remarcación acordada con el consumidor

http

POST /v1/callbacks

contact_phone ya debe ser un contacto de la deuda (las compuertas necesitan datos de línea/localización) → de lo contrario 422; menos del aviso mínimo del tenant (callback_min_notice_seconds, 10 minutos por defecto) → 422; el número está en cuarentena R16 → 422 (la plataforma no prometerá una llamada que no puede hacer); deuda desconocida → 404; marca de tiempo inválida → 400. campaign_id toma por defecto la ÚNICA campaña cuya población contiene la deuda: su propio campaign_id, o la campaña de una lista en la que está. Una deuda en MÁS de una campaña (la propia y la de una lista, o dos listas) no tiene valor por defecto: omitir campaign_id, o enviarlo null, es 422; la plataforma no elige una campaña por el llamante. El ejecutor de campañas marca las rellamadas vencidas ANTES que los leads nuevos.

agent_id es el CREADOR de la rellamada y es opcional (una rellamada puede no tener agente). Quién puede nombrar a quién (ADR #133, ADR #134). El agent_id queda ligado por el PRINCIPAL, con la misma regla en cada verbo que lee uno: una clave de máquina dd_ nombra a cualquier agente de su tenant; un ddw_ solo al propio; una sesión de inicio de sesión ddu_ vinculada a un puesto de agente actúa como ESE puesto: agent_id puede omitirse (se rellena con el puesto) o repetirlo, y nombrar a otro agente es 403 forbidden; una sesión ddu_ SIN puesto vinculado puede nombrar a otro agente solo con users.role = account_admin; un member recibe 403 role_forbidden, una vez que la clave de catálogo del tenant ddu_author_role_enforced está activada (nace desactivada: hasta entonces la sesión sin puesto conserva el contrato de dd_ en este verbo).

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`debt_id`	string (uuid)	sí
`contact_phone`	string	sí	E.164 de un contacto existente de la deuda.
`scheduled_at`	string (date-time)	sí	RFC 3339, al menos `callback_min_notice_seconds` del tenant (10 minutos por defecto) en el futuro.
`campaign_id`	string (uuid)	no
`agent_id`	string (uuid)	no
`note`	string	no
`priority`	integer	no

json

{
  "debt_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "contact_phone": "+13125551001",
  "scheduled_at": "2026-07-06T16:30:00Z",
  "note": "postman: consumer pidió el martes"
}

Respuestas

`201`

Rellamada programada.

Campo	Tipo	Obligatorio
`callback`	object (Callback)	sí
`callback.id`	string (uuid)	no
`callback.tenant_id`	string (uuid)	no
`callback.debt_id`	string (uuid)	no
`callback.contact_phone`	string	no
`callback.campaign_id`	string (uuid) \| null	no
`callback.agent_id`	string (uuid) \| null	no
`callback.scheduled_at`	string (date-time)	no
`callback.note`	string \| null	no
`callback.priority`	integer	no
`callback.status`	`pending` · `done` · `cancelled` · `missed`	no
`callback.created_at`	string (date-time)	no
`callback.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"
  }
}

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

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

`422` — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

json

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

`429` — ApiKeyRateLimited

json

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

pending → done

http

POST /v1/callbacks/{id}/complete

Máquina de estados pending → done|cancelled|missed (terminal); 409 ante una nueva transición.

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 rellamada completada.

Campo	Tipo	Obligatorio
`callback`	object (Callback)	sí
`callback.id`	string (uuid)	no
`callback.tenant_id`	string (uuid)	no
`callback.debt_id`	string (uuid)	no
`callback.contact_phone`	string	no
`callback.campaign_id`	string (uuid) \| null	no
`callback.agent_id`	string (uuid) \| null	no
`callback.scheduled_at`	string (date-time)	no
`callback.note`	string \| null	no
`callback.priority`	integer	no
`callback.status`	`pending` · `done` · `cancelled` · `missed`	no
`callback.created_at`	string (date-time)	no
`callback.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"
  }
}

pending → cancelled

http

POST /v1/callbacks/{id}/cancel

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 rellamada cancelada.

Campo	Tipo	Obligatorio
`callback`	object (Callback)	sí
`callback.id`	string (uuid)	no
`callback.tenant_id`	string (uuid)	no
`callback.debt_id`	string (uuid)	no
`callback.contact_phone`	string	no
`callback.campaign_id`	string (uuid) \| null	no
`callback.agent_id`	string (uuid) \| null	no
`callback.scheduled_at`	string (date-time)	no
`callback.note`	string \| null	no
`callback.priority`	integer	no
`callback.status`	`pending` · `done` · `cancelled` · `missed`	no
`callback.created_at`	string (date-time)	no
`callback.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"
  }
}

pending → missed

http

POST /v1/callbacks/{id}/miss

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 rellamada perdida.

Campo	Tipo	Obligatorio
`callback`	object (Callback)	sí
`callback.id`	string (uuid)	no
`callback.tenant_id`	string (uuid)	no
`callback.debt_id`	string (uuid)	no
`callback.contact_phone`	string	no
`callback.campaign_id`	string (uuid) \| null	no
`callback.agent_id`	string (uuid) \| null	no
`callback.scheduled_at`	string (date-time)	no
`callback.note`	string \| null	no
`callback.priority`	integer	no
`callback.status`	`pending` · `done` · `cancelled` · `missed`	no
`callback.created_at`	string (date-time)	no
`callback.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"
  }
}

Rellamadas ​

Endpoints ​

Vista de la cola de rellamadas / feed de vencidas ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

429 — ApiKeyRateLimited ​

Programar una remarcación acordada con el consumidor ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

422 — Unprocessable ​

429 — ApiKeyRateLimited ​

pending → done ​

200 ​

401 — Unauthorized ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

pending → cancelled ​

200 ​

401 — Unauthorized ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

pending → missed ​

200 ​

401 — Unauthorized ​

404 — NotFound ​

409 — Conflict ​

429 — ApiKeyRateLimited ​

Rellamadas

Endpoints

Vista de la cola de rellamadas / feed de vencidas

`200`

`400` — BadRequest

`401` — Unauthorized

`429` — ApiKeyRateLimited

Programar una remarcación acordada con el consumidor

`201`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`422` — Unprocessable

`429` — ApiKeyRateLimited

pending → done

`200`

`401` — Unauthorized

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited

pending → cancelled

`200`

`401` — Unauthorized

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited

pending → missed

`200`

`401` — Unauthorized

`404` — NotFound

`409` — Conflict

`429` — ApiKeyRateLimited