Primeros pasos con la API, el Playground y los webhooks
Encuentra tu clave API, realiza una primera petición segura y conecta notificaciones sin exponer credenciales.
Utiliza la referencia API actual
Con la sesión iniciada, abre la documentación API. Incluye los endpoints disponibles, campos obligatorios y ejemplos. Úsala para los detalles de las peticiones; esta guía explica el proceso sin duplicar la especificación.
Prepara tu clave
Sigue la verificación de identidad para ver o copiar la clave. La documentación permite cinco minutos de acceso verificado para consultar la clave y usar el Playground; generar o regenerar una clave requiere otra verificación. Trátala como una contraseña: guárdala en el servidor de tu aplicación, nunca en repositorios públicos, código del navegador ni capturas.
Realiza una primera petición segura
- Abre el Playground y elige una plantilla de solo lectura adecuada para tu cuenta, como listar identidades SIP.
- Revisa método, ruta y parámetros. Utiliza los identificadores devueltos para tu cuenta, no los valores de ejemplo.
- Selecciona Run request y revisa tanto el estado HTTP como el cuerpo de la respuesta.
- Utiliza el ejemplo documentado en tu aplicación y almacena las credenciales de forma segura.
El Playground usa tu cuenta. Las peticiones que envían mensajes, realizan llamadas o contratan servicios pueden ejecutar acciones reales y generar cargos. No lo trates como un entorno de pruebas gratuito.
Añade notificaciones webhook
En las integraciones de la cuenta, añade un endpoint HTTPS y selecciona los eventos necesarios. El secreto de firma del webhook es independiente de la clave API. Verifica las firmas, procesa cada evento una sola vez y confirma la recepción rápidamente. Consulta los registros de entrega para diagnosticar problemas. Antes de repetir una operación de pago, lee las reglas de reintentos y peticiones duplicadas; un timeout por sí solo no demuestra que haya fallado.
Guías relacionadas
Elige la referencia del servicio adecuado
La referencia separa Lookup, Pricing, SIP, SMS, Contacts, Speech API, Phone Numbers, Voice API y Calls & recordings. Consulta cada endpoint para conocer los requisitos, campos y cargos exactos. Las llamadas desde el navegador tienen su propia guía del Webphone SDK; no son lo mismo que el control de llamadas Voice API desde el servidor.
El permiso de un agente para leer la documentación no da acceso a la clave del propietario ni a ejecutar el Playground con ella. Pide al propietario que gestione las credenciales de integración en lugar de compartir su sesión.
Utiliza las referencias devueltas y la paginación
Trata las referencias públicas como valores opacos: copia la referencia CALL- completa de tu respuesta en vez de construirla o usar un identificador interno de telefonía. Las llamadas históricas y activas son listas distintas. Una acción de control requiere además un estado compatible; una fila del historial no tiene por qué poder controlarse.
Para el historial, sigue pagination.next_cursor mientras pagination.has_more sea verdadero. Mantén los filtros originales days, limit e identidad SIP. No decodifiques ni modifiques el cursor. Si caduca, inicia una lista nueva y concilia por referencia pública. Una marca temporal documentada en UTC debe convertirse expresamente para mostrarla; no es automáticamente la hora local del navegador.
Gestiona errores sin duplicar operaciones de pago
Lee el estado HTTP junto con el error estructurado. Corrige errores de validación o autorización antes de reintentar. Respeta la espera documentada para límites de frecuencia. Ante un timeout o error temporal en una operación de pago, comprueba su estado y las reglas de duplicados del endpoint antes de reenviar; cambiar identificadores puede convertir el reintento en una operación nueva. Guarda para soporte la referencia pública, la hora y el error sin datos sensibles, nunca la clave API.