Documentação protheus x isocrm.
A quem se destina
Este documento destina-se a todos os usuários do Sistema isoCRM.
Objetivo
Capacitar o usuário a configurar o Protheus.
Inicio da configuração
Objetivo do plugin
O objetivo do plugin é fazer com que haja a integração dos dados entre o Protheus e o ISO CRM de maneira automática e/ou manual. Através de uma API de comunicação disponibilizada pelo ISO CRM, o Protheus faz o envio e leitura dos dados, utilizando como critério alguns campos de controle, como: “Integra com ISO?”, “Data/Hora” da última integração, “Data/Hora” da última alteração do registro no Protheus, “Número de tentativas (attempts)” que ocorreram erros de integração e o “Código ISO” para controle da chave entre o Protheus e o ISO CRM. Através do uso de um “robô” configurado no sistema de agendamentos (workflow/scheduler) do Protheus, é possível realizar a integração de forma automática.
Fluxo de dados
A comunicação dos dados pode ser exemplificada de maneira mais simples no diagrama abaixo. Basicamente o que existe é uma API no sistema da ISO CRM que é responsável por realizar entrada de dados do Protheus para ele e a saída de dados dele para o Protheus. A comunicação tanto de entrada como de saída de dados é iniciada pelo Protheus através do uso de um robô configurado no agendador do configurador e/ou manualmente através do uso da ferramenta diretamente no menu pelo Protheus.
Estrutura de dados.
A seguir, será exibido a estrutura de dados que foi criada no protheus para que o plugin de integração com o CRM funcione de maneira adequada. Foram necessários criar parâmetros, tabelas, índices e campos, conforme a seguir:
Menu
O caminho sugerido para execução da ferramenta de integração via Protheus é o seguinte:
Faturamento->Atualizações->isoCRM->API isoCRM
Parâmetros
Lista dos parâmetros existentes atualmente que podem ser configurados e que irão afetar o funcionamento da ferramenta de integração:
Figura 1 - Local no servidor do arquivo CRT do certificado
A Figura 1* representa o parâmetro “ZZ_CERCRT”, que indica o local, a partir do “system_path” do servidor, onde está localizado o arquivo .CRT do certificado digital para uso na conexão SSL.
Figura 2 - Local no servidor do arquivo CST do certificado
A Figura 2* representa o parâmetro “ZZ_CERCSR”, que indica o local, a partir do “system_path” do servidor, onde está localizado o arquivo .CST do certificado digital para uso na conexão SSL.
Figura 3 - Local no servidor do arquivo KEY do certificado
A Figura 3* representa o parâmetro “ZZ_CERKEY”, que indica o local, a partir do “system_path” do servidor, onde está localizado o arquivo .KEY do certificado digital para uso na conexão SSL.
Figura 4 - Senha do certificado digital
A Figura 4* representa o parâmetro “ZZ_CERPASS”, onde é informado a senha que foi utilizada para geração dos arquivos do certificado digital para integração SSL.
Figura 5 - Data da última integracao dos clientes no isoCRM.
A Figura 5* representa o parâmetro “ZZ_DTCLI”, utilizado para determinar a última data e hora de integração da entidade: “ENTRADACLIENTE”. Esse parâmetro pode ser utilizado como filtro na consulta dos dados da API da ISO CRM. Dependendo da entidade de consulta, essa data será enviada para a API da ISO CRM e, dessa forma, a API irá retornar apenas registros que foram alterados a partir dessa data.
Figura 6 - Data da última integracao dos estoques no isoCRM.
A Figura 6* representa o parâmetro “ZZ_DTEST”, utilizado para determinar a última data e hora de integração da entidade: “ENTRADAARMAZEMESTOQUE”. Esse parâmetro pode ser utilizado como filtro na consulta dos dados da API da ISO CRM. Dependendo da entidade de consulta, essa data será enviada para a API da ISO CRM e, dessa forma, a API irá retornar apenas registros que foram alterados a partir dessa data.
Figura 7 - Data da última integracao dos pedidos no isoCRM.
A Figura 7* representa o parâmetro “ZZ_DTPED”, utilizado para determinar a última data e hora de integração da entidade: “ENTRADAPEDIDO”. Esse parâmetro pode ser utilizado como filtro na consulta dos dados da API da ISO CRM. Dependendo da entidade de consulta, essa data será enviada para a API da ISO CRM e, dessa forma, a API irá retornar apenas registros que foram alterados a partir dessa data.
Figura 8 - Nome da tabela que será utilizada para: Autenticação
A Figura 8* representa o parâmetro “ZZ_TAUTH” que é utilizado para definir o nome da tabela customizada utilizada para: Autenticação. Esse parâmetro existe para permitir utilizar diferentes nomes de tabelas customizadas que estão disponíveis, dependendo da empresa/filial em questão. Essa tabela é utilizada para definir o cabeçalho, usuário e senha e URL para realizar a autenticação na API da ISO CRM e obter o “token da sessão” para comunicação entre as ferramentas.
Figura 9 - Nome da tabela que será utilizada para: Entidades de Exportação
A Figura 9* representa o parâmetro “ZZ_TENTEXP” que é utilizado para definir o nome da tabela customizada utilizada para: Entidades de Exportação. Esse parâmetro existe para permitir utilizar diferentes nomes de tabelas customizadas que estão disponíveis, dependendo da empresa/filial em questão. Essa tabela é utilizada para definir o nome, URL e SQL para consulta dos dados das entidades de exportação (do Protheus para o ISO CRM), comumente chamadas de entidade de “ENTRADA”.
Figura 10 - Nome da tabela que será utilizada para: Entidades de Importação
A Figura 10* representa o parâmetro “ZZ_TENTIMP” que é utilizado para definir o nome da tabela customizada utilizada para: Entidades de Importação. Esse parâmetro existe para permitir utilizar diferentes nomes de tabelas customizadas que estão disponíveis, dependendo da empresa/filial em questão. Essa tabela é utilizada para definir o nome, URL e SQL para consulta dos dados das entidades de importação (do ISO CRM para Protheus), comumente chamadas de entidade de “SAIDA”.
Figura 11 - Nome da tabela que será utilizada para: Agendamentos
A Figura 11* representa o parâmetro “ZZ_TJOBS” que é utilizado para definir o nome da tabela customizada utilizada para: Agendamentos. Esse parâmetro existe para permitir utilizar diferentes nomes de tabelas customizadas que estão disponíveis, dependendo da empresa/filial em questão. Essa tabela é utilizada para definir quais dias, horários e recorrência determinada entidade de exportação ou importação será executada.
Obs.: O tempo de intervalo informado nessa tabela está diretamente ligada com o tempo de intervalo do agendador. Sendo necessário mantê-los configurados de tal forma que permita a execução deles no momento correto.
Figura 12 - Nome da tabela que será utilizada para: Logs
A Figura 12* representa o parâmetro “ZZ_TLOG” que é utilizado para definir o nome da tabela customizada utilizada para: Logs. Esse parâmetro existe para permitir utilizar diferentes nomes de tabelas customizadas que estão disponíveis, dependendo da empresa/filial em questão. Essa tabela é utilizada para armazenar qualquer apenas erros de integração que ocorrer entre as tentativas de comunicação das ferramentas. Através dela é possível identificar o problema para tentar corrigi-lo.
Tabelas customizadas
Abaixo a lista de tabelas utilizadas atualmente pela ferramenta de integração da API ISO CRM.
ZZA – isoCRM - Entidades Exportação
Detalhes sobre a tabela utilizada para: Entidades de Exportação. Essa tabela é utilizada para definir o nome, URL e SQL para consulta dos dados das entidades de exportação (do Protheus para o ISO CRM), comumente chamadas de entidade de “ENTRADA”.
ZZB – isoCRM – Jobs
Detalhes sobre a tabela utilizada para: Agendamentos. Essa tabela é utilizada para definir quais dias, horários e recorrência determinada entidade de exportação ou importação será executada.
ZZC – isoCRM – Entidades Importação
Detalhes sobre a tabela utilizada para: Entidades de Importação. Essa tabela é utilizada para definir o nome, URL e SQL para consulta dos dados das entidades de importação (do ISO CRM para Protheus), comumente chamadas de entidade de “SAIDA”.
ZZD – isoCRM – Autenticação
Detalhes sobre a tabela utilizada para: Autenticação. Essa tabela é utilizada para definir o cabeçalho, usuário e senha e URL para realizar a autenticação na API da ISO CRM e obter o “token da sessão” para comunicação entre as ferramentas.
ZZE – isoCRM – Logs
Detalhes sobre a tabela utilizada para: Logs. Essa tabela é utilizada para armazenar qualquer apenas erros de integração que ocorrer entre as tentativas de comunicação das ferramentas. Através dela é possível identificar o problema para tentar corrigi-lo.
Campos customizados
Campos de controle de última integração
Esses campos customizados são utilizados para memorizar, individualmente por registro, a última integração que ocorreu com sucesso para o registro em questão. Essa informação também é utilizada em alguns filtros nas consultas SQLs das entidades. Elas trabalham em conjunto com o controle de alterações nativa do Protheus: S_T_A_M_P_ e I_N_S_D_T_:
https://tdn.totvs.com/pages/viewpage.action?pageId=563943271
Campos de controle de tentativas (attempts)
Esses campos customizados são utilizados para memorizar, individualmente por registro, a quantidade de tentativas, sem sucesso, que ocorreram para o registro em questão. Essa informação também é utilizada em alguns filtros nas consultas SQLs das entidades. Elas trabalham em conjunto com o controle de alterações nativa do Protheus: S_T_A_M_P_ e I_N_S_D_T_:
https://tdn.totvs.com/pages/viewpage.action?pageId=563943271
Campos de controle de código ISO de retorno de sucesso do cadastro
Esses campos customizados são utilizados para memorizar, individualmente por registro, o “código ISO” obtido na integração entre o Protheus e o ISO CRM. Esse código é chamado de: “codigo_externo” nas propriedades de integração dos JSON da documentação da API da ISO CRM. Ele é a chave que existe para controle da informação entre o registro do Protheus e a API da ISO CRM.
Campos de identificação de integração com o isoCRM
Esses campos customizados são utilizados para memorizar, individualmente por registro, se o registro em questão será enviado nas integrações ou não.
Campos de bloqueio de registro
Esses campos customizados são utilizados para memorizar, individualmente por registro, se o registro em questão está bloqueado (Na API: I=Inativo) ou não (Na API: A=Ativo).
Agendador
O agendador é uma ferramenta nativa do Protheus onde é possível realizar configurações de rotinas a serem executadas em determinados períodos e recorrência. Para que a integração da ferramenta seja realizada de forma automática, é necessário configurador a rotina: “ISOCRM_WF()” dentro de um agendamento, conforme o sugerido abaixo.
Obs.: Na chamada da rotina, é necessário informar a empresa e filial no parâmetro, seguindo os parâmetros respectivamente: ISOCRM_WF(código da empresa, código da filial), onde, para a empresa “04” e filial “01”, ficaria: ISOCRM_WF(“04”,”01”).
Funcionamento da Ferramenta de Integração (plugin)
A ferramenta de integração do Protheus com o ISO CRM é dividida em abas, onde, cada aba representa uma área do programa que é utilizada para determinar algumas funcionalidades:
Aba: Integração TOTVS P/ ISOCRM (ENTRADA)
Nessa aba são configuradas as entidades que irão ter os dados enviados do Protheus para a API da ISO CRM. Essas entidades são chamadas de entidades de “ENTRADA” na documentação da API.
Figura 13 - Integração TOTVS P/ ISOCRM (ENTRADA)
Botão: Parado
Para iniciar a execução MANUAL de exportação das entidades marcadas na lista, SEM respeitar as regras de agendamento; ou seja, será executada na mesma hora; basta clicar no botão “PARADO” em aguardar a execução da integração e, posteriormente, visualização dos erros ocorridos na aba “logs”.
Botão: Operação
O campo de seleção “1 – Post” e “2 – Put” é utilizado para definir o tipo de integração a ser realizada. Atualmente, apenas a integração “1 – Post” está sendo utilizada pela API da ISO CRM. Portanto, não há necessidade de alterá-lo.
Botão: Zerar Tentativas
Existe um controle de tentativas de integração (attempts) através do uso dos “Campos de controle de tentativas (attempts)” informados anteriormente na documentação. Esses campos são incrementais e irão aumentar o seu número a cada tentativa de integração fracassada. Esses campos são utilizados nas consultas SQLs das entidades para evitar que haja uma tentativa indefinida de integração de um registro. Caso queira realizar a limpeza desses campos de controle, para iniciar novas tentativas de integração desses registros com erro, basta executar o botão “Zerar Tentativas”.
Obs.: Cada entidade poderá definir em sua consulta SQL o número de tentativas aceitas até que ele deixe de ser integrado. Para tanto, é necessário verificar os “Campos de controle de tentativas (attempts)” nas tabelas e na consulta.
Tela de manutenção do cadastro da Entidade de Exportação
Nessa tela são definidas as configurações de agendamento, URL e consulta SQL para listar quais registros serão integrados do Protheus para a API do ISO CRM (Entrada). Conforme os critérios aplicados, serão exibidos os registros aptos para a próxima integração. Caso a consulta não traga nenhum registro, significa uma das possibilidades abaixo:
1) A consulta SQL está incorreta;
2) Alguns registros que estão com erro atingiram o limite máximo de tentativas de integração (attempts)
3) Todos os registros aplicáveis foram integrados;
4) Não há novos registros a serem integrados;
Em outras palavras: qualquer registro que aparecer na tabela após a execução do SQL, serão os registros a serem integrados na próxima tentativa de integração, respeitando os critérios de agendamento.
Figura 14 - Tela de manutenção do cadastro da Entidade de Exportação
Figura 15 - Campos para configurações da Entidade de Exportação
Aba: Integração ISOCRM P/ TOTVS (SAIDA)
Nessa tela são definidas as configurações de agendamento, URL e consulta SQL para listar quais registros serão integrados do da API do ISO CRM (Saida) para o Protheus.
Obs.: As configurações de leitura e vínculo das propriedades está definida em código conforme documentação da API da ISO CRM.
Figura 16 - Integração ISOCRM P/ TOTVS (SAIDA)
Figura 17 - Campos para configurações da Entidade de Importação
Aba: Autenticação
Nessa tela são definidas as configurações de autenticação, usuário e senha e URL para gerar o “token de sessão” que será utilizado pela ferramenta de integração.
Obs.: A cada novo “token de sessão” gerado pelo usuário em questão, o último será desativado automaticamente.
Aba: Logs
Nessa tela são exibidos todos os “Logs de erro” que ocorreram nas tentativas de integração. Através da leitura desses erros é possível identificar e, posteriormente, corrigir, erros nas tentativas de integração entre a ferramenta do Protheus e a API da ISO CRM.
Figura 18 – Logs de erros
Botão: Parado
Para iniciar a execução MANUAL de importação e exportação das entidades marcadas na lista, SEM respeitar as regras de agendamento; ou seja, será executada na mesma hora; basta clicar no botão “PARADO” em aguardar a execução da integração e, posteriormente, visualização dos erros ocorridos na aba “logs”.
Exemplos de erros gerados
Abaixo uma seleção de alguns erros que podem ser encontrados na tentativa de integração entre as ferramentas. É possível encontrar erros gerados automaticamente pelo Protheus, como também, erros na tentativa de conexão com a API ou mensagens de retorno dos erros fornecidos pela API em determinadas tarefas. Ou seja, poderão existir erros do Protheus e/ou da API da ISO CRM; sendo necessário que o utilizador identifique cada um e aplique a tratativa necessária conforme cada situação apresentada. Para facilitar a identificação de erros, cada linha do “log de erro” selecionada irá apresentar detalhes de onde ele veio e em qual entidade ele estava tentando executar: Entrada ou Saída; como também, o respetivo nome da entidade em questão. Por último, é importante também notar que, eventualmente, alguns erros na aplicação podem não ser memorizados nessa tabela e estarem disponíveis apenas no “console.log” do servidor. Portanto, para uma análise completa, recomenda-se começar a leitura dos erros na aba de “Logs” e, posteriormente, caso não seja encontrado uma causa, procure olhar o log do “agendador” e, por fim, o “console.log” do servidor.
Figura 19 - Exemplo de erro de campo obrigatório não preenchido
Figura 20 - Exemplo de erro de campo obrigatório não preenchido
Figura 21 - Exemplo de erro de campo obrigatório não preenchido ou não encontrado
Figura 22 - Exemplo de erro de campo obrigatório não preenchido ou não encontrado
Figura 23 - Exemplo de erro de integração e/ou comunicação entre o Protheus e a API da ISO CRM
Outras informações e dicas
Pré-requisitos para instalação da ferramenta de integração
Existem alguns pré-requisitos que a ferramenta de integração exige para que possa ser instalada e configurada corretamente no ambiente do servidor do Protheus:
1) Uma janela de oportunidade de ao menos um dia sem ninguém acessando o Protheus enquanto a manutenção é realizada.
2) Acessos à base de produção. Usuário, senha, endereço, porta e nome do ambiente no servidor
3) É necessário que os certificados (.CRT, .KEY, .CSR) estejam na pasta dentro do servidor: "Protheus_data\certs\[nome_da_empresa]"
4) Habilitar controle de S_T_A_M_P_ e I_N_S_D_T_. Para tanto, é necessário que as chaves abaixo sejam configuradas no dbaccess.ini. Dependendo da estrutura, é necessário solicitar para a TOTVS essa alteração:
UseRowInsDt=1
UseRowStamp=1
Mais detalhes em:
https://tdn.totvs.com/pages/viewpage.action?pageId=563943271
5) Ter acesso para compilar em um RPO que depois será direcionado para a produção
Como converter um arquivo de certificado .pem ou .prf em .crt, .csr e .key.
Dicas de como gerar os arquivos de certificado ".crt", ".key" e ".csr" a partir de um arquivo ".pem" ou ".pfx":
1) Programas necessários para realizar a conversão:
Aqui está a lista dos binários do OpenSSL para instalar (inclusive no Windows):
https://wiki.openssl.org/index.php/Binaries
2) [Etapa opcional] Converter ".PFX" para ".PEM".
Obs.: Geralmente o arquivo ".PEM" já é enviando junto com o ".PFX" pela própria provedora do certificado. Caso você já tenha o arquivo ".PEM", não é necessária essa etapa.
Converter PFX para PEM:
openssl pkcs12 -in certificate.pfx -out certificate.cer -nodes
https://support.kaspersky.com/ksc/14.2/en-us/201428.htm
3) Gerar os arquivos ".CRT", ".CSR" e ".KEY" através do ".PEM".
Ao converter um arquivo ".PFX" para o formato ".PEM", o OpenSSL colocará todos os certificados e a chave privada em um único arquivo.
Você precisará abrir o arquivo em um editor de texto e copiar cada certificado e chave privada (incluindo as instruções BEGIN / END) em seu próprio arquivo de texto individual e salvá-los como certificate.cer, CACert.cer e privateKey.key, respectivamente.
Maiores Detalhes:
4) Colocar dentro do "Protheus_data\certs\[nome_da_empresa]" do servidor os certificados da empresa nos seguintes formatos: ".CRT", ".KEY" e ".CSR"
Obs.: Substituir "[nome_da_empresa]" pelo nome da empresa para separar os arquivos corretamente.
Documentação da API ISO CRM
A documentação da API da ISO CRM contém exemplos e detalhes de funcionamento das entidades envolvidas no processo de integração da ferramenta. Através desse endereço também é possível fazer download da “collection do Postman” para realização de testes de integração. Segue o link para acesso:
https://documenter.getpostman.com/view/8109129/TVssj8nT#intro
Figura 24 - Documentação da API da ISO CRM
Também é possível realizar testes de integração através da “Colection do Postman”. Para tanto, basta clicar no botão abaixo:
