Notifiq

O notifiq é uma aplicação online de notificação de andamentos via WhatsApp. É o primeiro de outros produtos que serão disponibilizados para os clientes na plataforma engedigital.app.

Uma vez que a aplicação notifiq esteja integrada com a serventia, será possível enviar uma mensagem via WhatsApp para o usuário do cartório sempre que um determinado andamento ocorrer em algum protocolo. 

Iniciando

Antes de tudo precisamos ter o cliente(serventia) cadastrado na aplicação notifiq. Essa tarefa cabe à diretoria em parceria com a infra. Uma vez cadastrado, o cliente terá uma url específica dentro da plataforma engedigital.app. Para fins de testes, nesse documento adotaremos a seguinte url fictícia 1oficio.engedigital.localhost.

Quando acessarmos a url acima mencionada, teremos que efetuar login. 

Ao informarmos os dados de login, obtidos no momento do cadastro do cliente, e clicarmos no botão entrar, seremos jogados para a página inicial da organização(1oficio) dentro da plataforma engedigital.app. Veja a imagem abaixo:

Estando dentro da aplicação, devemos clicar no ícone do WhatsApp localizada na barra à esquerda. Esse ícone representa o produto notifiq. Ao clicarmos, iremos direto para a página de mensagens. Veja a imagem abaixo.

Esta página é onde fica todas as mensagens que serão enviadas via WhatsApp para os clientes. É como se fosse uma fila, onde toda vez que o cartório enviar uma notificação para o sistema notifiq através do webservice, essa página exibirá. 

Mas para o sistema começar a funcionar, precisamos primeiro conectar com o WhatsApp, e em seguida cadastrar os andamentos que serão permitidos para notificação.

Conectando dispositivo

O notifiq utiliza uma biblioteca que simula o WhatsApp Web. Através dessa biblioteca é possível manusearmos "virtualmente" um navegador web para acessar o site do WhatsApp Web e em seguida parearmos a aplicação notifq com um dispositivo real que possua WhatsApp instalado, seja android ou ios. O pareamento se dá pela leitura do qr code que é obtido pela biblioteca, exatamente como se você estivesse pareando o seu celular diretamente no site o WhatsApp Web. 

Então, estando na página de mensagens, na parte superior da listagem à direita, existe um botão com ícone de telefone escrito Conectar. Ao clicar nesse botão. Será aberta uma janela com um qr que deve ser escaneado através do aplicativo WhatsApp instalado em um celular. Na própria janela do qr code estão os passos que devem ser seguidos. Mas o processo é semelhante ao realizado no site oficial do WhatsApp Web. Veja a imagem abaixo.

Ao finalizar o escaneamento, aguarde alguns segundos para a sincronização. Se tudo ocorrer bem, a caixa será fechada automaticamente, e você poderá ver o número do dispositivo conectado, como mostra a imagem abaixo:

É possível parear somente um dispositivo. Caso queira trocar de dispositivo, basta desconectar e conectar novamente com o novo dispositivo, seguindo exatamente os mesmos passos. Porém, é importante ter em mente que as mensagens enviadas pelas serventias no período em que não há dispositivo conectado, ficarão como pendentes e precisarão serem reprocessadas manualmente, quando houver um dispositivo conectado novamente.

Configurando Andamentos

Para cadastrar os andamentos devemos clicar no menu Andamentos, seremos levados para a listagem de andamentos.  Em seguida vamos direto clicar no botão Novo Andamento, a tela seguinte será aberta:

Os três campos são auto explicativos  e obrigatórios. O campo template é a mensagem propriamente que será entregue ao usuário. Clique no botão Criar Andamento e você será redirecionado para a pagina de edição. Depois vá para a listagem de andamentos clicando no menu Andamentos.

Agora que já temos um dispositivo pareado, e andamentos configurados, podemos partir para a parte de integração com as serventias. 

Integração

Para integrar a serventia com a aplicação notfiq você vai precisar obter o endereço do webservice(WSDL) e o Token de autenticação. Essas informações estão disponíveis no menu Integrações. Veja a imagem abaixo:

O Token de autenticação deve ser enviado no cabeçalho http X-Auth-Token, para toda requisição feita aos métodos do webservice.

Teste

Você pode testar a integração utilizando alguma ferramenta que faça requisições soap, como Postman ou Soap UI. Nesse exemplo iremos utilizar o SoapUI por já ser específico para serviços soap, mas você pode fazer uso da ferramenta que preferir.

Essa é a tela inicial do SoapUI.

Vamos clicar no botão SOAP indicado pela seta vermelha, localizado no canto superior esquerdo, ilustrado na imagem acima. Uma caixa será aberta com dois campos.

Cole o endereço do wsdl no segundo campo, Initial WSDL, como indicado pela seta vermelha. O campo Project Name será preenchido automaticamente. Deixe a opção Create Requests marcada, clique em ok. 

O SoapUI exibirá no lado esquerdo a lista de métodos disponibilizados pelo webservice, nesse caso são três: GetAndamentos, NotificarStatusDeAndamento e Ping. Veremos o funcionamento de cada um.

Para testar a chamada aos métodos com SoapUI, basta clicar com o botão auxiliar sobre o método desejado e escolher a opção New request, ou então clicar no ícone de mais(+) do método desejado para abrir uma request já criada quando o wsdl foi importado. O SoapUI já cria uma estrutura XML padrão de envelopamento que é necessário para realizar requisições soap.

Ping()

O método Ping testa a comunicação com a api, ele não recebe nenhum parâmetro e simplesmente retorna uma string com o valor Pong e um emoji sorridente. 

Para executar o método Ping, basta ir até o mesmo na lateral onde lista os métodos e clicar em New request. Será aberta uma nova janela dividida em dois lados. À esquerda tratas-e da configuração do método que será executado, é onde informamos os parâmetos do método, que no caso do Ping não há nenhum. O lado da direita é onde a resposta do webservice será exibida.

Agora vamos realizar a requisição de fato. Primeiramente precisamos configurar o cabelaçho X-Auth-Token, que é obrigatório para a chamada a todos os métodos do web service, logo, os passos ilustrados na imagem abaixo deve-se repetidos para qualquer um dos métodos que se deseja testar.

Passo 1, primeiramente clicamos na opção Headers. Passo 2, clicamos no ícone de + para adicionar um novo cabeçalho. Passo 3, na caixa que se abre digitamos o nome do cabeçalho. Passo 4, e então clicamos no botão ok. Agora é só colar o token no local apontado pela seta na imagem abaixo e dar enter.

Agora já podemos executar o método clicando no botão verde indicado pela seta na imagem abaixo. Se tudo ocorrer bem o resultado deve ser "Pong 😁".

Observe que a janela da direita, onde fica a resposta da execução do método, possui duas abas em sua lateral esquerda. A aba XML é padrão e retorna somente o corpo da resposta. Já a aba RAW mostra a resposta completa em HTTP, que inclui os cabeçalhos e o corpo da resposta.

Agora vamos continuar com os outros métodos. Alguns passos serão suprimidos por serem idênticos aos que vemos no método Ping.

GetAndamentos()

Este método lista os andamentos que a serventia possui cadastrados na aplicação notifiq. Somente serão permitidas notificações para estes andamentos. O método GetAndamentos não recebe nenhum parâmetro, e retorna uma lista de objetos com as propriedades Number(número do andamento), Name(nome do andamento) e Template(mensagem). Como mostra imagem abaixo;

A propriedade Template é a mensagem que será enviada ao usuário via whatsapp, e pode conter variáveis que serão substituídas durante o envio da mensagem. Essas variáveis devem ser fornecidas pela serventia durante o envio da notificação. Veremos isso com detalhes na próxima sessão, onde veremos o método NotificarStatusDeAndamento.

NotificarStatusDeAndamento(int AndamentoNumero, int WhatsappNumero, string Data)

Este método recebe o número do andamento que ocorreu(AndamentoNumero), o número do telefone whatsapp do usuário envolvido no protocolo em questão(WhatsappNumero), e no último parâmetro(Data) recebe uma string JSON contendo as variáveis que são usadas no template referente ao andamento em questão e que está listado no método GetAndamentos visto anteriormente. O número do whatsapp deve seguir o padrão internacional de telefone, exemplo: 556677778888. Onde 55 é o código do pais, 66 código de área, e 77778888 é o número do whatsapp. Não é necessário informar o digito 9 antes do número do telefone.

Agora que sabemos as informações do método NotificarStatusDeAndamento, vamos realizar uma notificação. Vamos então ao SoapUI e criarmos uma nova requisição (New request). Veja que o SoapUI já identifica o nome de todos os parâmetros e os preenche com um sinal de interrogação(?) indicando onde você deve entrar com as informações reais. Entre com os dados corretamente e clica no botão verde para executar o método.

Se você fez todos os passos corretos receberá a resposta contendo uma string simples de "Ok", como ilustra a imagem acima.

Agora se você voltar na página de mensagens na aplicação notifiq, poderá ver a mensagem que foi enviada. Veja a imagem abaixo:

Vídeo da ferramenta