Histórico da Página

Quadro de Responsáveis

Requisitos

Especificação técnica

Cenário principal

Visto a grande demanda que existe todos os anos de integrações, exportações e consultas que são criadas de diversas formas para fontes externas, foi criado o AS Integrador que visa ser um meio de integração simples e eficaz para diminuir o esforço investido em horas desenvolvendo integrações com terceiros.

Nesta proposta de integrador o sistema de terceiro tem um WS que permite consultar e alterar as tabelas do AutoSystem (sob responsabilidade do cliente) com algumas restrições.

O integrador permite a criação de funções a serem executadas dentro da base da dados do AutoSystem, estas funções podem ser construidas e parametrizadas pelo cliente e serão salvas dentro do AutoSystem, fazendo com que o sistema de terceiro só tenha contato com a invocação do WS.

Criando uma função de integração:

• Através do menu "Gerencial > Configurações > Módulos > Gerenciador de integrações"
• Novo (botão)
  
  • Digitar o comando SQL desejado para a função de integração
  • Informar um nome para a integração (esse nome será a chamada de acesso para o sistema de terceiro)
  • Opção de incluir campos adicionais
• Editar (botão) (com uma integração selecionada)
  
  • Editar todos os itens da integração
• Excluir (botão) (com uma integração selecionada)
  • Elimina a linha da integração após confirmação
• Chave (botão)
  
  • Permite a geração da chave privada referente a integração

*Tela de gerenciamento de integrações

*Tela de criação da integração

*Se o nome da integração for alterado será necessário atualizar o terceiro quanto a mudança do nome para que continue tendo acesso a integração

Nessa tela também se encontra o botão "Campos adicionais" que funciona da seguinte forma:

Campos adicionais:

Quando o comando SQL tiver uma tag de parâmetros de projeção dinâmicos "%(projecao)s" os campos adicionais serão adicionados juntamente aos campos que forem enviados pelo sistema de terceiro ou logo após o "*".

Por exemplo:

Comando cadastrado: "select %(projecao)s from pessoa where cpf = '068.828.439-61'"

Campos adicionais:

• Campo: TIPO
• Valor: CLIENTE DE TESTE

O integrador irá executar o seguinte comando: "select 'CLIENTE DE TESTE' as TIPO, * from pessoa where cpf = '068.828.439-61'"

Se o sistema de terceiro enviar algum campo na projeção, o comando ficará o seguinte: "select 'CLIENTE DE TESTE' as TIPO, [CAMPOS ENVIADOS PELO TERCEIRO] from pessoa where cpf = '068.828.439-61'"

*Ou seja, os CAMPOS ADICIONAIS, sempre serão enviados como os primeiros campos da área de projeção do SQL

Configuração da chave privada

O integrador conta com uma chave privada de segurança da integração que permite que o cliente controle quem estará acessando a sua base de dados:

• Clicar em gerar nova chave
• Salvar

*Tela de configuração de chave privada de acesso da integração

O cliente deve acessar esta tela e gerar a chave, esta chave deve ser enviada para o responsável do sistema/aplicação de terceiro que realizará a integração!!

*Se uma nova chave for gerada, as antigas se tornarão inválidas e o sistema/aplicação de terceiro terá que receber esta nova chave para continuar tendo acesso aos dados do AutoSystem.

Executando o serviço do AS Integrador

• O executável main.exe deve ser executado com o seguinte parâmetro "main.exe --as_integrador"
  • A porta padrão do serviço é 5482 podendo ser alterada conforme a necessidade com o seguinte comando "main.exe --as_integrador 5471" por exemplo

Para efetuar testes no AS Integrador é possível utilizar o Postman que permite simular as requisições via JSON:

• O Postman pode ser instalado através deste link: https://www.getpostman.com/

Segue exemplos de testes e configurações com Postman:

Levantamento de escopo para criação de um integrador genérico que venha a atender as diversas integrações que são requisitadas para o AutoSystem de diversas áreas, tais como:

• Integrações de cadastros;
• Integrações Fiscais;
• Integrações Contábeis;
• Integrações de Fidelidade.

A integração deve funcionar através de um webservice utilizando JSON para troca de dados.

O webservice deve aceitar as seguintes ações:

• POST - Envio de comandos a serem executados

DEFINIÇÃO

Permitir a integração com sistemas de terceiros através de um WS via comandos SQL, permitindo a flexibilidade do cliente quanto a customizações em busca de dados, alterações e inserções.

• URL
       /as/integrador/{INTEGRACAO} - Deve ser informado na URL o nome da integração
• ENVIO

{cnpj} - CNPJ do Posto onde serão executados os comandos

{chave} - Chave privada do Integrador gerada e fornecida pelo cliente através do AutoSystem

SELECT

{projecao} - Campo que deve conter todos os campos que devem ser retornados da integração.

Exemplo: SELECT p.nome, p.cpf FROM pessoa p; - nome e cpf são campos de projeção da tabela pessoa.

{selecao} - Campo que deve conter todos os campos que devem fazer parte da condição WHERE do comando SQL da integração.

Exemplo: SELECT p.nome, p.cpf FROM pessoa p WHERE p.grid = 22154654546; - p.grid = 22154654546 é um parâmetro de seleção dos registros da tabela pessoa

{condicao} - Campo que deve conter todas as condições de restrição do comando SQL da integração.

Exemplo: SELECT p.nome, p.cpf FROM pessoa LIMIT 1; - LIMIT 1 é a condição de restrição para o retorno da tabela pessoa

Exemplo de comando a ser cadastrado:

SELECE %(projecao)s FROM pessoa p JOIN ponto pt ON (pt.pessoa = p.grid) %(selecao)s %(condicao)s

INSERT

{campos} - Campo que deve conter todos os campos da tabela que terão registros inseridos.

Exemplo: INSERT INTO pessoa (nome, cpf, data_nascimento, ......) values (.................) - nome, cpf, data_nascimento são campos que terão dados inseridos

{valores} - Campo que deve conter todos os valores dos respectivos campos que serão inseridos na tabela.

Exemplo: INSERT INTO pessoa (.........) values ('JOAO', '054.658.955-77', '1991-10-20', ......) - 'JOAO', '054.658.955-77', '1991-10-20' são valores que serão inseridos

Exemplo de comando a ser cadastrado:

INSERT INTO ponto %(campos)s VALUES %(valores)s

UPDATE

{expressao} - Campo que deve conter a expressão que define o que será alterado e em qual coluna.

Exemplo: UPDATE pessoa SET nome = 'LUIZ' WHERE grid = 22154654546; - nome = 'LUIZ' é a expressão que representa o que será alterado e em qual coluna da tabela pessoa

{selecao} - Campo que deve conter todos os campos que devem fazer parte da condição WHERE do comando SQL da integração.

Exemplo: UPDATE pessoa SET nome = 'LUIZ' WHERE grid = 22154654546; - grid = 22154654546 é o parâmetro de seleção para a atualização dos registros da tabela pessoa

Exemplo de comando a ser cadastrado:

UPDATE pessoa SET %(expressao)s %(selecao)s

DELETE

{selecao} - Campo que deve conter todos os campos que devem fazer parte da condição WHERE do comando SQL da integração.

Exemplo: DELETE FROM pessoa WHERE grid = 22154654546; - grid = 22154654546 é o parâmetro de seleção para a exclusão dos registros da tabela pessoa

Exemplo de comando a ser cadastrado:

DELETE FROM pessoa %(selecao)s

• RETORNO

{url} - URL que foi invocada

{versao} - Versão do AutoSystem

{retorno} - Onde virá o retorno do comando

{dados} - Onde virá a lista de dados retornados ou o OK da execução do comando

{banco} - Nome do banco onde foi executado o comando

{apiversion} - Versão da api do WS

{erro} - Texto indicando o erro ocorrido

{status_code} - Código do status do erro ou da execução bem sucedida

{status} - Status de execução de comandos "update", "insert"

EXEMPLOS

SELECT

• POST - /as/integrador/consulta_fidelidade

{

    "cnpj": "54517628001402",

    "projecao": "p.nome, p.cpf, pt.ponto",

    "selecao": "pt.ponto > 100",

    "condicao": "order by p.nome",

    "chave": "da5e6bced07ea4823992c0382e5f068f"

}

Exemplo de execução do comando:

SELECT p.cpf, p.nome, pt.ponto FROM pessoa p JOIN ponto pt ON (pt.pessoa = p.grid) WHERE pt.ponto > 100 order by p.nome

*A expressão "WHERE" será adicionada sempre que houver a chave %(selecao)s, portando não é necessário adicionar o "WHERE" no cadastro da integração

Após a execução o retorno do comando será em JSON conforme os exemplos abaixo.

• RETORNO OK

{

"url": "/as/integrador/consulta_fidelidade",

"versao": "3.2.2.0",

"retorno": {

"dados": [

{

"ponto": 112,

"cpf": "068.828.439-61",

"nome": "CLIENTE TESTE"

}

]

},

"status_code": 200,

"banco": "posto_tulio",

"apiversion": "1.0"

}

Se a chave de integração for inválida poderá ocorrer o seguinte exemplo de erro:

• RETORNO ERRO

{

"url": "/as/integrador/consulta_fidelidade",

"versao": "3.2.2.0",

"status_code": 400,

"erro": "Conexão não permitida pois a chave de segurança é inválida!",

"banco": "posto_tulio",

"apiversion": "1.0"

}

• INSERT

• POST - /as/integrador/registra_pontuacao

{

"cnpj": "54517628001402",

"campos": "pessoa, ponto",

"valores": "21325564546, 100"

"chave": "e50951856d1bbf486bf9f8845b0df03b"

}

Exemplo de execução: INSERT INTO ponto (pessoa, ponto) VALUES (21325564546, 100);

• UPDATE

• POST - /as/integrador/atualiza_endereco

{

"cnpj": "54517628001402",

"expressao": "logradouro = 'Rua Teste'",

"selecao": "pessoa = 21325564546"

"chave": "e50951856d1bbf486bf9f8845b0df03b"

}

Exemplo de execução: UPDATE pessoa SET logradouro = 'Rua Teste' WHERE pessoa = 21325564546;

*A expressão "WHERE" será adicionada sempre que houver a chave %(selecao)s, portando não é necessário adicionar o "WHERE" no cadastro da integração

• DELETE

• POST - /as/integrador/excluir_produto

{

"cnpj": "54517628001402",

"selecao": "grid = 513256547426"

"chave": "e50951856d1bbf486bf9f8845b0df03b"

}

Exemplo de execução: DELETE FROM produto WHERE grid = 513256547426;

*A expressão "WHERE" será adicionada sempre que houver a chave %(selecao)s, portando não é necessário adicionar o "WHERE" no cadastro da integração

*As relações das tabelas funcionam através do grid <> nomeDaTabela, por exemplo:

• • Tabela ponto possui o campo "pessoa" que é o grid (chave estrangeira) da tabela "pessoa"
  • A tabela pessoa possui o campo "grid" que pode ser utilizado em todas as relações de tabelas com o campo "pessoa"

O comando será executado se o mesmo passar nas validações de restrições e for um comando válido!

As restrições incluem os seguintes comandos:

• • drop table
  • alter table
  • update (sem condição where)
  • create
  • delete (sem condição where)
  • truncate
  • Acessar qualquer tabela _flow
  • Acessar qualquer tabela do integrador e configurações do mesmo

*Os comandos acima são bloqueados no integrador

Todos os comandos ficam registrados em tabelas de log do integrador com todas as informações da aplicação que enviou o comando para permitir o rastreio.

Após a execução o retorno do comando será em JSON conforme os exemplos abaixo.

• RETORNO OK

{

"url": "/as/integrador",

"versao": "3.2.2.0",

"retorno": {

"status": "OK"

},

"status_code": 200,

"banco": "posto_tulio",

"apiversion": "1.0"

}

Se o comando for com um erro de sintaxe ou de programação poderá ocorrer o seguinte exemplo de erro:

• RETORNO ERRO

{

"url": "/as/integrador",

"versao": "3.2.2.0",

"status_code": 500,

"erro": "ERROR:  more than one row returned by a subquery used as an expression\n\ninsert into ponto (pessoa, ponto) values ((select grid from pessoa), 10)",

"banco": "posto_tulio",

"apiversion": "1.0"

}