Inicio rápido alojado: del registro al primer webhook

English version: Hosted quickstart — sign up to first webhook.

Esta guía te lleva de ninguna cuenta a tu primera llamada simulada y tu primer webhook firmado, contra la API alojada y con una clave de prueba. Una clave de prueba nunca llega a un operador, un teléfono, un proveedor de SMS ni un buzón, y nada de lo que hace se mide ni se cobra. El recorrido contra el stack local, que hace intentos reales con puerta de cumplimiento, es el Inicio rápido.

https://api.usa.dialerdigital.com    # hosted API (USA cell)

Vas a: registrarte → fijar tu contraseña → iniciar sesión → crear una clave dd_test_ → simular una llamada → recibir el webhook call.ended → leer el registro de prueba.

Listo para copiar y pegar

Cada paso es un curl ejecutable; jq captura valores en variables de shell. Ramifica por error.code, nunca por message: ver el índice de errores.

Paso 1 — Regístrate

El registro es público y anónimo. Primero lee lo que necesita el formulario: la versión de los términos vigente y la clave pública del antibot:

API=https://api.usa.dialerdigital.com
curl -s $API/v1/signups/config
# -> {"available":true,"terms_version":"...","captcha":{"provider":"turnstile","site_key":"..."}}

available: false significa que el registro está cerrado en esta celda. Si no, resuelve el widget de Cloudflare Turnstile (con ese site_key) en un navegador para obtener un captcha_token y regístrate:

curl -s -X POST $API/v1/signups \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "name": "Ada Developer",
    "terms_version": "<terms_version from the config>",
    "captcha_token": "<token from the widget>",
    "locale": "en"
  }'
# -> {"status":"accepted"}

La respuesta es 202 accepted tanto si la dirección es nueva, está pendiente o ya está registrada: nunca te dice cuál, para que nadie pueda sondear cuentas. Una dirección nueva o pendiente recibe un correo con un enlace de un solo uso (un enlace nuevo invalida el anterior); una dirección que ya pertenece a una persona recibe un aviso de «ya tienes una cuenta», sin enlace. Hasta que lo canjees no hay clave, ni persona, ni sesión, y el plan de la cuenta es draft: todo lo que gasta o hace una llamada real responde 402 plan_inactive.

Rechazos que puedes encontrar: 422 terms_version_mismatch, 403 captcha_failed, 429 signup_rate_limited (espera Retry-After), 503 signup_unavailable / 503 captcha_unavailable (no se creó nada).

Paso 2 — Fija tu contraseña

El enlace del correo lleva un token (ddr_…). Canjéalo con la contraseña que elijas (de 12 a 128 caracteres):

curl -s -X POST $API/v1/auth/password-reset/confirm \
  -H "Content-Type: application/json" \
  -d '{"token": "<token from the link>", "new_password": "<your password>"}'
# -> {"status":"ok"}

Canjear el enlace verifica la dirección y crea a tu persona en el mismo paso. Un token malo, caducado o ya usado es un único 401 indistinguible.

Paso 3 — Inicia sesión

SESSION=$(curl -s -X POST $API/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "password": "<your password>"}' | jq -r .token)

Esto crea una sesión ddu_ del panel. Si la cuenta tiene un segundo factor activo, la respuesta es mfa_required: true más un challenge que se canjea antes en POST /v1/auth/mfa/verify. Ver Autenticación.

Paso 4 — Crea una clave de prueba

El registro público entra como member

Quien se registra por el alta pública entra como member. Crear una clave exige account_admin, y hoy ese rol sólo lo concede un operador de la plataforma (no hay ruta en la API). Hasta entonces POST /v1/api_keys responde 403 role_forbidden.

Con una sesión account_admin, pide environment: "test":

TOKEN=$(curl -s -X POST $API/v1/api_keys \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"label": "quickstart", "environment": "test"}' | jq -r .token)
echo $TOKEN    # dd_test_… — shown ONCE

El token se muestra una sola vez; guárdalo. El entorno queda fijo al crearla. Una clave de prueba autentica y lee como una real, pero toda ruta que marca de verdad, compra o aprovisiona responde 403 test_environment.

Paso 5 — Registra un endpoint de webhook

Suscribe un endpoint HTTPS (puerto 443, host público) a los eventos de llamada. El secreto se muestra una sola vez:

curl -s -X POST $API/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/dialerdigital", "events": ["call.answered", "call.ended"]}'
# -> {"webhook":{"id":"...","enabled":true,...},"secret":"whsec_..."}

Verifica las firmas como se describe en Webhooks de salida. Para comprobar tu receptor antes de cualquier llamada, POST /v1/webhooks/{id}/test envía ahora un evento webhook.test firmado y responde con lo que contestó tu endpoint.

Paso 6 — Simula una llamada

Con una clave de prueba, POST /v1/dial/manual responde un resultado simulado determinista que elige el destino; ver límites y números de prueba:

curl -s -X POST $API/v1/dial/manual \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"number": "+13125550100"}'
# -> {"status":"dialing","call_id":"..."}

Tu endpoint recibe call.answered y call.ended, firmados con X-DD-Signature como una entrega real, con livemode: false y environment: "test" en el sobre.

Paso 7 — Lee el registro de prueba

Las llamadas y SMS simulados viven aparte de tu CDR real (/v1/reports/cdr nunca los incluye):

curl -s "$API/v1/sandbox/records?kind=call&limit=5" -H "Authorization: Bearer $TOKEN"
# -> {"environment":"test","records":[{"kind":"call","to_number":"+13125550100","outcome":"answered","status":"completed",...}]}

Solución de problemas

Síntoma	Causa probable / arreglo
422 unknown_test_number	El destino no es uno de los cuatro números de prueba.
403 test_environment	La ruta llega a un operador, proveedor o credencial; una clave de prueba no puede usarla.
403 role_forbidden al crear la clave	Tu sesión es member (todo registro público empieza así); sólo un operador de la plataforma puede conceder account_admin.
402 plan_inactive	Una llamada o envío real en una cuenta con el plan inactivo; las claves de prueba no pasan por ese camino.
429 rate_limited	Cuota por clave: ver límites de uso.

Siguientes pasos

• Guía: llamadas y SMS · números · voz IA · facturación
• Límites y números de prueba
• Índice de errores