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 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.
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"
- *Se for multi-empresa
- Selecionar a empresa desejada
- Clicar em Novo
- 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)
- Clicar em Salvar
*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
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 da chave privada
- 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.
- 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
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
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
- 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.cpf, p.nome, pt.ponto",
"selecao": "",
"condicao": "limit 1",
"chave": "e50951856d1bbf486bf9f8845b0df03b"
}
Exemplo de execução do comando: select p.cpf, p.nome, pt.ponto from pessoa p join ponto pt on (pt.pessoa = p.grid) limit 1
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": 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/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_pontuacao
{
"cnpj": "54517628001402",
"expressao": "ponto = 50",
"selecao": "pessoa = 21325564546"
"chave": "e50951856d1bbf486bf9f8845b0df03b"
}
Exemplo de execução: UPDATE ponto SET ponto = 50 WHERE pessoa = 21325564546;
*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"
}