API y webhooks de Call para desarrolladores: claves, scopes, eventos
Recorrido práctico por la API REST de Call: claves de API y scopes, límites de peticiones, gestión de errores, webhooks firmados y la página Desarrolladores.
Tarde o temprano, un sistema telefónico tiene que comunicarse con otra cosa: un CRM que debe mostrar una llamada en cuanto termina, una herramienta de facturación que quiere saber quién llamó, un script que hace una llamada cuando se envía un formulario. Call tiene una API REST y webhooks salientes precisamente para esto. Esta guía explica cómo encajan las piezas, qué pedir antes de escribir código y los errores que con más frecuencia le cuestan una tarde a un desarrollador.

Si solo quieres mover contactos de forma masiva, lee primero Importar contactos en el CRM de un equipo telefónico; una importación suele ser más sencilla que una integración.
Por dónde empezar: la referencia y la página Desarrolladores
Hay dos lugares que conviene conocer. La Referencia de la API está en Configuración y también en el menú Recursos de la página de inicio. Se puede leer sin iniciar sesión, algo práctico cuando estás definiendo el alcance de un trabajo para un cliente. La página Desarrolladores, también en Configuración, es para tu propio espacio de trabajo: muestra los identificadores de tu organización y de tus agentes, tus endpoints de webhook y una lista de solo lectura de tus claves.
Qué te ofrece cada lugar
- Empieza aquíURL base y convenciones, autenticación con una tabla de scopes, y errores con sus códigos de estado.
- EndpointsCada tarjeta de endpoint indica su scope, parámetros, cuerpo de la petición, respuesta y errores, con peticiones listas para copiar en curl, JavaScript y Python.
- BúsquedaPulsa / para ir a Buscar endpoints y filtrar por método, ruta, scope o resumen.
- OpenAPI JSONDescarga toda la especificación en un único archivo para tus propias herramientas.
- ID de agente / APIEl ID y el slug de tu organización, el modo de la API (Entorno de pruebas o En directo) y el ID del agente de IA que elijas, cada uno con un botón Copiar.
- WebhooksTus endpoints, los eventos que recibe cada uno, el último estado HTTP y las entregas fallidas.
Lee las secciones sobre límites de peticiones y webhooks salientes antes de pasar a producción, no después. Describen un comportamiento que es fácil pasar por alto en una prueba rápida.
Claves de API y scopes
Cada petición lleva una clave en una cabecera Authorization como token bearer. Las claves no se crean en la aplicación: las emite el operador de tu espacio de trabajo y te indica qué scopes tienen. La clave completa se muestra una sola vez, en el momento de emitirla, y después solo aparecen sus primeros caracteres, así que guárdala enseguida en tu propio almacén de secretos.
| Scope | Qué permite |
|---|---|
| read | Leer contactos, llamadas, colas, miembros del equipo, informes y la lista de no llamar. |
| write | Crear y actualizar contactos, registrar resultados de llamadas y añadir números a la lista de no llamar. |
| calls | Hacer y finalizar llamadas. |
| admin | Gestionar webhooks; también puede llamar a todos los demás endpoints. |
Pide el conjunto mínimo que cumpla tu objetivo. Un script de informes solo necesita read; un botón de clic para llamar necesita calls. Si una petición devuelve un 403 con el código insufficient_scope, a la clave le falta el scope que aparece en la tarjeta de ese endpoint.
Entorno de pruebas y producción
Las claves se pueden emitir para un entorno de pruebas, que usa un simulador y no hace llamadas reales, o para uso en directo. Trata el prefijo de una clave solo como una etiqueta: una clave etiquetada como de prueba funciona con los mismos datos y la misma conexión telefónica que una en directo, así que no confíes en el prefijo para mantener los experimentos lejos de los clientes reales. Usa el modo de la API que aparece en la página Desarrolladores para saber dónde estás.
Hacer llamadas a través de la API
Los endpoints públicos cubren lo básico: una comprobación de estado, listar llamadas, leer una llamada, hacer una llamada, colgar, gestionar webhooks y chatear con un agente de IA. Una llamada saliente hecha a través de la API pasa la misma comprobación de cumplimiento normativo que una llamada hecha desde el puesto, así que un número que está en la lista de no llamar o fuera del horario de llamadas permitido se rechaza, exactamente igual que para un agente. Diseña tu código para tratar ese rechazo como un resultado normal, no como un fallo.
Esto importa para el diseño. No escribas un bucle que reintente una llamada rechazada hasta que funcione. Lee el motivo, regístralo y sigue adelante. Para las normas que hay detrás de esos rechazos, consulta El control de horarios de llamada en Call y La lista de no llamar en Call.
Límites de peticiones y errores
Cada clave tiene su propio límite de peticiones por minuto, fijado al emitirla; el valor predeterminado es 120. Cuando una clave agota el minuto, la API responde 429 con el código rate_limited e indica cuánto esperar en la cabecera X-RateLimit-Reset. Espera ese tiempo y continúa. Un cliente educado frena antes de chocar contra el límite.
- 429 rate_limited: espera el periodo que indica la cabecera de reinicio y reparte el trabajo masivo en el tiempo.
- 403 insufficient_scope: a la clave le falta el scope que aparece en la tarjeta de ese endpoint; solicita una clave que lo tenga.
- Otros errores: actúa según el código de error, no según el mensaje. Los códigos no cambian; la redacción puede cambiar.
Gestionar una petición fallida
- Lee el estado¿Es un error del cliente que puedes corregir o un error del servidor que merece un reintento?
- Lee el códigoBifurca según el código, nunca según el texto del mensaje.
- EsperaPara un 429, espera lo que indica la cabecera de reinicio; para errores del servidor, reintenta unas pocas veces con esperas crecientes.
- Registra el detalleGuarda el endpoint, el código y la hora para que el soporte pueda rastrearlo.
- Detente ante los rechazosUn rechazo por cumplimiento normativo es una decisión, no un fallo pasajero; no lo repitas en bucle.
Webhooks: recibir eventos
En lugar de preguntar a la API una y otra vez si ha pasado algo, deja que Call te avise. En la página Desarrolladores, pulsa Añadir endpoint, introduce una dirección https pública y marca los eventos que quieras; si no marcas ninguno, recibirás todos. El secreto de firma se muestra una sola vez, al añadir el endpoint. Cópialo en ese momento. Si lo pierdes, elimina el endpoint y vuelve a añadirlo para obtener uno nuevo.
Cada entrega va firmada. La cabecera de firma contiene un HMAC-SHA256 de la marca de tiempo y el cuerpo unidos por un punto, calculado con tu secreto de firma, y otra cabecera lleva la marca de tiempo. Vuelve a calcularlo por tu parte y compáralo antes de confiar en el contenido. La referencia de la API incluye código de ejemplo para esto en Node.js y Python, y rechazar las marcas de tiempo antiguas te protege frente a peticiones reenviadas.
Un receptor de webhooks bueno y uno deficiente
| Bueno | Deficiente | |
|---|---|---|
| Firma | Verificada en cada petición | Aceptada sin comprobar |
| Respuesta | 2xx en segundos, con el trabajo en cola para después | Procesamiento lento antes de responder |
| Duplicados | Recibir el mismo evento dos veces no causa problemas | Crea dos registros |
| Fallos | Avisa cuando fallan las entregas | Silencio hasta que alguien se da cuenta |
Tu endpoint debe responder con un estado 2xx en un máximo de 10 segundos. Una entrega fallida se reintenta, hasta seis intentos en total, y un endpoint que falla 50 veces seguidas se desactiva. Cada fila de la página Desarrolladores muestra el último estado HTTP y cuántas entregas fallaron, y Enviar prueba lanza un evento de prueba firmado para que veas qué responde tu servidor.
Lista para pasar a producción
Antes de activar una integración
- Sabes qué scopes tiene la clave, y no tiene más de los necesarios
- La clave está guardada en un almacén de secretos, no en el código fuente
- Las firmas de los webhooks se verifican y se rechazan las marcas de tiempo antiguas
- El receptor responde rápido y gestiona los eventos duplicados
- Las respuestas de límite de peticiones y de rechazo se gestionan sin bucles de reintento rápidos
- Has probado en modo de entorno de pruebas y has pulsado Enviar prueba en el endpoint
- Hay una persona designada para recibir una alerta si las entregas empiezan a fallar
Cómo hacerlo en Call
En Call, abre Configuración y después Referencia de la API para estudiar los endpoints, y Configuración y después Desarrolladores para copiar el ID de tu organización, revisar tus claves y añadir un webhook. Los propietarios, administradores y responsables pueden añadir, probar y eliminar endpoints; el resto ve la lista. Si también usas las funciones de agente de IA, el ID de agente de la misma página alimenta el endpoint de chat. Para la parte de voz del producto, consulta Configurar un agente de IA en Call.
Preguntas frecuentes
¿Cómo obtengo una clave de API?
Las claves las emite el operador de tu espacio de trabajo; no se pueden crear en la aplicación. Pide una e indica qué scopes necesita. La clave completa se muestra una sola vez, al emitirla.
¿Qué significa una respuesta 429?
La clave ha agotado sus peticiones del minuto en curso. Espera los segundos que indica la cabecera X-RateLimit-Reset, vuelve a intentarlo y reparte el trabajo masivo en un periodo más largo.
¿Cómo compruebo que un webhook procede realmente de Call?
Calcula un HMAC-SHA256 de la marca de tiempo y el cuerpo con tu secreto de firma y compáralo con la cabecera de firma. La referencia de la API muestra ejemplos en Node.js y Python.
¿Puedo enviar webhooks a un servidor de desarrollo local?
No directamente. Los endpoints deben ser direcciones https públicas, así que usa una herramienta de túnel que exponga tu servidor local en una de ellas.
¿Por qué se rechazó mi llamada a la API para hacer una llamada?
Las llamadas hechas a través de la API pasan la misma comprobación de cumplimiento normativo que las llamadas desde el puesto. Se rechaza un número que está en la lista de no llamar o fuera del horario de llamadas.
¿Quién puede ver y cambiar los webhooks?
Todo el mundo puede leer la lista, pero solo los propietarios, administradores y responsables pueden añadir, probar o eliminar endpoints.