Integrações

Visão geral

A tela fica no menu Integrações, com o subtítulo Conecte o ChatISP aos sistemas do provedor. O acesso exige a permissão Integrações no perfil (veja Usuários e perfis).

Fora desta tela ficam outras ligações com serviços externos: os números de WhatsApp e a API oficial da Meta (Conexões de WhatsApp), o Google Agenda, conectado por cada usuário em Minha conta (veja Google Agenda), e o e-mail do sistema (veja E-mail do sistema).

Ravicor

O Ravicor é a plataforma de gestão de rede da Ravi Systems. Conectado ao ChatISP, ele responde por tudo o que é rede na ficha do cliente; o ERP continua sendo a fonte do cadastro e do financeiro.

O que a conexão habilita

• A cena da rede do assinante no cartão da conversa: concentradora, sessão PPPoE, OLT e sinal da ONU, equipamento, Wi-Fi, aparelhos conectados, quedas e reinícios (veja Ficha do cliente: rede).
• As ações no equipamento do cliente: Reiniciar e Editar Wi-Fi, pelo atendente ou pela IA.
• Para a IA, também o teste de velocidade e a análise e troca do canal do Wi-Fi, quando o Ravicor instalado já tem esses diagnósticos.
• O vínculo manual de cliente pela busca de cadastros (veja Vínculo manual).
• O botão Importar do Ravicor, que traz os ERPs cadastrados no Ravicor para o ChatISP.
• Enquanto nenhum ERP estiver cadastrado no ChatISP, a identificação do cliente pelo telefone é feita pelo Ravicor.

Estados do card

Conectar pelo pareamento (recomendado)

No pareamento ninguém copia chave nenhuma: o ChatISP pede acesso, alguém libera no Ravicor e a chave chega sozinha, guardada cifrada. Ela não aparece em tela nenhuma.

1. No card Ravicor, preencha Endereço do Ravicor com o IP ou o nome do servidor (por exemplo 192.168.0.10). Pode ser também a URL completa. Sem protocolo, o ChatISP tenta HTTPS e, se não houver certificado, HTTP.
2. Clique em Conectar. O card passa para Aguardando liberação.
3. No Ravicor, abra Configurações › Integrações e libere o pedido do ChatISP.
4. Volte ao ChatISP: a tela confere sozinha a cada poucos segundos e vira Conectada assim que o pedido é liberado, com o aviso Integração confirmada. Não é preciso recarregar.

Enquanto espera, Cancelar pedido desiste da conexão. Se o pedido for recusado ou removido no Ravicor, o card volta ao começo com o aviso A conexão foi removida no Ravicor.

Testar e desconectar

• Testar conexão faz uma chamada ao Ravicor e responde Integração confirmada. ou Não foi possível conectar. Confira o endereço e a chave.
• Desconectar pede a confirmação Desconectar do Ravicor? O acesso do ChatISP é cancelado nos dois lados. O ChatISP avisa o Ravicor, que apaga a chave, e limpa a ligação deste lado. Os ERPs importados do Ravicor continuam cadastrados no ChatISP.
• Ao abrir a tela com o card conectado, o ChatISP confere se a conexão ainda existe no Ravicor; se tiver sido removida por lá, avisa e volta ao estado inicial.

Configuração manual

Abaixo do botão Conectar, Informar a chave de API manualmente abre os campos Endereço (URL completa) e Chave de API. O card passa a Configurada com o texto Configurado com uma chave de API informada manualmente.

ERPs e sistemas externos

O card ERPs e sistemas externos reúne as fontes de cadastro e financeiro do atendimento. O ERP é quem diz quem é o cliente, em que situação está o contrato e o que ele deve; o ChatISP conversa direto com ele, sem intermediários.

A lista de ERPs

Cada ERP cadastrado ocupa uma linha:

Sem nenhum ERP, o card mostra Nenhum ERP conectado ainda. Adicione uma fonte ou importe do Ravicor. Abaixo da lista de ERPs fica a tabela dos sistemas externos genéricos (veja Sistemas externos).

Qual empresa o ERP atende

Com mais de uma base de conhecimento ativa (várias empresas no mesmo ChatISP), cada linha ganha a escolha Atende: Todas as bases ou o nome de uma base. Tocar grava na hora (Pronto, a escolha já vale para os próximos atendimentos.). Nos números de uma base, a assistente e o cartão do cliente consultam só os ERPs dela e os que atendem todas. Com uma base só, nada aparece e o ERP atende tudo. Veja Várias bases: uma por empresa.

Botões do card

• Adicionar fonte abre a janela Adicionar fonte externa, com um cartão para cada ERP homologado (IXC Provedor, SGP (TSMX), Hubsoft, Gesprov, ReceitaNet, Pipesoft: Cadastro guiado, no padrão homologado) e o cartão Outro sistema (Integração genérica por API).
• Importar do Ravicor aparece com o Ravicor conectado pelo pareamento. Veja Importar ERPs do Ravicor.

Cadastrar um ERP

1. Em ERPs e sistemas externos, clique em Adicionar fonte e escolha o ERP.
2. Na janela Conectar ERP, preencha Nome desta conexão (como o ERP vai aparecer na tela e no cartão do cliente) e Endereço (URL) da API.
3. Preencha as credenciais do ERP escolhido (tabela abaixo).
4. Clique em Testar e conectar. O ChatISP faz uma chamada real ao ERP antes de gravar: só salva se a credencial funcionar.
5. Salvo, o ERP já nasce ligado e a primeira carga do espelho de assinantes começa em segundo plano. A tela pode ser fechada: a carga segue sozinha e a contagem de assinantes cresce na lista.

Campos por ERP

Mensagens ao testar

Editar

Na edição, os campos secretos (token, senha, client secret) vêm vazios com a dica Deixe em branco para manter a chave atual. Em branco, a credencial salva é mantida. No Hubsoft, para trocar a credencial, informe Client Secret e Senha do usuário juntos. Toda edição é validada com uma chamada real antes de gravar, religa o ERP e dispara uma nova carga do espelho.

Particularidades de cada ERP

IXC Provedor

• O espelho é montado a partir dos logins de acesso, contratos, clientes, grupos de velocidade e planos de venda. A velocidade do plano vem do grupo de velocidade do login.
• A sincronização periódica traz só o que foi alterado desde a anterior. Quando o IXC libera um contrato pelo pagamento sem marcar a alteração, o botão Atualizar do cartão relê aquele cliente direto no ERP.
• Financeiro: faturas em aberto (até 100 por cliente), último pagamento, boleto, link do gateway e Pix copia e cola quando a carteira gera Pix, com a imagem do QR Code fornecida pelo próprio IXC. O ChatISP não gera nem atualiza boleto no IXC.
• Fatura cobrada por cartão ou gateway ainda não emitida chega sem forma de pagamento e aparece marcada na janela de faturas.
• Desbloqueio em confiança pelo contrato, com os dias e restrições configurados no IXC. A liberação temporária do IXC não está disponível pela API.
• Lista os títulos por data de vencimento na própria API, o que alimenta a régua de cobrança automática sem espelho intermediário (Automação de envios).

Hubsoft

• Autenticação OAuth com client ID, client secret, usuário (e-mail) e senha.
• O espelho é montado a partir dos serviços de cada cliente. A sincronização periódica pede ao Hubsoft os serviços alterados desde o dia da anterior; a velocidade vem do texto do plano (por exemplo "200 Mbits").
• Financeiro: até 50 faturas pendentes por consulta, último pagamento, linha digitável, link do PDF e Pix copia e cola quando a carteira gera Pix.
• Desbloqueio em confiança pelo serviço, com o teto de dias definido no painel do Hubsoft.

SGP (TSMX)

• Usa as rotas de consulta da categoria URA da API do SGP, somente leitura. Token e aplicativo precisam estar corretos juntos.
• A API não oferece recorte por data: cada sincronização percorre a listagem inteira de clientes.
• O SGP não publica a velocidade em números, então o cartão mostra só o nome do plano.
• Financeiro: os títulos do contrato, cada um com linha digitável, link do boleto e Pix copia e cola; o último pagamento sai da mesma consulta. O botão Atualizar do cartão relê o cliente direto no SGP.
• Desbloqueio em confiança pela promessa de pagamento da URA do SGP (o limite de promessas no mês é regra do SGP e a recusa volta explicada). Localização por CPF/CNPJ ao vivo.

Gesprov

• Exige a API de monitoramento de serviços na instalação do Gesprov.
• A unidade que o Gesprov bloqueia, libera e fatura é o serviço; é ele que aparece como contrato no cartão.
• Cada sincronização percorre a listagem inteira de serviços e completa telefones e e-mail pelo cadastro de clientes.
• As consultas financeiras do Gesprov são feitas pelo CPF/CNPJ do cliente, guardado cifrado no espelho e aberto só no momento da consulta.
• Financeiro: faturas em aberto, Pix do gateway ou do boleto (sem Pix na fatura, o ChatISP pede um ao gateway, o que funciona com o gateway Efí), boleto em PDF. O último pagamento só aparece quando o Gesprov informa a data de liquidação.
• Desbloqueio em confiança pelo serviço; as regras (intervalo entre desbloqueios, serviço já ativo) são do Gesprov e a recusa volta explicada.

ReceitaNet

• Sistema de servidor único: o endereço já vem preenchido. Duas credenciais, qualquer uma pode faltar: o token da integração de cobrança via chat e o Client ID e Client Secret da Central do Assinante.
• Com o token, cada cobrança já traz o cadastro do cliente e o pagamento pronto (boleto, linha digitável e Pix copia e cola): o espelho nasce das próprias cobranças e a régua de cobrança por vencimento consulta a API direto.
• Com a Central do Assinante: segunda via com QR Code, faturas pagas com a data do pagamento e a liberação em confiança (notificação de pagamento). Sem a Central, o último pagamento não aparece e o desbloqueio não está disponível.

Pipesoft

• Client ID e Client Secret do usuário da API (Provedor > Controle de Usuário > API). Libere a esse usuário os controles cliente, plano e titulo; a escrita de cliente só é usada pela liberação em confiança.
• A listagem de clientes não traz telefone nem endereço: a carga completa consulta cada cadastro individualmente, em paralelo, e as sincronizações seguintes refazem a listagem e completam os cadastros por partes. Em bases de alguns milhares de clientes a primeira carga leva alguns minutos.
• Velocidade do plano pelo catálogo de planos do Pipesoft (o número é a velocidade aplicada, com a folga do provisionamento). Sem o controle de planos liberado, o cartão mostra só o nome do plano.
• Financeiro: todos os títulos do cliente, com linha digitável e Pix copia e cola; último pagamento; segunda via; localização por CPF/CNPJ ao vivo. O botão Atualizar do cartão relê o cliente direto no Pipesoft.
• Desbloqueio em confiança pela observação do Pipesoft: o cliente deixa de ser bloqueado por atraso até a data limite (5 dias por padrão) e a sessão é liberada.
• Régua de cobrança por vencimento pelo espelho de títulos do ChatISP, renovado a cada 6 horas.

Comparativo de capacidades por ERP

A localização por nome completo usa o espelho local, por isso vale para todos; a localização por documento consulta o ERP ao vivo. Como cada recurso aparece para o atendente está em Ficha do cliente: o que depende de cada ERP.

Espelho local e sincronização

Para identificar o cliente pelo telefone em milissegundos, sem depender do ERP responder naquele instante, o ChatISP guarda uma cópia enxuta dos assinantes de cada ERP ativo: o espelho local.

O que o espelho guarda

Uma linha por acesso (login ou serviço) com o código do cliente e do contrato no ERP, login da conexão, nome, plano, velocidade, situação normalizada, cidade, bairro, endereço, telefones e e-mail. CPF/CNPJ, senhas de conexão e credenciais que o ERP devolve junto são descartados. A exceção é o Gesprov, cujo documento fica guardado cifrado porque a API dele só faz cobrança por CPF/CNPJ.

Quando sincroniza

Nas cargas completas, acessos que sumiram do ERP passam a Cancelado no espelho, em vez de continuarem aparecendo como ativos.

Telefones

Todos os campos de telefone do cadastro entram no espelho, na ordem do ERP e sem repetir o mesmo número escrito de dois jeitos. Na busca, os números são normalizados com DDI 55 e o nono dígito do celular. Número sem DDD aproveita o DDD do número vizinho no mesmo campo.

Importar ERPs do Ravicor

Com o Ravicor conectado pelo pareamento, o botão Importar do Ravicor copia para o ChatISP os ERPs cadastrados no Ravicor, com endereço e credencial. O aviso {n} ERP(s) sincronizado(s) do Ravicor confirma.

• Os ERPs importados viram cadastros próprios do ChatISP, marcados como importado do Ravicor, com espelho próprio.
• Importar de novo atualiza endereço e credencial dos já importados e cria os novos. Nunca apaga nada: um ERP removido do Ravicor continua no ChatISP até ser excluído aqui.
• A caixa Usar este ERP no atendimento nunca é alterada pela importação: a escolha feita no ChatISP prevalece.
• Se o ERP recusar a credencial de um ERP importado (porque ela foi trocada no Ravicor), o ChatISP reimporta sozinho e tenta de novo.

Sistemas externos (integração genérica por API)

Qualquer sistema do provedor com uma API HTTP (um financeiro próprio, um CRM, um sistema de OS) pode ser integrado sem programação no ChatISP: você descreve as operações em JSON e a IA, os fluxos e o cartão do cliente passam a usá-las. O JSON é a única lista de operações permitidas: só o que estiver nele pode ser executado, sempre contra o endereço base cadastrado.

Cadastrar

1. Em ERPs e sistemas externos, clique em Adicionar fonte e escolha Outro sistema.
2. Preencha a janela Novo sistema (campos abaixo).
3. Clique em Salvar. O JSON é validado na hora; um erro de estrutura aparece como O JSON de operações não é válido, seguido do ponto com problema.
4. Use Testar na tabela para executar uma operação de verdade e ver a resposta.

Formato das operações

{
  "operacoes": [
    {
      "id": "faturas_abertas",
      "descricao": "Lista as faturas em aberto do cliente pelo CPF",
      "metodo": "GET",
      "caminho": "/api/v1/faturas?cpf={cpf}&situacao=aberta",
      "parametros": [{ "nome": "cpf", "descricao": "CPF do cliente, somente numeros" }],
      "resposta": "lista de faturas com vencimento, valor e link do boleto"
    },
    {
      "id": "liberar_confianca",
      "descricao": "Desbloqueio de confianca pelo codigo do cliente",
      "metodo": "POST",
      "caminho": "/api/v1/desbloqueio",
      "corpo": { "cliente": "{codigo}", "dias": 3 },
      "parametros": [{ "nome": "codigo", "descricao": "Codigo do cliente" }]
    }
  ]
}

O ChatISP não segue redirecionamentos e aproveita até 64 KB de cada resposta. Respostas de 200 a 299 contam como sucesso.

A tabela de sistemas

Colunas Nome (com o endereço base), Operações (quantas), Disponível para a IA, Último teste (data em verde ou vermelho), Situação e as ações Editar, Testar e Excluir (com o aviso Excluir este sistema? A IA e os fluxos deixam de usá-lo.).

A janela de teste lista as operações, abre um campo para cada parâmetro da operação escolhida e mostra a resposta com o código HTTP. Sem operações cadastradas, aparece Cadastre as operações no JSON para testar.

Onde as operações são usadas

• IA: com Disponível para a IA ligado, a IA recebe a lista de operações com as descrições e decide quando chamar cada uma. Veja Inteligência artificial.
• Fluxos: a etapa Consultar sistema escolhe o sistema, a operação e os parâmetros, e responde ao cliente com {resposta.campo} na mensagem. Sem sistema cadastrado, a etapa mostra Cadastre um sistema externo em Integrações para usar esta etapa. Veja Fluxos.
• Cartão do cliente: pelas convenções da próxima seção.

Convenções dos sistemas externos

Alguns recursos da ficha do cliente são ligados automaticamente quando o JSON de operações declara parâmetros com nomes combinados. Basta seguir os nomes:

Respostas embrulhadas em {"ok": true, "dados": {...}} são desembrulhadas automaticamente. Quando há mais de uma operação que serve, vale a com menos parâmetros. O vínculo manual a sistema externo só aparece quando o sistema declara a busca e o cartão do vinculado.

API do ChatISP (chaves) Recurso de plano

O card API do ChatISP ("Chaves para outros sistemas usarem a API: mensagens, conversas, contatos, ordens de serviço, agenda e indicadores, cada chave com as suas permissões.") cria as chaves que o ERP, o CRM, o portal do assinante, o monitoramento ou o BI do provedor usam para trabalhar com o atendimento pela API pública. A API pública e os webhooks fazem parte dos planos a partir do PREMIUM; o número de chaves ativas depende do plano (3 no PREMIUM, 10 no GOLD, sem limite no ENTERPRISE). Fora do plano, o card mostra o recurso trancado com o plano a partir do qual ele entra. O medidor ao lado do título mostra quantas chaves estão em uso.

O topo do card mostra o Endereço da API da sua instalação, com a dica a chave vai no cabeçalho Authorization: Bearer, e o botão Documentação da API, que abre a referência completa.

Criar uma chave

1. Clique em Nova chave.
2. Dê um Nome que identifique o sistema que vai usá-la. Esse nome aparece no histórico de tudo o que a chave fizer.
3. Ligue só as permissões de que a integração precisa (a tabela abaixo). Numa chave nova vêm ligadas Enviar mensagens, Consultar conversas e Abrir atendimentos.
4. Com mais de um número de WhatsApp conectado, escolha o Número de origem: o número por onde esta chave envia quando a chamada não informa a conexão. Sem isso, a API recusa o envio que não informa conexao_id. A opção Nenhum (a chamada precisa informar a conexão) deixa a escolha para cada chamada. Com um número só, o campo não aparece.
5. Ajuste o Limite por minuto: chamadas aceitas por minuto, padrão 60, máximo 10.000. 0 desliga o limite.
6. Clique em Salvar. A janela Chave criada mostra a chave completa com o botão Copiar.

Permissões da chave

As permissões ficam em três grupos. Cada uma libera um conjunto de operações da API:

Conexões, departamentos, atendentes, modelos, etiquetas e motivos ficam disponíveis para qualquer chave ativa, sem permissão: são os cadastros de que toda integração precisa para montar as chamadas. O código técnico de cada permissão e as operações exatas que ela libera estão em Permissões da chave (escopos).

A tabela de chaves

• Colunas Nome, Chave de API (só o início, para reconhecer), Permissões (uma etiqueta por permissão ligada), Usos (passe o mouse para ver o Último uso) e Situação (Ativa ou Inativa).
• Editar muda nome, permissões e limite, e permite desativar a chave sem apagá-la. A chave em si não muda: a integração continua com o mesmo valor, já com as permissões novas.
• Revelar mostra a chave completa de novo, para quem tem a permissão Integrações.
• Excluir apaga a chave; o sistema que a usava para de conseguir chamar a API.

As 37 operações, o formato das chamadas, os códigos de erro e a coleção para Postman e Insomnia estão na documentação da API: Introdução à API do ChatISP.

Webhooks de saída Recurso de plano

Um webhook avisa um sistema seu, por HTTP, quando algo acontece no atendimento. Faz parte do mesmo recurso de plano da API pública.

Criar um webhook

1. Clique em Novo webhook.
2. Informe Nome e Endereço (a URL que vai receber os avisos).
3. Marque os eventos (pelo menos um). Num webhook novo vêm marcados Mensagem recebida, Conversa criada e Conversa encerrada.
4. Clique em Salvar. A janela Webhook criado mostra o Segredo, que serve para conferir a assinatura de cada entrega.

Eventos disponíveis

Como as entregas funcionam

• Cada evento vira um POST com corpo JSON e os cabeçalhos X-ChatISP-Evento, X-ChatISP-Entrega e X-ChatISP-Assinatura, que leva o HMAC SHA-256 do corpo calculado com o segredo.
• O envio nunca atrasa o atendimento: o evento entra numa fila e é entregue em segundo plano, normalmente alguns segundos depois.
• Respostas de 200 a 299 contam como entregue. A espera máxima por resposta é de 10 segundos.
• Falhou, o ChatISP tenta de novo depois de 1 minuto, 5 minutos, 15 minutos, 1 hora e 6 horas. Depois da última tentativa, a entrega é descartada.

A tabela de webhooks

Colunas Nome (com a URL), Eventos, Último disparo (passe o mouse para ver o resultado; um número em destaque indica entregas na fila) e Situação. Ações: Editar (inclusive desativar; as entregas pendentes ficam guardadas até reativar), Testar (entrega na hora um evento de teste e informa Entrega de teste aceita ou Entrega de teste falhou, com o código ou o erro), Segredo (revela o segredo) e Excluir (as entregas pendentes são descartadas).

O conteúdo exato de cada evento, a conferência da assinatura em PHP, Node.js e Python, as regras de reenvio e de duplicatas estão em Webhooks de saída na documentação da API.

Google Agenda

O espelhamento dos compromissos no Google Agenda é individual: cada usuário conecta a própria conta Google em Minha conta, no card Google Agenda, pelo botão Conectar minha conta Google. A autorização abre numa aba da central de conexão da Ravi Systems; ao concluir, aparece Conta Google conectada. Seus próximos compromissos serão espelhados.

• O sentido é único: os compromissos em que o usuário é o responsável aparecem na agenda Google dele. O que for criado no Google não volta para o ChatISP.
• Com a conta conectada, tipos de compromisso configurados para isso podem gerar a sala do Google Meet automaticamente.
• Desconectar preserva os eventos já criados no Google; os próximos deixam de ser espelhados.

Detalhes em Agenda.

E-mail do sistema

O ChatISP envia poucos e-mails: convites para novos usuários e códigos de recuperação de senha. Esses e-mails saem por um canal de envio mantido pela Ravi Systems, sem necessidade de configurar servidor SMTP. Não existe SMTP próprio por instalação. As mensagens ao cliente final sempre saem pelo WhatsApp.

Segurança das credenciais

• Tokens, senhas e chaves de ERPs, do Ravicor e dos sistemas externos ficam cifrados no banco do ChatISP.
• Credenciais de ERP e de sistemas externos são de escrita apenas: depois de salvas, nunca voltam para a tela. Para trocar, digite a nova; em branco mantém a atual.
• A chave do Ravicor obtida pelo pareamento não aparece em tela nenhuma.
• As chaves da API do ChatISP e os segredos dos webhooks podem ser revelados de novo, por quem tem a permissão Integrações.
• Dados pessoais sensíveis que os ERPs devolvem (CPF/CNPJ, senhas de conexão) são descartados no espelho local, com a exceção do documento cifrado do Gesprov e da ReceitaNet.
• Sistemas externos só executam operações declaradas no JSON e só contra o endereço base cadastrado.

Problemas comuns