Documentación

Su central en cinco minutos

Todo lo de aquí abajo ya existe en su cuenta. Nada necesita un instalador, la visita de un técnico ni un aparato que haya que comprar.

• Ya tiene números y extensiones. Se crean con su cuenta, junto con las credenciales que necesita cada aparato. Una extensión es una persona o un puesto; un número es lo que marca la gente de fuera.
• Apunte un número a algún sitio. En la pestaña de Números dice qué debe hacer una llamada que entre por ahí: timbrar una extensión, timbrar un grupo, abrir un menú, entrar en una cola o seguir su horario.
• Contéstela desde el navegador. Abra la pestaña Teléfono, dé permiso al micrófono y esa pestaña es un aparato que funciona. Llame a la prueba de eco marcando *43 y se oirá a usted mismo de vuelta.
• Y después ponga su horario y su buzón. Esos dos son los que impiden que una llamada se pierda a las siete de la tarde, y son las dos cosas que más suelen faltarle a una central recién estrenada.

¿Con prisa? Hay cinco plantillas de arranque —un consultorio, un bufete, un taller, una tienda y una casa— que crean el horario, la ruta de entrada y el buzón de fuera de horario en una sola petición. Nunca pisan algo que usted ya haya configurado.

Cómo se entra al panelpor la API

El panel vive en su página de VOICE y sólo aparece con una sesión. Esa sesión la emite su área de cliente; aquí no se teclea nada.

Para quien construya ese botón, éste es el contrato entero:

POST /inquilinos/:inquilino/sesiones     # ámbito sistema: sólo el portal puede emitirla
{ "minutos": 15 }
→ { "clave": "pbx_ses_…", "caduca": "…", "ambito": "sesion", "minutos_max": 60 }

/central-telefonica#t=<clave>&exp=<ISO>&v=<inquilino>

La credencial viaja en el fragmento y no en la consulta a propósito: un fragmento no se manda nunca a un servidor, así que no acaba en una cabecera Referer, ni en un registro de accesos, ni en un intermediario del camino. Caduca en minutos, tiene techo, y no puede fabricar una clave permanente.

El panel, pestaña a pestañapor la API

16 secciones, las mismas 16 en los ocho idiomas. Todo lo que hay aquí existe también en la API.

El teléfono dentro del navegadorllamada real

Una pestaña es un aparato. Sin instalar nada, sin comprar un teléfono de escritorio y sin portar ningún número: es una extensión de su propia central, registrada desde el navegador.

• Es una extensión de verdad. El navegador se registra contra su central igual que un teléfono de escritorio, y el audio va cifrado. Quien llame a su número puede llegar a la pestaña, y la pestaña puede llamar hacia fuera.
• La pestaña tiene que estar abierta. Una pestaña cerrada es un teléfono desenchufado. Ése es el límite honesto de un teléfono en el navegador, y la razón de que acompañe a un aparato de escritorio en vez de sustituirlo en todos lados.
• Ve quién está en llamada.llamada real Las luces de sus compañeros se actualizan en vivo —libre, timbrando, hablando—, así que sabe si hay a quién pasarle la llamada antes de intentar pasársela.
• Puede mover una llamada viva a otro aparato.aún sin ejercitar «Me tengo que ir y estoy hablando»: la llamada se pasa a su celular sin colgar. Es un botón y no un código de teclado a propósito — quien mueve una llamada tiene una pantalla delante.
• Transferir, aparcar y grabar son los mismos códigos que en cualquier aparato. Se marcan, no se pulsan, así que lo que aprende en el navegador le sirve en el teléfono de escritorio y en su celular.

El teléfono del navegador no graba nunca en su computadora. Grabar ocurre dentro de la central, que es donde se aplican las reglas de a quién se puede grabar y a quién hay que avisarle — vea «Grabar, y la ley».

Códigos que se marcan desde el teléfono

Se respetan los de siempre allí donde hay convención (*72 desviar, *78 no molestar, *97 el buzón, *8 capturar, *69 quién acaba de llamar). Ése es todo el sentido de un código de teclado: la función ya está en el panel, y el código es lo que hace que alguien que lleva veinte años marcando *72 se crea el panel.

Se marcan con el teléfono libre

Se marcan durante una conversación

Mientras consulta, en una transferencia atendida

Dentro de una sala de conferencia

Algunos códigos significan dos cosas y no chocan: *1 en una conversación normal es «grabar ahora», mientras consulta es «completar la transferencia», y dentro de una sala es «cerrar la sala». Son estados distintos del mismo teléfono, atendidos por código distinto.

Antes de fiarse de un teléfono nuevo: Los teléfonos de escritorio y los adaptadores procesan sus propios códigos de estrella y no los mandan nunca. Si marca un código y oye silencio y luego el tono, se lo comió el aparato y la central no vio nada. Pídanos que revisemos un modelo nuevo contra la lista de hoy antes de repartirlo.

El buzón desde cualquier teléfonobanco de pruebas

Marque *97, teclee su clave y tiene el buzón entero: sin aplicación y sin navegador. Está pensado para el dueño que llama desde un celular prestado.

Menú principal

Mientras suena un mensaje

Menú de saludos

Atender la llamada

Un grupo de timbrado dice «que suene en varios sitios». Todo lo de esta lista hace algo que un grupo no puede hacer.

• Colas.aún sin ejercitar Una cola sabe cuánta gente hay delante y cuánto se suele tardar, así que puede decirlo. La espera se mide con sus propias llamadas recientes, nunca se inventa — con menos de tres muestras no dice nada. Sin nadie de turno, no se hace esperar a nadie.
• Devolución de llamada desde la cola.aún sin ejercitar Se ofrece pasado un rato de espera, y no se ofrece si la llamada va a entrar enseguida. La petición sobrevive a un reinicio, porque quien la pide cuelga, y la devolución entra por delante de la fila, que es lo que se le prometió.
• Salas de conferencia.aún sin ejercitar Una sala con su número y dos claves: una para entrar y otra para organizarla. Nadie necesita cuenta en ningún sitio. Las entradas y salidas se anuncian con el nombre que grabó cada quien.
• El directorio por nombre.banco de pruebas Quien llama deletrea un nombre en el teclado y se le pasa. Se indexa cada palabra del nombre por separado, porque aquí dos apellidos son lo normal y buscar sólo por el primero encuentra a media empresa. Los acentos y la eñe se normalizan, así que «Muñoz» se encuentra marcando 686.
• El cero para la operadora.aún sin ejercitar Probablemente la expectativa más universal que existe sobre un teléfono: poder llegar a una persona. El cero baja en cascada de su operadora al buzón general y a decirlo en voz alta — nunca un cuelgue mudo.
• Aparcar y capturar.aún sin ejercitar Aparque una llamada y espera con música en una plaza numerada mientras usted camina a otro puesto. Cualquiera la recoge marcando esa plaza. Capturar el teléfono que timbra a su lado es *8.

Canales: garantía, préstamo y devoluciónpor la API

Es la parte del producto que un techo duro no sabe hacer, y conviene entenderla antes de elegir plan.

• Garantizadas. Las llamadas simultáneas que vende su plan. Caben siempre, esté como esté la central, y nadie se las puede quitar.
• Prestadas. Por encima de su garantía usa lo que la central tenga libre. La mayoría de los días estará aquí, y no cuesta nada de más.
• La reserva. Un colchón de canales que no se le presta a nadie, para que todo el mundo pueda llegar a su propia garantía en cualquier momento.
• La devolución. Cuando la central va apretada, una llamada prestada puede devolverse para proteger la garantía de otro. Sólo afecta a las cuentas que lo activaron, nunca a una llamada dentro de su garantía, nunca a una llamada de emergencia, y nunca en silencio — la central habla antes de soltar.
• No se puede sobrevender. La suma de todas las garantías más la reserva tiene que caber. El aprovisionamiento lo comprueba y rechaza un plan que no quepa, que es lo que hace que la palabra «garantizada» signifique algo.
• Y se ve cuándo mordió. La congestión se informa por episodios con su hora, no como un total del mes. «Doce rechazos en treinta días» se lee como ruido; «el martes pasado, entre diez y once, cinco personas oyeron ocupado» es algo sobre lo que se puede decidir.

Qué pasa cuando algo se rompe

Una central se juzga el día que se va la luz, no el día que todo funciona.

• Más de una salida. La central llega al mundo de fuera por varias conexiones independientes y elige entre ellas sola. Usted no configura esto ni lo ve ocurrir.
• «Funciona» se mide contra lo que hay que medir. Una conexión sólo entra en el reparto si llega a internet Y a la red telefónica. Comprobar sólo lo primero es como una central se queda sin línea con todas las luces en verde.
• Se recupera sola de un corte de luz. Cuando vuelve la luz, la central y los equipos de red arrancan a la vez y no siempre en el orden bueno. En vez de confiar en ese orden, la central compara sin parar lo que tiene con lo que debería tener y se repara — con un techo de cuántas veces puede reintentarlo, para que una avería de verdad se escale en lugar de quedarse en bucle.
• No corta una llamada para arreglarse. Cualquier reparación que fuera a interrumpir conversaciones espera a que no haya ninguna.

Las grabaciones y los mensajes del buzón se guardan fuera de la central, así que sobreviven a la propia máquina.

Planes y minutos

5 planes, de $100 a $300 al año, con un número por licencia. El minuto entrante a un número de Costa Rica es de $0.00.

Minutos

Precios en dólares, impuestos incluidos. El operador mide los celulares por segundo. Cada licencia incluye 1 número; los números adicionales comparten central, flujos y panel.

Grabar, y la leypor la API

Un audio grabado es la voz de otras personas. Lo gobierna la Ley 8968, y el diseño sale de ahí y no de lo que resultaría cómodo.

• Usted decide qué se graba.por la API Todo, o sólo ciertas extensiones, o sólo las llamadas que entren por cierto número. O nada, que es una respuesta legítima.
• La retención viene con su plan. Las grabaciones se purgan solas cuando les toca. La única excepción es una grabación atada a un expediente de llamada malintencionada, que deja de caducar hasta que usted cierre el expediente — y cerrarlo devuelve un plazo normal, nunca un «bórrela ya».
• Compartir una no es dar acceso. Un enlace firmado reproduce una sola grabación, caduca solo y se puede revocar. La persona a quien se lo manda no ve nunca su cuenta.
• Cada escucha queda anotada. Quién reprodujo qué grabación y cuándo. Es la voz de otra persona: saber quién la ha oído es parte de tenerla.
• Se pueden clasificar. Cliente, prospecto o interno. No hay valor por defecto a propósito: sin clasificar es honesto, y una etiqueta que puso la máquina no se distingue después de una que puso una persona.

Siempre se les avisa a las dos partes. Pedirle a la central que grabe devuelve también la obligación de anunciarlo: las dos cosas no se pueden separar, porque separarlas es como alguien acaba grabado sin saberlo. En una sala de conferencia el aviso se le hace a cada persona al entrar.

Límites, protección y deshacer

Lo que decide cuánto llega a doler un mal día: una credencial robada, un error en el enrutamiento, un número que no deja de llamar.

• Un tope de gasto, diario y mensual.banco de pruebas Es lo que impide que una credencial robada cueste dinero. Alcanzado el tope, las llamadas se paran.
• Qué puede marcar cada extensión.por la API Sólo internas, nacional, celular o todo. El teléfono de la bodega no tiene por qué poder llamar a un número premium. Las llamadas de emergencia no pasan nunca por aquí.
• El precio antes de marcar.por la API Pregunte cuánto costaría un número y la respuesta la calcula la misma maquinaria que va a cursar la llamada de verdad, no una lista de tarifas que podría no ser la que se aplique.
• Una alarma de fraude que mira el comportamiento.aún sin ejercitar Una velocidad rara, un país al que nunca ha llamado, una hora a la que no trabaja nadie. Avisa y no corta: un falso positivo aquí no es una alerta molesta, es una llamada que no se hizo. Le hacen falta dos señales antes de decir nada, porque una alarma que salta a diario se aprende a ignorar.
• Se señala a quien insiste demasiado.aún sin ejercitar El mismo número cinco veces en dos minutos no es un cliente insistente: es un marcador automático. De fábrica sólo avisa; bloquear automáticamente es una casilla suya, porque un falso positivo cuesta un cliente que ya no puede llamar nunca.
• Un expediente para una llamada malintencionada.aún sin ejercitar La hora, la ruta y el audio, guardados juntos para una denuncia. Abrir uno no bloquea a quien llama: cada llamada nueva es una prueba más, y eso lo decide usted y no nosotros.
• Qué tan alcanzables han estado sus aparatos.por la API No nuestro tiempo en pie: el suyo. Y siempre enseña qué parte del periodo se llegó a medir de verdad, porque un porcentaje que se come en silencio las horas que nadie miró se equivoca siempre hacia el lado cómodo.
• Qué cambió, quién lo cambió y cómo se deshace.aún sin ejercitar «Ayer funcionaba» es una pregunta con respuesta. Cada cambio de configuración queda anotado y se puede revertir, y revertir comprueba que nadie más haya tocado esos campos mientras tanto en vez de pisarlos en silencio.

Lo que está apagado, y por qué

Un manual que sólo cuenta lo que funciona le obliga a descubrir el resto por su cuenta, y siempre se descubre en el peor momento. Esta lista se genera desde la propia central, así que no puede describir como apagado algo que ya se encendió.

La APIpor la API

El panel es un cliente más de esta API. Todo lo que usted cambia a mano se puede cambiar por programa, con una clave que es de su cuenta.

curl -H "authorization: Bearer <clave>" \
  https://api.voice.forhosting.com/inquilinos/<cuenta>/numeros

Ámbitos

Cuando algo sale mal

Hoy casi no hay límite de ritmo. El único es una espera de unos segundos entre intentos de abrir el teléfono del navegador. No hay cuota general, y preferimos decirlo a que usted lo descubra habiendo construido sobre una suposición. Sea razonable, y si está planeando algo pesado, avísenos antes para medirlo con usted en vez de después de usted.

Hasta dónde llega

267 endpoints en total, leídos de la propia central el 2026-08-17.

Esta tabla es un resumen. La lista que no puede quedarse vieja es la que la central genera sobre sí misma: GET /api.

Sesiones: el navegador nunca lleva una clave permanente

Una credencial corta, con techo de 60 minutos, que no puede fabricar una permanente. Éste es el contrato si usted es quien construye el botón.

• Sólo el portal puede emitirla. Emitir una sesión necesita una clave de aprovisionamiento, porque sólo el portal puede afirmar que detrás de la petición hay un cliente con la sesión iniciada. VOICE no sabe de contraseñas de cliente y no tiene por qué saberlo.
• Nunca nace sin caducidad. Si nadie pide una duración, se le pone una. Un ámbito que existe para caducar y que pudiera nacer eterno es peor que no tenerlo, porque se confía en él.
• Pedir más tiempo no sirve. Hay un techo duro. Que quien llama pida ocho horas no hace segura la credencial.
• No puede ascender. La gestión de claves vive entera detrás del ámbito de aprovisionamiento, así que una sesión no puede fabricarse una clave permanente. Eso se impone en el enrutador, antes de cualquier manejador.
• Se puede cerrar antes de tiempo. El identificador vuelve al emitirla, justamente para que usted pueda revocarla antes de que le toque.

Avisos a su sistema (webhooks)por la API

Sus sistemas se enteran de lo que pasó en vez de preguntarlo cada pocos segundos. 28 eventos, firmados, con reintento, y ninguno se cae en silencio.

x-pbx-evento: llamada.entrante
x-pbx-marca:  1755300000
x-pbx-firma:  <hex>

{ "evento": "llamada.entrante", "inquilino": "…", "cuando": "…", "datos": { … } }

Cada entrega va firmada: la firma cubre la marca de tiempo y el cuerpo exacto que usted recibió, así que verifíquela contra los bytes en crudo y no contra una copia vuelta a serializar. El secreto se enseña una sola vez al crear la suscripción, y se puede rotar sin parar las entregas.

Una entrega que falla se reintenta a los 10 · 30 · 60 · 300 · 900 · 3600 segundos, y cada intento tiene 10 segundos. Una suscripción que sigue fallando se pausa tras 20 fallos seguidos, en vez de caerse en silencio — y usted puede ver todos los intentos.

Los eventos

El canal en vivollamada real

Los avisos viajan en lotes y llegan en segundos. Hay cosas que tienen que estar en pantalla ya: una luz que dice que un compañero está hablando no puede llegar quince segundos tarde.

• Qué lleva. Las llamadas según ocurren, los mensajes nuevos y el estado de la luz de cada extensión — que es lo que hace que un panel de luces en una pantalla esté vivo de verdad.
• Es de sólo lectura.aún sin ejercitar Se puede abrir un pase para el canal sin entregar un teléfono: mirar lo que pasa no debería exigir una credencial que además pueda cambiar cosas.
• No sustituye a los avisos. El canal en vivo es para una pantalla que alguien está mirando. Si importa que su sistema se entere, use un aviso: reintenta, y no depende de que haya un socket abierto.

Cómo se leen las insignias

Cada capacidad de esta página lleva una insignia que dice cómo se ha comprobado. Publicamos también las que todavía no se han ejercitado, marcadas como tales, porque que lo descubra usted es peor.

112 capacidades, contadas desde la central el 2026-08-19.

La insignia es de una capacidad, no de una fila suelta: donde una capacidad cubre varios códigos, todos enseñan el nivel del grupo. Eso significa que una insignia puede quedarse CORTA respecto a lo que de verdad se ha probado — nunca larga, que es la única dirección en la que estamos dispuestos a equivocarnos en una página que usted lee como una promesa.

Glosario

Las palabras que usa una central telefónica y no usa ninguna otra cosa.