Referencia de la API — Resumen

English version: API Reference — Overview.

La API de Dialer Digital es el mismo plano de control sobre el que corre nuestro propio dashboard: campañas, importación de leads, registros de llamadas, SMS, promesas, callbacks, agentes, supervisión, facturación y evidencia de cumplimiento — todo bajo /v1, todo JSON.

También es compliance-first por construcción. Cada marcación y cada SMS pasa por el mismo motor con compuertas, venga de una campaña, del dashboard o de tu llamada a la API. No existe un endpoint de «envío en bruto» que se pueda usar mal — consulta Errores y cumplimiento.

Por dónde empezar

Página	Qué obtienes
Autenticación	Claves API bearer, rotación y semántica de 401/403.
Errores y cumplimiento	El sobre de error, y por qué 422 compliance_blocked es una virtud.
Webhooks	Verificación de firmas paso a paso, con ejemplos ejecutables.
Gestión de calidad	Formularios de puntuación, evaluaciones, disputas y reportes; apagado por defecto tras qm_enabled.
Límites de uso y topes	Los frenos 429 y los topes mensuales de gasto que mantienen las facturas predecibles.
Seguridad de la cuenta	Política de acceso por IP y horario, acceso de soporte auditado y sesión única.
Referencia de endpoints	Cada endpoint, generado desde la especificación OpenAPI — parámetros, esquemas, ejemplos (en inglés).

URL base

https://api.usa.dialerdigital.com     # US region ingress

Todas las peticiones usan HTTPS y llevan una clave API bearer (salvo los endpoints de webhook firmados y la sonda de vida sin autenticación GET /healthz).

El recorrido de 60 segundos

API=https://api.usa.dialerdigital.com
TOKEN=dd_your_api_key_here            # yours is issued at onboarding — this is not a real key

# Who am I? (validates the key, returns your account + plan + caps)
curl -s $API/v1/me -H "Authorization: Bearer $TOKEN"

# List campaigns
curl -s $API/v1/campaigns -H "Authorization: Bearer $TOKEN"

# Pull call records (append-only CDR, keyset-paginated)
curl -s "$API/v1/call_attempts?from=2026-07-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $TOKEN"

Convenciones

• JSON de entrada, JSON de salida. Los cuerpos de petición de más de 8 MiB se rechazan.
• Un único sobre de error en todas partes: {"error": {"code": "...", "message": "..."}}. Ramifica por code, nunca por message — detalles en Errores y cumplimiento.
• X-Request-ID en cada respuesta (se propaga el tuyo si está bien formado). Cítalo en los tickets de soporte.
• Marcas de tiempo en RFC 3339 / ISO-8601 en UTC (2026-07-01T14:30:00Z); las horas del día son HH:MM:SS.
• Decimales como cadenas: las razones de ritmo y los umbrales se entregan como cadenas JSON para evitar la deriva de los flotantes.
• Paginación por claves (keyset): pasa limit (100 por defecto, 1000 como máximo) y el next_cursor de la página anterior.
• Versionado en la ruta (/v1). Los cambios aditivos llegan dentro de v1; un cambio incompatible abriría /v2.

Tenencia y aislamiento de datos

Tu clave API es la identidad de tu cuenta — no hay cabecera, segmento de ruta ni campo de cuerpo con el id del tenant, así que no hay nada que falsificar. En el servidor, cada consulta corre bajo seguridad a nivel de fila (row-level security) de PostgreSQL: el id de un recurso de otra cuenta responde 404 not_found, indistinguible de un id inexistente. Nunca se filtra la existencia.

Cómo se construye esta referencia

La referencia de endpoints está generada, no escrita: en la compilación, un script la renderiza a partir de la especificación OpenAPI 3.1 que publica el servicio core (openapi/dialer-v1.yaml). El CI de core impone una compuerta de deriva bidireccional — cada ruta de los routers en ejecución debe aparecer en la especificación, y viceversa — así que la referencia no puede divergir en silencio del código.

Cada página generada muestra el commit exacto de core desde el que se renderizó, y la especificación se puede descargar en /openapi/dialer-v1.yaml.