TKT-18975 - AS Integrador

Quadro de Responsáveis

Requisitos

Especificação técnica

Cenário principal

O Cliente Rede Marcela requisitou uma integração que permitisse buscar, inserir e alterar diversas informações do AutoSystem através de um sistema de terceiro via Webservice.

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 o 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. Dessa forma transferimos o esforço para o sistema de terceiro e podemos nos focar em demais projetos.

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:

Configuração

• Através do menu "Gerencial > Configurações > Módulos > AS Integrador"
• *Se for multi-empresa
  • Selecionar a empresa desejada
• 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.

• ENVIO

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

{comando} - Comando SQL que será executado no banco

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

• 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

{

"cnpj": "54517628001402",

"comando": "select p.cpf, p.nome, pt.ponto from pessoa p join ponto pt on (pt.pessoa = p.grid) limit 1",

"chave": "e50951856d1bbf486bf9f8845b0df03b"

}

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": {

"dados": [

{

"ponto": 36.42,

"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",

"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/UPDATE

• POST - /as/integrador

{

"cnpj": "54517628001402",

"comando": "insert into ponto (pessoa, ponto) values ((select grid from pessoa where cpf = '068.828.439-61'), 100)",

"chave": "e50951856d1bbf486bf9f8845b0df03b"

}

*Este comando de insert está exemplificando uma inserção de pontuação de um cliente buscando o mesmo através do CPF e registrando 100 pontos

*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
  • 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"

}