Cargo | Nome |
---|---|
Gerente de Projeto | |
Analista de Negócio | |
Analista de Sistemas | |
Arquiteto e Revisor | - |
Desenvolvedor | |
Documentador | - |
Analista de Testes |
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"
}