Integração Yeastar PBX
A integração Yeastar coloca a telefonia da portaria dentro do ACCELERO. O operador fala com as unidades do condomínio sem aparelho na mesa e sem sair da tela em que está: a chamada acontece no próprio navegador, por WebRTC, usando a SDK oficial da Yeastar.
O princípio que orienta o recurso é que ninguém precise saber o número do ramal. Quem atende pensa em "Casa 12" ou "o senhor Lacerda", e o sistema descobre o resto.
Esta integração é disponibilizada como plugin (yeastar) e precisa ser instalada e habilitada pela equipe técnica da IONGRADE. Consulte o suporte para verificar compatibilidade com a sua versão do ACCELERO.
Versão atual do plugin: 0.2.0 — compatível com ACCELERO 2.16.9 e 2.17.2.
O que a integração faz
| Recurso | O que o operador ganha |
|---|---|
| Busca rápida | Abre por atalho de teclado sobre qualquer tela e procura pela unidade, pelo bloco, pelo nome do morador ou pelo ramal |
| Painel da chamada | Quando a unidade liga, mostra quem mora ali (destacando quem pode autorizar entrada), as visitas do dia e as últimas chamadas — antes de atender |
| Chamada no navegador | Atender, desligar, mudo, espera, transferência e teclado numérico, sem softphone externo |
| Histórico | Quem ligou para qual unidade, de qual posto, quando e com que resultado |
| Postos de atendimento | O ramal pertence ao posto, não à pessoa: quem estiver logado com aquele perfil atende por aquele ramal |
No ACCELERO a unidade é o cadastro de Empresa. Em condomínio, cada casa ou apartamento é uma empresa, e o Grupo da empresa é o que aparece como bloco na busca e no painel de chamada.
Pré-requisitos
| Requisito | Por quê |
|---|---|
| PBX Yeastar série P | A integração usa a OpenAPI e o Linkus SDK, que são desta linha |
| Firmware 84.12.0.32 ou superior | Versões anteriores não expõem o sign/create usado para autenticar o navegador |
| Plano Ultimate | O Linkus SDK é um recurso pago do PBX |
| Ramal com e-mail cadastrado | O Yeastar identifica o ramal pelo e-mail, não pelo número |
| Navegador com microfone | A chamada acontece no navegador do operador, por WebRTC |
É uma troca imposta pelo próprio PBX, não pela integração. Se o condomínio usa o aplicativo Linkus no celular com notificações, confirme com o cliente antes de ligar o recurso.
Em PBX sem o plano, a tela do Linkus SDK exibe "This is a demo. Subscribe to unlock this feature.", o botão fica travado e o AccessID/AccessKey vêm vazios. É uma liberação comercial da Yeastar — não há configuração que contorne.
Configuração no PBX Yeastar
São quatro etapas do lado do PBX, todas anteriores à configuração no ACCELERO.
1. Habilitar o Linkus SDK
É deste par de credenciais que sai a telefonia em si: é o único que consegue assinar a sessão do navegador.
- No PBX, acesse
Integrations > Linkus SDK. - Ligue a chave Linkus SDK.
- Clique em Save e depois em Apply.
- Copie o AccessID e o AccessKey — o AccessKey só aparece ao clicar no ícone de olho.
Em campo, ligar apenas a chave do Linkus SDK não bastou. Foi preciso habilitar o recurso, salvar e aplicar, e só então o AccessID e o AccessKey passaram a ser gerados. Se os campos vierem vazios, repita o Save e o Apply antes de suspeitar de outra coisa.
2. Habilitar a API
Este é um par diferente do anterior, e igualmente obrigatório. É ele que lê o diretório de ramais e o histórico de chamadas.
- Acesse
Integrations > API. - Ligue a chave API.
- Salve e aplique.
- Copie o Client ID e o Client Secret.
Os escopos são mutuamente exclusivos. O AccessID/AccessKey assina a telefonia e recebe 10005 ACCESS DENIED em qualquer outro endpoint; o Client ID/Secret lê ramais e histórico e recebe o mesmo 10005 na telefonia. Trocar um pelo outro faz a integração falhar com ACCESS DENIED, e é o erro de configuração mais comum.
3. Liberar o acesso remoto
Quando o ACCELERO fala com o PBX pelo FQDN da Yeastar, o próprio PBX decide quem pode se conectar de fora. Esta é a etapa que mais gera chamado, porque quando ela falta o erro não diz o que está errado.
- Acesse
System > Network > Yeastar FQDN. - Confirme que o status é Successfully connected to the tunnel server.
- Em Features, abra a aba Remote Access e deixe o API Access como
Enabled. - Verifique o Access Type. Se estiver como Allowed Account, siga para o passo abaixo.
Com o Access Type em Allowed Account, o ramal usado pelo ACCELERO precisa estar liberado. Em campo, adicionar os ramais individualmente na lista não surtiu efeito, mesmo após Save e Apply. O que resolveu foi incluí-los no Extension Group que já estava liberado, em Extension and Trunk > Extension Group.
O gate do Allowed Account é avaliado antes da credencial. Senha certa e senha errada devolvem exatamente o mesmo 70112, e o navegador do operador mostra apenas PBX_API_ERROR. Já custou horas de investigação em credencial que estava correta o tempo todo.
4. Preparar os ramais
Cada posto de atendimento consome um ramal do PBX. Reserve um ramal por posto (guarita principal, portaria de serviço) e confira quatro pontos em cada um.
| Campo no ramal | Valor e motivo |
|---|---|
| Obrigatório. O Yeastar identifica o ramal pelo e-mail, e um ramal sem e-mail nunca autentica. A configuração do plugin recusa o salvamento e informa qual ramal está sem | |
ICE (enb_ice) | Habilitado. Sem ICE a mídia fica de mão única: o operador não ouve nada em chamada recebida, embora o outro lado o ouça normalmente |
NAT (enb_nat) | Habilitado, pelo mesmo motivo |
| Concurrent Registrations | Igual ao número de operadores que atendem aquele posto ao mesmo tempo. Cada navegador consome um registro, mesmo com várias abas abertas |
A tela do Yeastar aplica esses padrões; o extension/create da API, não. Se os ramais foram criados por integração ou importação, confira enb_ice e enb_nat antes de concluir que o problema é de rede.
Configuração no Accelero
Caminho de acesso: Avançado > Sistema > Plugins - Yeastar PBX
A tela tem uma única aba (Geral) e reúne as credenciais do PBX, o e-mail do ramal genérico e a tabela de postos de atendimento.
Credenciais
| Campo | O que preencher |
|---|---|
| Endereço do PBX | URL completa incluindo o caminho /openapi/v1.0/. Ex.: https://pbx-exemplo.ras.yeastar.com/openapi/v1.0/ |
| AccessID | De Integrations > Linkus SDK no PBX |
| AccessKey | Do mesmo lugar |
| Client ID | De Integrations > API no PBX |
| Client Secret | Do mesmo lugar |
| Email (Ramal Genérico) | E-mail cadastrado no ramal que o ACCELERO usará. O ramal precisa ter e-mail no PBX: é por ele que o Yeastar identifica o ramal, não pelo número |
AccessKey e Client Secret voltam como ••••••••. Deixá-los assim preserva o valor gravado; digitar por cima substitui. Isso existe para que o segredo do PBX não trafegue até o navegador de todo operador que abrir a tela de configuração.
O salvamento apenas descobre o e-mail de cada ramal e grava. Se houver outro problema (credencial trocada, acesso remoto fechado), o erro aparece quando um operador carregar uma tela do sistema, não aqui.
Postos de atendimento
Na mesma tela, a tabela Postos de atendimento liga cada perfil do ACCELERO a um ramal do PBX.
| Campo | O que preencher |
|---|---|
| Perfil (posto) | O perfil do ACCELERO que representa aquele posto: a guarita principal, a portaria de serviço |
| Ramal | Só o número. O e-mail é descoberto no PBX ao salvar |
| Nome do posto | Como o posto aparece para o operador |
Use Incluir para adicionar uma linha e o botão vermelho para remover.
O ramal pertence ao posto, não à pessoa. Quem estiver logado com aquele perfil atende por aquele ramal, inclusive dois operadores ao mesmo tempo, caso em que a chamada toca nos dois e qualquer um pode atender.
Mapear um posto a um perfil sem a permissão Yeastar - usar a telefonia resulta em nada: o operador entra e simplesmente não vê telefone algum, sem erro em lugar nenhum. A tela de configuração avisa quando isso acontece, nomeando o perfil, mas conceda a permissão em Avançado > Perfis antes de dar a implantação por encerrada.
Se a tela mostrar "há posto vinculado a um perfil que esta tela não consegue exibir (perID N)", o posto aponta para um perfil interno do sistema ou já removido. A linha está mostrando outro perfil, e salvar assim moveria o posto para ele. Corrija o vínculo antes de salvar.
Ramal da unidade
Para que o operador consiga ligar para uma unidade — e para que a chamada recebida seja reconhecida — cada unidade precisa do seu ramal.
Caminho de acesso: Configurações > Empresas > Editar
Na aba Editar do cadastro, a seção Integração Yeastar traz um único campo.
| Campo | Descrição |
|---|---|
| Ramal | Número do ramal Yeastar associado a esta empresa (ex.: 1006) |
O sistema recusa o salvamento e informa qual unidade já usa aquele número. A chamada recebida é resolvida de ramal para unidade: com dois cadastros no mesmo número, o painel mostraria a unidade errada, com toda a confiança e sem nada na tela indicando ambiguidade.
Permissões
São três, concedidas em Avançado > Perfis. A primeira decide se a telefonia existe para aquele operador.
| Permissão | Função interna | O que libera |
|---|---|---|
| Yeastar - usar a telefonia | yeastarWidget | Receber e atender chamadas. Sem ela nada é carregado |
| Yeastar - ligar para unidades | yeastarCall | Usar a busca rápida para originar chamadas |
| Yeastar - consultar historico de chamadas | yeastarHistorico | Abrir o menu Histórico de chamadas |
Ele mostra qual operador falou com qual unidade e quando. Isso é informação de supervisão, e não decorre de poder atender o telefone. Na atualização do plugin, quem já podia ligar recebeu a permissão nova automaticamente, para não perder acesso em silêncio.
Operador cujo perfil não esteja vinculado a nenhum posto simplesmente não vê a telefonia. Não há erro, apenas ausência — é o comportamento correto para quem trabalha em outra função.
Uso no dia a dia
O posto do operador
No canto inferior direito ficam o botão laranja de telefone e uma etiqueta com o nome do posto e o estado da linha naquela aba.
| Indicação | Significado |
|---|---|
| ● linha | Esta aba é a que está conectada ao telefone. É nela que a chamada toca |
| ○ espelho | Outra aba está com a linha. O operador continua vendo tudo e pode agir normalmente |
O navegador só libera o som depois de uma interação do usuário na página. Sem isso, a primeira chamada do dia pode chegar sem áudio. Um clique qualquer resolve, e vale para o resto do turno.
Ligar para uma unidade
Pressione Alt + T de qualquer tela, ou clique no botão laranja de telefone. A busca abre por cima do que o operador estava fazendo, e procura ao mesmo tempo por quatro coisas.
| O operador digita | A busca encontra |
|---|---|
| O número da unidade | 12 acha a Casa 12 |
| O bloco ou setor | Palmeiras acha as unidades daquele grupo |
| O nome de um morador | Lacerda acha as unidades onde alguém com esse nome mora |
| O próprio ramal | 2021 acha a unidade que usa aquele número |
| Tecla | Faz |
|---|---|
↓ e ↑ | Passa pelos resultados |
Enter | Liga para o selecionado |
Esc | Fecha e devolve o foco para onde o operador estava |
Condomínio com numeração repetida entre torres ou quadras é a regra, não a exceção. É exatamente aí que se liga para a unidade errada sem perceber — por isso o bloco fica sempre visível ao lado do número.
Digite o número. Se ele não corresponder a nenhuma unidade cadastrada, a última opção da lista oferece discar aquele número direto — útil para interfone de serviço, manutenção ou portaria vizinha.
Receber uma chamada
Quando uma unidade liga, o telefone toca e um painel aparece no canto superior direito, antes de atender. Ele existe para que o operador já saiba com quem vai falar.
| O painel mostra | Para quê |
|---|---|
| A unidade e o bloco | O operador já sabe de onde vem a chamada, sem perguntar |
| Os moradores | Com o selo Autorizante em quem pode liberar entrada |
| Visitas de hoje | Quem está agendado para aquela unidade, com horário e situação |
| Últimas chamadas desta unidade | Se aquela unidade já ligou hoje, e no que deu |
Use Atender para receber ou Recusar para não atender.
Saber, antes da primeira palavra, que quem está do outro lado pode liberar entrada evita a pergunta "o senhor autoriza?" dirigida a quem não pode autorizar. É a informação que mais economiza tempo na portaria.
Se o número não pertencer a nenhuma unidade cadastrada, o painel mostra o número e as ações do mesmo jeito. O operador nunca perde a chamada por falta de cadastro.
Durante a conversa
Depois de atender, a janela da chamada aparece com os controles. Ela pode ser arrastada pela barra de título para onde for mais confortável.
| Controle | Faz |
|---|---|
| End Call | Encerra a chamada |
| Mute | Corta o microfone do operador. O outro lado deixa de ouvir; o operador continua ouvindo |
| Hold | Coloca em espera |
| Video | Liga a câmera, quando houver |
| Transfer | Passa a chamada para outro ramal |
| Dialpad | Teclado numérico, para menus de atendimento |
| New call | Inicia outra chamada sem encerrar a atual |
A janela da chamada é fornecida pela SDK da Yeastar e mantém os rótulos originais. O controle Record aparece desabilitado quando a gravação não está liberada no PBX.
Histórico de chamadas
Caminho de acesso: menu lateral > Histórico de chamadas
Cada linha reúne o registro do PBX (horário, duração e resultado) com o que o ACCELERO sabe: de qual posto partiu e qual operador agiu.
| Coluna | Conteúdo |
|---|---|
| Quando | Data e hora da chamada |
| Unidade | A unidade e o bloco, quando o ramal está vinculado a um cadastro |
| Direção | Recebida ou efetuada |
| Posto | O posto de atendimento envolvido |
| Operador | Quem agiu pelo ACCELERO |
| Duração | Tempo de conversa |
| Resultado | Atendida, Não atendida, Caixa postal |
O botão Pesquisar abre o painel de busca, no mesmo padrão das demais listagens do sistema.
| Filtro | Conteúdo |
|---|---|
| De / Até | Período, no formato dd/mm/aaaa |
| Direção | Todas, recebidas ou efetuadas |
| Resultado | Todos, ou um desfecho específico |
| Ramal da unidade | Número do ramal |
Os botões Pesquisar, Fechar e Limpar completam o painel.
Significa que ninguém agiu por dentro do ACCELERO naquela chamada — uma ligação que ninguém atendeu, por exemplo. O registro do PBX existe; o que não existe é uma ação de operador para associar a ele.
O PBX não permite filtrar no servidor, então o plugin lê as chamadas mais recentes e aplica o filtro sobre elas. Para períodos antigos, o histórico completo fica no próprio PBX (consulta ao CDR).
Várias abas abertas
É comum trabalhar com o ACCELERO aberto em mais de uma aba. Apenas uma delas fica conectada ao telefone, escolhida automaticamente: é a que mostra ● linha.
- A aba com a linha é onde a chamada toca.
- As demais mostram o mesmo painel e encaminham as ações do operador.
- Se a aba da linha for fechada, outra assume sozinha em poucos segundos.
Na prática o operador não precisa se preocupar com isso. A distinção existe para que o ramal ocupe um registro no PBX, e não um por aba.
Validação da implantação
Antes de entregar, confirme os cinco pontos abaixo com um operador de verdade na tela.
- A telefonia aparece. Entre com um usuário do perfil mapeado. No canto inferior direito devem surgir o botão de telefone e o nome do posto.
- A busca encontra. Pressione
Alt + Te digite o número de uma unidade, e depois o nome de um morador. As duas buscas devem achar. - A chamada sai. Ligue para uma unidade e confirme que o áudio vai e volta.
- A chamada entra. Peça para a unidade ligar. O painel deve aparecer antes de atender, com a unidade certa.
- Uma aba só registra. Abra o ACCELERO em três abas e confira em
Extension and Trunk > Extension, no PBX, que o ramal aparece com um registro, não três.
O navegador só permite reproduzir som depois de um clique do usuário na página. Se a primeira chamada do dia chegar muda e as seguintes funcionarem, é isso — e não a integração.
Troubleshooting
A telefonia não aparece para um operador
Verifique nesta ordem:
- Se o perfil dele está vinculado a um posto na configuração do plugin.
- Se o perfil tem a permissão Yeastar - usar a telefonia (
yeastarWidget).
Sem qualquer um dos dois, nada é carregado e nenhum erro é exibido.
O navegador mostra PBX_API_ERROR e nada mais
Causa mais provável: o Access Type do FQDN está em Allowed Account sem o ramal liberado. O PBX recusa a conexão antes de checar a credencial, então senha certa e errada dão o mesmo erro.
Solução: libere pelo Extension Group, não ramal a ramal.
A integração falha com ACCESS DENIED
Causa: os dois pares de credenciais foram trocados de lugar.
Solução: o AccessID/AccessKey vem de Integrations > Linkus SDK; o Client ID/Secret vem de Integrations > API. Cada um é recusado no endpoint do outro.
O salvamento recusa dizendo que um ramal não tem e-mail
Causa: é proposital. O Yeastar identifica o ramal pelo e-mail, e um ramal sem e-mail nunca conseguiria autenticar — a falha apareceria muito depois, sem pista da causa.
Solução: cadastre o e-mail no ramal dentro do PBX.
O operador não ouve a chamada recebida, mas o outro lado o ouve
Causa: ramal sem ICE habilitado. Acontece com ramais criados pela API em vez da interface.
Solução: habilite enb_ice e enb_nat no ramal. Verifique também a permissão de microfone no navegador.
A chamada chegou muda
Solução: clique em qualquer ponto da página e tente de novo — o navegador só libera o som depois de uma interação. Se persistir, confirme que o microfone está autorizado para o site.
Apareceu "Sessão expirada"
Causa: a sessão do ACCELERO caiu.
Solução: recarregue a página e entre de novo.
O operador buscou uma unidade que existe e não achou
Causa: aquela unidade provavelmente ainda não tem ramal vinculado no cadastro.
Solução: preencha o Ramal na seção Integração Yeastar do cadastro da empresa.
O Alt + T não abre a busca
Solução: verifique se o foco está na página do ACCELERO, e não em outra janela. O botão laranja de telefone faz a mesma coisa.
Dois operadores no mesmo posto — os dois tocam?
Sim, por definição: o ramal é do posto e qualquer um pode atender. Confira se o Concurrent Registrations do ramal comporta o número de operadores simultâneos.
Integração com outros módulos
Empresas
A unidade é o cadastro de Empresas. O campo Ramal da seção Integração Yeastar vincula o ramal do PBX à unidade, e o Grupo da empresa é o que aparece como bloco na busca e no painel de chamada.
Pessoas
Os moradores exibidos no painel da chamada recebida vêm das Pessoas associadas à empresa. O selo Autorizante reflete a marcação de autorizante no vínculo entre a pessoa e a unidade.
Eventos (Visitas)
O bloco Visitas de hoje do painel lista os Eventos do dia para aquela unidade, com horário e situação. Visitas canceladas não entram.
Operadores e Perfis
O posto é um perfil, e as três permissões do plugin são concedidas aos perfis dos Operadores que atendem.