Referencia de la API

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.

Plano de control de marcación saliente con el cumplimiento primero: la superficie /v1 autenticada.

Referencia formal de la API del plano de control /v1 que sirve Dialer.API.Router (Bandit, puerto 4000). Fuente de verdad: lib/dialer/api/v1_router.ex (superficie del tenant), lib/dialer/api/admin_router.ex (superficie de administración de la plataforma), lib/dialer/api/auth_router.ex (inicio de sesión del dashboard y recuperación de contraseña: la única superficie /v1 sin autenticación) y lib/dialer/api/sms_webhook_router.ex (webhooks públicos de SMS, descritos bajo webhooks). La CI hace cumplir tools/check_openapi_drift.py: cada ruta de los routers debe aparecer aquí (método + ruta) y viceversa, y info.version debe ser igual a la @version de mix.exs.

Convenciones

• JSON de entrada / JSON de salida. Los cuerpos de petición de más de 8 MiB se rechazan.
• Los errores usan siempre el sobre {"error": {"code": "...", "message": "..."}}. Ramifica por code (legible por máquina), nunca por message.
• Cada respuesta lleva X-Request-ID (el tuyo se propaga cuando es razonable).
• Las marcas de tiempo son RFC 3339 / ISO-8601 (UTC). Las horas del día son HH:MM:SS.
• Los campos decimales (ratios de ritmo, umbrales) se renderizan como cadenas JSON.

Multi-tenencia y semántica del 404

Cada ruta se ejecuta con el tenant resuelto a partir de la clave bearer; todo el acceso a datos pasa por la seguridad por filas (RLS) de Postgres. La API nunca acepta un id de tenant de la ruta, la consulta ni el cuerpo. Los ids de otro tenant se leen como 404 not_found porque la RLS devuelve cero filas: nunca se filtra la existencia (no hay 403 para ids ajenos), y los ids mal formados (que no son UUID) dan el mismo 404.

Límites de uso (por clave de API, por persona)

Cada clave de API dd_ tiene su propia cuota de peticiones en /v1: dos claves del mismo tenant nunca comparten presupuesto. Es una asignación deslizante (GCRA), por nodo, con una ráfaga equivalente a un minuto. El valor por defecto es generoso y un ajuste de operador por tenant (api_key_requests_per_minute) lo modifica. Los carriles de consola (ddu_) y de agente (ddw_) también se cuentan, con el mismo algoritmo y su propio ajuste (session_requests_per_minute): el cubo pertenece a la persona (el agente, si no el usuario), no a la sesión, así que volver a iniciar sesión no compra un presupuesto nuevo, y otra persona del mismo tenant no se ve afectada. Cada respuesta a una petición contada lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; por encima de la cuota la respuesta es 429 rate_limited con Retry-After y la petición no se procesa. Exentos: POST /v1/calls/{call_id}/hangup, los webhooks y las rutas de salud. Una petición rechazada por la cuota no se vuelve a contar, así que esperar Retry-After segundos siempre basta.

Errores canónicos

• 401 unauthorized: clave de API ausente/desconocida/revocada. 403 forbidden: tenant suspendido.
• 404 not_found: id desconocido, mal formado o de otro tenant (RLS; véase arriba).
• 422 compliance_blocked: el motor de cumplimiento rechazó la operación; el cuerpo lleva gate (qué compuerta rechazó) y decision_id (citable contra la cadena de auditoría). NO reintentes sin cambios: el bloqueo es evidencia, no un error.
• 429 rate_limited: la cuota de peticiones por clave de API (abajo), o uno de los frenos de peticiones de ventana fija (inicio de sesión, segundo factor, tokens de widget, control de llamadas, disposiciones, invitaciones). Estos llevan Retry-After: segundos enteros hasta que un reintento pueda tener éxito. La cuota lleva además X-RateLimit-*.
• 429 sms_spend_cap_exceeded: freno del presupuesto de SMS del mes hasta la fecha; reintentable solo tras subir el tope o tras el cambio de mes. 429 throttled: freno de tasa; reintenta más tarde con espera creciente. Ninguno lleva Retry-After: el motor no sabe cuándo vuelve la capacidad, y un número inventado es peor que ninguno.
• 502 provider_error / 502 dial_error / 502 sbc_error: un servicio ascendente (proveedor de SMS, switch, borde SIP) rechazó la operación.

Fuera de alcance aquí (documentado en API.md): GET /healthz (sin autenticación), el websocket del piso en vivo GET /v1/ws (se actualiza antes de este pipeline; autenticación mediante un ?ticket= efímero de un solo uso emitido por POST /v1/ws/ticket, nunca un bearer de larga duración), y GET /metrics (Prometheus, puerto 9568).

Recursos

Recurso	Endpoints	Descripción
Rastreo de contacto (skip trace)	3	Rastreo de contacto (F0): una consulta medida a un proveedor, detrás de un tope mensual por tenant con corte duro. Todavía no genera línea de factura.
Identidad	22	Tenant autenticado, ajustes de la cuenta.
Autenticación	16	Inicio de sesión en el dashboard (email + contraseña -> una sesión ddu_ revocable; sha256 en reposo, texto plano mostrado una sola vez) y recuperación de contraseña (un enlace de un solo uso que caduca — la mitad de la petición nunca revela si una dirección tiene cuenta).
SSO	11	Inicio de sesión único SAML 2.0 por tenant: la configuración del proveedor de identidad del tenant (cargada por un account_admin, auditada de solo anexado) y los metadatos del proveedor de servicio que necesita el administrador de su IdP. Solo iniciado por el SP; la persona ya debe existir en el tenant (sin aprovisionamiento just-in-time).
Acceso de soporte	4	Acceso del soporte de la plataforma (ADR 225): el consentimiento del cliente (una concesión con un motivo y una caducidad fija, una viva por tenant, revocable a voluntad) y su registro de solo anexado. Solo account_admin, salvo el banner.
Usuarios	6	Cuentas de usuario del dashboard (email + contraseña; se deshabilitan, nunca se eliminan).
Claves de API	4	Claves de API por tenant (sha256 en reposo; texto plano mostrado una vez).
Widgets	11	Ciclo de vida del widget de agente incrustable: tokens de navegador ddw_ y lista de orígenes permitidos.
Click to call	7	Click-to-call para el sitio web del cliente (ADR 220): la consola emite y revoca una clave de sitio PUBLICABLE ddc_, y el navegador del visitante la usa para leer la configuración del formulario y dejar una solicitud de llamada. Controlado por click_to_call_enabled.
Campañas	28	CRUD de campañas, ciclo de vida, marcación manual y rebobinado.
Deudas y leads	10	Importación masiva de leads, detalle de deuda, CDR por deuda, paquete de defensa.
Consumidores	1	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.
Listas de deudas	10	Listas reutilizables de deudas, asociadas a campañas (ADR #162).
Mapeos de importación	8	Plantillas de importación CSV (mapeo columna -> campo y opciones de análisis), versionadas de sólo anexado por tenant.
Gestión de calidad (QM)	16	Formularios de puntuación de gestión de calidad (ADR #217), versionados de sólo anexado por tenant. Las escrituras requieren el indicador qm_enabled.
Insights	3	Evidencia de anomalías del evaluador de insights (core#1983): series de contacto, abandono, coste, bloqueo por compuerta y timeout de medios, cada anomalía con su serie y su umbral. Siempre activo; insights_anomaly_k sólo ajusta la sensibilidad.
Analítica de producto	3	Analítica de producto y NPS dentro de la consola, propios y sin terceros (macro-tasks#876): eventos de uso como claves de un catálogo cerrado, y la pregunta de NPS para los administradores de la cuenta. Siempre activa; nunca lleva datos de un consumidor.
Guiones de divulgación	4	Biblioteca de guiones de aviso de cobranza (ADR #219): versiones inmutables por tenant, aprobadas mediante un evento sellado.
Filtros de segmento	7	Filtros de segmentación guardados (los criterios de GET /v1/debts con un nombre), versionados sólo-anexado por tenant. Detrás del indicador debt_segmentation_enabled (ADR #221).
Intentos de llamada (CDR)	4	Consulta del CDR de solo anexado + disposiciones tipadas.
Rellamadas	5	Citas de remarcación acordadas con el consumidor.
Reglas de disposición	5	La política de reintentos del tenant según el resultado de la llamada (R10): reprogramar o suprimir una deuda tras una disposición dada. Solo puede posponer o cerrar una deuda; cada marcación sigue pasando por las compuertas de cumplimiento en el momento del originate.
Disposiciones	1	El conjunto de contrato dialer.v1.Disposition en grafía REST: el valor en minúsculas, el nombre de su enum y su número.
Promesas de pago	2	Pipeline de promesas de pago.
Agentes y puestos	20	Lista de puestos, presencia, check-in/check-out del softphone.
Wfm	1	Gestión de la fuerza laboral: la cobertura por intervalo de un día (pronóstico a partir del CDR, agentes requeridos según Erlang C frente al objetivo de servicio del tenant, agentes planificados en turnos R11). Una lectura derivada; no se persiste nada.
Academia	3	Registros de formación de la Academia dentro de la app: la constancia auditable (quién completó qué y cuándo), de solo anexar y por agente.
Supervisión	4	Audio de supervisor (escuchar/susurrar/intervenir/tomar el control), con evidencia primero.
Llamadas	13	Verbos de control de llamadas en vivo (hold/unhold/mute/unmute/hangup), con evidencia primero.
Destinos de transferencia	5	El registro del tenant de los números externos a los que se puede transferir una llamada en curso.
Segmentos de rebobinado	4	Conjuntos con nombre de filtros de rebobinado que un supervisor guarda por tenant y reutiliza (los filtros, nunca una lista de cuentas).
Estadísticas y uso	9	Contadores operativos, resúmenes de marcaciones bloqueadas, medición de uso.
Facturación	9	Líneas facturables.
Informes	10	Artefactos de cumplimiento empaquetados.
Cumplimiento	5	Datos de supresión que posee el tenant (su lista interna de no llamar, subida como CSV a la misma lista que lee la compuerta previa al marcado) y la cita de la cadena de auditoría: resolver un decision_id en su eslabón sellado más el veredicto de integridad sobre él.
DID (identificadores de llamada)	11	Registro de DID, salud calculada a partir del CDR, lista de verificación de lanzamiento y tickets del carrier.
Carriers (troncales SIP)	8	Registro de troncales SIP (BYOC/house) + aprovisionamiento del SBC.
SMS	12	Envío puntual de SMS con compuertas + libro mayor unificado.
Proveedores de SMS	5	Registro de enrutamiento de SMS por tenant/región.
Email	6	Direcciones de email de los deudores con su procedencia, el libro de supresiones (lectura) y el libro de emails (lectura).
Proveedores de email	5	Registro de proveedores de email por tenant/región (SMTP / log).
Plantillas de email	6	Plantillas de email por tenant (asunto estático + cuerpo con variables tipadas), versiones de solo anexar, aprobación y retirada por account_admin.
Plantillas de SMS	8	Plantillas de SMS por tenant con variables tipadas, aprobación y el ajuste «solo plantillas».
Webhooks	8	Webhooks de salida para CRM: el registro de endpoints del tenant, sus eventos suscritos y el secreto de firma (se muestra una vez; rotación con ventana).
Rutas entrantes	6	Enrutamiento de DID entrantes + aprovisionamiento del SBC.
Menús IVR entrantes	4	Los menús IVR entrantes del tenant: versiones publicadas, historial de solo anexar, convertidos en audio al publicarse. Una ruta entrante con dest_type: ivr ejecuta uno de ellos.
Colas entrantes	15	Las colas entrantes del tenant: se crean con un nombre, un desborde opcional hacia otra de sus colas, y se retiran cuando nada las usa. Una ruta con dest_type: queue nombra una en queue_id; un menú IVR entrante nombra una como queue:<id>.
Grabaciones	23	Evidencia de grabación de llamadas: metadatos con retención bloqueada, reproducción firmada, retención legal, exportación masiva, política por tenant.
IA de voz	25	Agentes de IA de voz: constructor + política versionada, conversaciones en vivo, transcripciones/resultados, toma de control por el supervisor, el interruptor de emergencia de la marcación por IA por tenant y las métricas de hoy.
WebSocket	1
Endpoints de webhook	3	De cara al proveedor, autenticados por firma (sin bearer).