Integrador
O Integrador do Gestão de Relacionamento | CRM é uma ferramenta voltada para facilitar a integração dos demais sistemas disponíveis no mercado com o Gestão de Relacionamento | CRM, e vice e versa. Ele permite criar e gerenciar as integrações através de configurações do sistema, ou parametrização, sem a necessidade do desenvolvimento de novos fontes.
Em termos de execução, o Integrador somente executa o que lhe foi configurado, não realiza todas as ações automaticamente. O que é feito pelo Integrador é interpretar e executar as configurações de uma determinada integração, já cadastrada, no momento em que é chamada para execução, através de um URL. Com isso, é necessário configurá-lo corretamente e executar a chamada. Existem três tipos de execução, que possuem mesma estrutura de configuração, cada um com sua particularidade:
Para utilizar o Integrador é necessário a utilização de um software capaz de realizar requisições, criando o pacote HTTP com parâmetros específicos no header. Para isso é recomendável o software Postman.
A execução de cada integração é através da chamada de uma URL, com alguns parâmetros de execução da integração informados e pode conter parâmetros configurados para uma integração exclusiva, além dos valores obrigatórios, sendo:
- EMPRESA_ID ou EMPRESA_FILIAL_ID: identificador da empresa do CRM ou identificador de qual empresa e filial do CRM, conforme sistema do cliente for para múltiplas empresas;
- BASE_CRM: nome da base de dados do cliente no CRM;
- INTEGRACAO_SERVICO_ID: identificador do serviço a ser executado;
- TOKEN_CRM: chave de segurança que permite acesso em determinada base de dados, conforme permissão. Esse valor deve ser adicionado no header da requisição.
O TOKEN_CRM é obrigatório em todas as integrações.
Exemplo:
URL para realizar a chamada de uma determinada integração: https://Integrador.crmsenior.com.br/Integrador/integrar.php?empresa_id=1&base_crm=crmsenior&servico_integracao_id=1
Pacote completo utilizando a ferramenta Postman para envio da requisição:
Params
Headers
Cada identificador de empresa do CRM por cliente gera um arquivo de log de erro e de acesso, que irão registrar os passos executados e os erros encontrados durante a execução, sendo avisos ou erros fatais, para possíveis correções. Para qualquer integração a ser executada, é preciso configurar os dados de conexão em um arquivo que será carregado pelo Integrador.
O Integrador está arquitetado sobre cinco tabelas do CRM, onde é realizado uma consulta conforme a integração a ser executada e relacionada as informações para integração entre os sistemas, sendo elas:
| Tabelas | Descrição |
|---|---|
| CONEXAO_INTEGRACAO | Essa tabela é responsável pela configuração das conexões de acesso do Integrador aos provedores ou receptores de dados. |
| INTEGRACOES | São definidas as integrações com determinado sistema, e suas particularidades. |
| CAMPOS_INTEGRACAO | Descrito todos os campos os quais farão parte da integração e seus iguais, no sistema receptor ou provedor. |
| DEPENDENCIAS | Quais são as dependências de uma determinada integração, ou seja, os valores originados em outras tabelas do sistema. |
| REGRAS |
As regras para execução da integração, sendo vinculadas aos campos, serão executadas para ajustar as informações conforme o sistema, receptor ou o banco de dados do cliente no CRM está preparado para receber. |
Para que seja possível ajustar as informações da integração conforme o sistema esteja preparado para receber, é preciso carregar as regras disponíveis. A maior parte das regras que são executadas são parte do Integrador, construídas em código e carregadas pelo Integrador em tempo de execução.
Para cada tipo de integração é carregado um código de regra diferente, pois elas se comportam diferentemente para cada tipo. Há casos em que se faz necessário criar regras específicas para uma integração, ou seja, customizar regras para os clientes, para suprir um processo ou ajustar uma informação, permitindo que o sistema receptor ou banco de dados do CRM entenda a informação e processe-a corretamente. Para tal é necessário a ação do desenvolvimento.
Importante
Para que a regra seja executada em um campo da integração, é preciso que a mesma esteja cadastrada na tabela REGRAS com as informações pertinentes.
Com as definições do Integrador apresentadas, confira o passo-a-passo para criação das integrações GET/INFO e SET.
Em casos de integrações via web service o Integrador gera um log de envio e de recebimento de XML, nomeado da seguinte forma: base_empresa_requisição.xml e base_empresa_resposta.xml, onde base é a base do cliente igual ao parâmetro base_crm e empresa é o id da empresa do cliente igual ao parâmetro empresa_id ou empresa_filial_id.
Para toda integração executada com status de erro, o Integrador tentará enviar uma mensagem de e-mail para o e-mail geral do cliente com o conteúdo do log de erro gerado pela integração, os arquivos XML do envio e recebimento caso a integração seja por web service e as mensagens de retornadas pela integração.
Configurações do arquivo de conexão
Toda integração tem como pré-requisito uma conexão, que é configurada em um arquivo a ser carregado pelo Integrador. Este arquivo é interpretado junto ao código fonte do Integrador e é importante atentar à caracteres como: parênteses, vírgulas e aspas a mais ou a menos.
Para configurar a conexão, o arquivo precisa estar no diretório de configurações do Integrador com a nomenclatura NOME-DA-BASE.connection. Esse arquivo deve conter um array com os dados de conexão, onde cada índice do array representa uma conexão.
Exemplo:
No exemplo, o índice da conexão, destacado em vermelho será referenciado posteriormente na tabela CONEXAO_INTEGRACAO. O índice DEFAULT é obrigatório e deve existir em toda configuração, ele representa a conexão com o próprio CRM e deve conter os dados de conexão do CRM. Cada nova conexão configurada deve ter seu próprio índice.
Existem três tipos de conexão possíveis para o Integrador, são elas por Banco de Dados, Web Service e API (web, http). Cada uma das conexões possuem seus próprios parâmetros e um layout para configurar os dados da conexão, entretanto para a paginação, todas as conexões utilizam a mesma estrutura para a configuração. Os layouts para configuração da conexão de cada tipo de conexão são:
Banco
Para cada conexão serão usados campos diferentes, vale a pesquisa para descobrir a melhor forma de conectar-se.
- dbname: nome do banco;
- user: usuário de conexão ao banco;
- password: senha de conexão;
- host: servidor da conexão;
- driver: a ferramenta de conexão que o Integrador vai usar, difere de banco para banco e há um número limitado de drivers para conexão, sendo eles: ibm_db2 para IBM-db, pdo_mysql para MySQL, pdo_pgsql para PostgreSQL, pdo_sqlite para SQLite. O Integrador usa uma ferramenta para criar as conexões com os drivers, e, caso seja necessária uma configuração específica, é possível acessar a documentação da ferramenta que traz os passos para a configuração.
- charset: encoding para a conexão, padrão UTF-8;
- dsn: um texto de conexão customizado;
- pdo: funciona como o driver, para conexões customizadas.
Web service
Conexões web service possuem os mesmo campos, sendo alguns obrigatórios:
- host: servidor da conexão, obrigatório;
- port: porta da conexão;
- charset: encoding para a conexão, padrão UTF-8;
- header: array com dados de cabeçalho para a requisição, alguns web services precisam enviar autenticação por cabeçalho;
- body: um array com um template de corpo padrão para as requisições, no qual o índice deve conter um valor "#BODY#" que será substituído pelo corpo da requisição gerado pelo Integrador e funciona como se fosse uma capa de envio para todas as requisições.
API
Conexões via API são utilizadas para carregar valores pela web mas sem a necessidade de um protocolo WSDL. As conexões via API só aceitam transações de conteúdo JSON, ou seja, se a API consumida pelo integrador não retornar valores JSON a integração não será executada.
- host: servidor da conexão, obrigatório;
- port: porta da conexão;
- method: qual o método de envio da mensagem para a API, o padrão é GET e os tipos suportados são: GET, POST, PUT, PATCH e DELETE;
- header: um array com os campos de headers padrão para a integração, pode ser usado para preencher campos de authorization, por exemplo. Este campo é mesclado ao campo setado na coluna CONSULTA para as integrações GET e INFO.
Paginação
A estrutura de paginação se dá por um índice de configuração, definido como pagination, que deve estar junto às configurações da conexão.
O índice é composto por três parâmetros que definem o formato que a paginação é feita, são eles:
- pager: define uma chave de registro que esteja presente no resultado da integração como paginador. Desta forma, a integração vai utilizar esse índice para buscar os valores de páginas e passá-los para a próxima requisição. Por exemplo: se a busca de dados retorna uma chave chamada paginaAtual com o número da página, basta configurar o pager como paginaAtual que a integração vai usar este valor como paginador para a próxima requisição;
- endpoint: define como a integração reconhece quando as páginas acabaram, ou qual foi a última página. Para esta configuração é possível definir um índice presente no resultado da integração como validador para que a integração interpretar se as páginas acabaram ou usar palavras-chave que definem este validador automaticamente. Caso seja utilizado um índice como validador, a integração vai validar os valores: OK - OK - S - NULL como finalizado. Qualquer valor diferente destes será interpretado como não finalizado. Caso sejam utilizadas as palavras-chave elas podem ser:
- none: a integração não vai paginar, pois entende que há apenas uma página;
- empty: a integração só vai entender que as páginas acabaram quando uma das páginas requeridas retornar um resultado vazio, sem registros.
- type: define qual cálculo será utilizado para carregar os números das páginas. Existem três tipos de cálculos possíveis:
- NU: cálculo numérico simples com a fórmula: Pagina = Pagina+1;
- QR: cálculo de quantidade de registros com a fórmula: Pagina = count(registros);
- RG: cálculo de registro específico com a fórmula: Pagina = UltimoRegistro[pager]. Este cálculo utiliza o pager obrigatoriamente.
Caso nenhuma configuração de paginação seja definida nas configurações de conexão, o integrador utilizará a seguinte configuração por padrão:
