Documentação

A sua central em cinco minutos

Tudo o que está aqui embaixo já existe na sua conta. Nada disso precisa de instalador, de visita de técnico nem de um aparelho que você tenha que comprar.

• Você já tem números e ramais. Eles nascem junto com a sua conta, com as credenciais SIP que cada aparelho precisa. Um ramal é uma pessoa ou um posto; um número é o que a gente de fora disca.
• Aponte um número para algum lugar. Na aba Números você diz o que uma ligação que entra por ali deve fazer: tocar num ramal, tocar num grupo, abrir um menu, entrar numa fila ou seguir o seu horário.
• Atenda pelo navegador. Abra a aba Telefone, libere o microfone, e essa aba vira um aparelho que funciona. Ligue para o teste de eco digitando *43 e você vai se ouvir de volta.
• Depois ponha o seu horário e a sua caixa postal. Esses dois são o que impede uma ligação de se perder às sete da noite, e são as duas coisas que mais costumam faltar numa central recém-estreada.

Com pressa? Há cinco modelos de partida — um consultório, um escritório de advocacia, uma oficina, uma loja e uma linha residencial — que criam o seu horário, a sua rota de entrada e a caixa postal de fora do horário numa única requisição. Eles nunca passam por cima do que você já configurou.

Como se entra no seu painelpela API

O painel fica na sua página do VOICE e só aparece com uma sessão. Essa sessão é emitida pela sua área do cliente; aqui não se digita nada.

Para quem for construir esse botão, este é o contrato inteiro:

POST /inquilinos/:inquilino/sesiones     # escopo sistema: só o portal pode emitir
{ "minutos": 15 }
→ { "clave": "pbx_ses_…", "caduca": "…", "ambito": "sesion", "minutos_max": 60 }

/pabx-virtual#t=<clave>&exp=<ISO>&v=<inquilino>

A credencial viaja no fragmento e não na query de propósito: um fragmento nunca é enviado a um servidor, então não acaba num cabeçalho Referer, nem nos registros de acesso, nem num intermediário do caminho. Expira em minutos, tem teto, e não consegue fabricar uma chave permanente.

O painel, aba por abapela API

16 seções, as mesmas 16 nos oito idiomas. Tudo o que está aqui existe também na API.

O telefone dentro do navegadorligação real

Uma aba é um aparelho. Sem instalar aplicativo, sem comprar telefone de mesa e sem portar número nenhum: é um ramal da sua própria central, registrado a partir do navegador.

• É um ramal de verdade. O navegador se registra na sua central igual a um telefone de mesa, e o áudio vai por uma conexão cifrada. Quem ligar para o seu número chega na aba, e a aba liga para fora.
• A aba tem que estar aberta. Uma aba fechada é um telefone fora da tomada. Esse é o limite honesto de um telefone no navegador, e a razão de ele acompanhar um aparelho de mesa em vez de substituí-lo em todo lugar.
• Você vê quem está em ligação.ligação real As luzes dos seus colegas se atualizam ao vivo — livre, tocando, falando —, então você sabe se há para quem passar antes de tentar passar.
• Você pode mover uma ligação viva para outro aparelho.ainda sem exercitar «Tenho que sair e estou no meio de uma ligação»: a ligação passa para o seu celular sem desligar. É um botão e não um código de teclado de propósito — quem move uma ligação tem uma tela na frente.
• Transferir, estacionar e gravar são os mesmos códigos de qualquer aparelho. São digitados, não clicados, então o que você aprende no telefone do navegador vale no telefone de mesa e no seu celular.

O telefone do navegador nunca grava no seu computador. Gravar acontece dentro da central, que é onde valem as regras de quem pode ser gravado e a quem é preciso avisar — veja «Gravar, e a lei».

Códigos que se digitam no aparelho

Mantemos os de sempre onde existe convenção (*72 desvio, *78 não perturbe, *97 caixa postal, *8 captura, *69 quem acabou de ligar). É todo o sentido de um código de teclado: a função já está no painel, e o código é o que faz quem digita *72 há vinte anos acreditar no painel.

Digitados com o telefone livre

Digitados durante uma conversa

Durante a consulta, numa transferência assistida

Dentro de uma sala de conferência

Alguns códigos significam duas coisas e não se chocam: *1 numa conversa normal é «gravar agora», durante a consulta é «completar a transferência», e dentro de uma sala é «trancar a sala». São estados diferentes do mesmo telefone, tratados por código diferente.

Antes de confiar num aparelho novo: Telefones de mesa e adaptadores processam os próprios códigos de estrela e nunca os repassam. Se você digita um código e ouve silêncio e depois o tom de discar, o aparelho engoliu e a central não viu nada. Peça para a gente conferir um modelo novo contra a lista de hoje antes de distribuir.

A caixa postal de qualquer telefonebancada de testes

Digite *97, informe a sua senha, e a caixa inteira está ali — sem aplicativo e sem navegador. Foi escrita para o dono que liga de um celular emprestado.

Menu principal

Enquanto um recado toca

Menu de saudações

Atender a ligação em si

Um grupo de toque diz «que toque em vários lugares». Tudo o que está nesta lista faz algo que um grupo de toque não consegue.

• Filas.ainda sem exercitar Uma fila sabe quantas pessoas estão na frente e quanto costuma demorar, então pode dizer. A espera é medida com as suas próprias ligações recentes, nunca inventada — com menos de três amostras não diz nada. Sem ninguém de turno, ninguém fica esperando.
• Retorno de ligação a partir da fila.ainda sem exercitar É oferecido depois de um tempo de espera, e não é oferecido se a ligação vai ser atendida logo. O pedido sobrevive a um reinício, porque quem pede desliga, e o retorno entra na frente da fila — que foi o que se prometeu.
• Salas de conferência.ainda sem exercitar Uma sala com o seu número e duas senhas: uma para entrar e outra para organizar. Ninguém precisa de conta em lugar nenhum. As entradas e saídas são anunciadas com o nome que cada um gravou.
• A lista de nomes.bancada de testes Quem liga soletra um nome no teclado e é encaminhado. Cada palavra do nome é indexada em separado, porque aqui dois sobrenomes são o normal e buscar só pelo primeiro encontra meia empresa. Acentos e o ñ são normalizados, então «Muñoz» se acha digitando 686.
• O zero para a telefonista.ainda sem exercitar Provavelmente a expectativa mais universal que existe sobre um telefone: conseguir chegar a uma pessoa. O zero desce em cascata da sua telefonista para a caixa postal geral e para dizer isso em voz alta — nunca um desligar mudo.
• Estacionar e capturar.ainda sem exercitar Estacione uma ligação e ela espera com música numa vaga numerada enquanto você caminha até outra mesa. Qualquer um pega de volta digitando essa vaga. Capturar o telefone que toca ao seu lado é *8.

Canais: garantia, empréstimo e devoluçãopela API

É a parte do produto que um teto fixo não sabe fazer, e vale entender antes de escolher o plano.

• Garantidos. As ligações simultâneas que o seu plano vende. Cabem sempre, faça o que fizer a central, e ninguém tira de você.
• Emprestados. Acima da sua garantia você usa o que a central tiver livre. Na maioria dos dias você vai estar aqui, e não custa nada a mais.
• A reserva. Um colchão de canais que não se empresta a ninguém, para que qualquer um alcance a própria garantia a qualquer momento.
• A devolução. Quando a central aperta, as ligações emprestadas podem ser devolvidas para proteger a garantia de outro. Só vale para contas que ativaram isso, nunca para uma ligação dentro de uma garantia, nunca para uma emergência e nunca em silêncio: a central fala antes de soltar.
• Não dá para vender demais. A soma de todas as garantias mais a reserva tem que caber. A ativação confere e recusa um plano que não caiba, e é isso que faz a palavra «garantido» significar algo.
• E dá para ver quando apertou. O congestionamento é informado por episódios com a sua hora, não como um total do mês. «Doze rejeições em trinta dias» se lê como ruído; «na terça passada, entre dez e onze, cinco pessoas ouviram ocupado» é algo sobre o que dá para decidir.

O que acontece quando algo quebra

Uma central se julga no dia em que falta luz, não no dia em que tudo funciona.

• Mais de uma saída. A central chega ao mundo de fora por várias conexões independentes e escolhe entre elas sozinha. Você não configura isso nem vê acontecer.
• «Funciona» se mede contra o que interessa. Uma conexão só entra no rodízio se alcança a internet E a rede telefônica. Conferir só a primeira é como uma central acaba sem linha com todas as luzes verdes.
• Ela se recupera sozinha depois de uma falta de luz. Quando a luz volta, a central e os equipamentos de rede ligam ao mesmo tempo e nem sempre na ordem certa. Em vez de confiar nessa ordem, a central compara sem parar o que tem com o que deveria ter e se conserta — com um teto de quantas vezes pode tentar, para que um defeito de verdade seja escalado em vez de ficar em laço.
• Ela não corta uma ligação para se consertar. Qualquer conserto que fosse interromper conversas espera até não haver nenhuma.

As gravações e os recados da caixa postal ficam guardados fora da central, então sobrevivem à própria máquina.

Planos e minutos

5 planos, de US$ 100 a US$ 300 por ano, e um número por licença. O minuto de entrada num número da Costa Rica é US$ 0,00.

Minutos

Preços em dólares, impostos incluídos. A operadora mede as ligações para celular por segundo. Cada licença inclui 1 número; os números adicionais compartilham a mesma central, os mesmos fluxos e o mesmo painel.

Gravar, e a leipela API

Um áudio gravado é a voz de outras pessoas. Quem manda nisso é a Lei 8968 da Costa Rica, e o desenho sai daí, não do que seria cômodo.

• Você decide o que é gravado.pela API Tudo, ou só certos ramais, ou só as ligações que entram por certo número. Ou nada, que é uma resposta legítima.
• A retenção vem com o seu plano. As gravações são apagadas sozinhas quando dá o prazo. A única exceção é uma gravação presa a um processo de ligação mal-intencionada, que deixa de expirar até você fechar o processo — e fechar devolve um prazo normal, nunca um «apague agora».
• Compartilhar uma não é dar acesso. Um link assinado toca uma única gravação, expira sozinho e pode ser revogado. A pessoa para quem você manda nunca vê a sua conta.
• Cada escuta fica anotada. Quem tocou qual gravação e quando. É a voz de outra pessoa: saber quem já ouviu faz parte de guardá-la.
• Dá para classificar. Cliente, prospecto ou interno. Não há valor padrão de propósito: sem classificar é honesto, e uma etiqueta que a máquina chutou não se distingue depois de uma que uma pessoa escolheu.

As duas partes são sempre avisadas. Pedir à central que grave devolve junto a obrigação de anunciar: as duas coisas não se separam, porque separá-las é como alguém acaba gravado sem saber. Numa sala de conferência o aviso é feito a cada pessoa na hora de entrar.

Limites, proteção e desfazer

O que decide o tamanho de um dia ruim: uma credencial roubada, um erro no roteamento, um número que não para de ligar.

• Um teto de gasto, diário e mensal.bancada de testes É o que impede uma credencial roubada de custar dinheiro. Alcançado o teto, as ligações param.
• O que cada ramal pode discar.pela API Só internas, nacional, celular, ou tudo. O telefone do depósito não tem por que conseguir ligar para um número premium. As ligações de emergência nunca passam por aqui.
• O preço antes de discar.pela API Pergunte quanto custaria um número e a resposta é calculada pela mesma maquinaria que vai cursar a ligação de verdade, não por uma tabela que poderia não ser a aplicada.
• Um alarme de fraude que olha o comportamento.ainda sem exercitar Uma velocidade estranha, um país para o qual você nunca ligou, uma hora em que ninguém trabalha. Avisa e não corta: um falso positivo aqui não é um alerta chato, é uma ligação que não aconteceu. Ele precisa de dois sinais antes de dizer qualquer coisa, porque um alarme que dispara todo dia se aprende a ignorar.
• Quem insiste demais é sinalizado.ainda sem exercitar O mesmo número cinco vezes em dois minutos não é um cliente insistente: é um discador automático. De fábrica só avisa; bloquear automaticamente é uma caixinha sua, porque um falso positivo custa um cliente que nunca mais consegue ligar.
• Um processo para uma ligação mal-intencionada.ainda sem exercitar A hora, o caminho e o áudio, guardados juntos para uma denúncia. Abrir um não bloqueia quem liga: cada ligação nova é mais uma prova, e isso quem decide é você, não a gente.
• Quão alcançáveis os seus aparelhos têm estado.pela API Não o nosso tempo no ar: o seu. E sempre mostra que parte do período foi de fato medida, porque um percentual que engole em silêncio as horas que ninguém olhou erra sempre para o lado cômodo.
• O que mudou, quem mudou e como se desfaz.ainda sem exercitar «Ontem funcionava» é uma pergunta com resposta. Cada mudança de configuração fica anotada e pode ser revertida, e reverter confere que ninguém mais mexeu nesses campos no meio-tempo em vez de passar por cima em silêncio.

O que está desligado, e por quê

Um manual que só conta o que funciona obriga você a descobrir o resto sozinho, e sempre se descobre na pior hora. Esta lista é gerada a partir da própria chave, então não consegue descrever como desligado algo que já foi ligado.

A APIpela API

O painel é mais um cliente desta API. Tudo o que você muda na mão dá para mudar por programa, com uma chave que é da sua conta.

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

Escopos

Quando algo dá errado

Hoje quase não há limite de ritmo. O único é uma espera de alguns segundos entre tentativas de abrir o telefone do navegador. Não há cota geral, e preferimos dizer a deixar você descobrir depois de ter construído em cima de uma suposição. Seja razoável, e se estiver planejando algo pesado, avise antes para medirmos junto com você em vez de depois de você.

Até onde dá para chegar

267 endpoints no total, lidos da própria central em 2026-08-17.

Esta tabela é um resumo. A lista que não pode ficar velha é a que a central gera sobre si mesma: GET /api.

Sessões: o navegador nunca guarda uma chave permanente

Uma credencial curta, com teto de 60 minutos, que não consegue fabricar uma permanente. Este é o contrato se você é quem constrói o botão.

• Só o portal pode emitir uma. Emitir uma sessão exige uma chave de ativação, porque só o portal pode afirmar que atrás da requisição há um cliente com a sessão iniciada. O VOICE não sabe de senhas de cliente e não tem por que saber.
• Ela nunca nasce sem prazo. Se ninguém pede uma duração, uma é aplicada. Um escopo que existe para expirar e que pudesse nascer eterno é pior do que não ter, porque as pessoas confiam nele.
• Pedir mais tempo não adianta. Há um teto duro. Quem chama pedir oito horas não torna a credencial segura.
• Ela não consegue se promover. A gestão de chaves vive inteira atrás do escopo de ativação, então uma sessão não consegue fabricar uma chave permanente. Isso é imposto no roteador, antes de qualquer manipulador.
• Dá para encerrar antes da hora. O identificador volta na hora de emitir, justamente para que você possa revogá-la antes do prazo.

Avisos ao seu sistema (webhooks)pela API

Os seus sistemas ficam sabendo do que aconteceu em vez de perguntar a cada poucos segundos. 28 eventos, assinados, com reenvio, e nenhum cai em silêncio.

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

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

Cada entrega vai assinada: a assinatura cobre a marca de tempo e o corpo exato que você recebeu, então confira contra os bytes crus e não contra uma cópia serializada de novo. O segredo é mostrado uma única vez ao criar a assinatura, e pode ser girado sem parar as entregas.

Uma entrega que falha é reenviada depois de 10 · 30 · 60 · 300 · 900 · 3600 segundos, e cada tentativa tem 10 segundos. Uma assinatura que continua falhando é pausada depois de 20 falhas seguidas, em vez de ser descartada em silêncio — e você consegue ver todas as tentativas.

Os eventos

O canal ao vivoligação real

Os avisos viajam em lotes e chegam em segundos. Tem coisa que precisa estar na tela agora: uma luz que diz que um colega está em ligação não pode chegar quinze segundos atrasada.

• O que ele carrega. As ligações conforme acontecem, os recados novos e o estado da luz de cada ramal — que é o que faz um painel de luzes numa tela estar vivo de verdade.
• Ele é de só leitura.ainda sem exercitar Dá para abrir um passe para o canal sem entregar um telefone: olhar o que acontece não deveria exigir uma credencial que também consegue mudar coisas.
• Ele não substitui os avisos. O canal ao vivo é para uma tela que alguém está olhando. Se importa que o seu sistema fique sabendo, use um aviso: ele reenvia, e não depende de um socket aberto.

Como se leem os selos

Cada função desta página traz um selo dizendo como foi verificada. Publicamos também as que ainda não foram exercitadas, marcadas como tais, porque você descobrir sozinho é pior.

112 funções, contadas da própria central em 2026-08-19.

O selo é de uma função, não de uma linha solta: onde uma função cobre vários códigos, todos mostram o nível do grupo. Isso significa que um selo pode ficar CURTO em relação ao que de fato foi testado — nunca comprido, que é a única direção na qual estamos dispostos a errar numa página que você lê como uma promessa.

Glossário

As palavras que uma central telefônica usa e mais nada usa.