¶ 1. Visão geral.
Existe uma grande demanda de integração de dados entre as diversas plataformas e sistemas disponíveis no mercado. O T6 Enterprise possibilita esta integração através da utilização de
WebServices ou API REST, trafegando os dados no formato JSON de três formas:
-
Buscar dados de uma API/REST: consumindo os dados de um serviço disponibilizado pelo cliente/fornecedor;
-
Enviar dados para uma API/REST: encapsular os dados que estão armazenados no T6 Enterprise e envia-los a um serviço disponibilizado pelo cliente/fornecedor;
-
Disponibilizar os dados para consulta: ofertar uma estrutura de dados através de nossa API dos formulários para que algum serviço consuma os dados conforme a necessidade da origem.
Para visualizarmos a listagem completa das APIs do T6, podemos utilizar o Swagger, para informações quanto à configuração e utilização, acesse nossa central de ajuda: Swagger
Internamente no T6 Enterprise as carga de dados (ETL) são criados através de nosso processo de workflow, permitindo diversos controles, envios de e-mails e a interação com o usuário. Abaixo um exemplo de fluxo de carga:
¶ 2. DataloadREST.
A ferramenta que disponibilizamos para interagir com qualquer API/REST externas ao T6 é o DataloadREST. Através dele podemos disparar chamadas em diversos protocolos, métodos e autenticações, permitindo consumir dados ou enviar dados a WebServices disponíveis na rede.
¶ 2.1. Chamada GET.
Por padrão o serviço utiliza o método POST, porém também é possível utilizar o método GET, passando os parâmetros concatenados na URL conforme o exemplo abaixo. Como no caso anterior, o insert está dentro de uma Stored Procedure, que concatena dinamicamente o ano e o mês na URL.
{
"Url": "https://apiqas.cliente.com.br:6244/teste-e/sysphera/integracao?ano='+@ano+'&mes='+@mes
"RequestMethod": "GET",
"AuthenticateType": "None",
"Body": ""
}
¶ 2.2. Autenticação Básica.
Configuração mais simples, com método POST, a URL do serviço, o método de autenticação básico, usuário, senha e os parâmetros sendo passados no body (passagem clássica do método POST):
{
"Url": "http://sapqas.cliente.com:8001/sysphera/sysphera_dados?sap-client=300",
"RequestMethod" : "POST" ,
"AuthenticateType": "BASIC",
"UserName": "SYSPHERA",
"Password": "agrC4DkbyJuHSFwCU@",
"Body": "{
\"I_ANO\": \"2019\",
\"I_MES\": \"02\"
}"
}
¶ 2.3. Chamada SEM Autenticação ou Incluída no Serviço (URL).
Quando o serviço não exigir autenticação, colocar None nos parâmetros.
{
"Url": "https://api.cliente.com.br:6244/sysphera/listar/volume",
"AuthenticateType": "None",
"UserName": "None",
"Password": "None",
"Body": "{
\"ANO\": \"2019\",
\"MES\": \"01\"
}"
}')
¶ 2.4. Chamada com passagem de parâmetros no HEADER "URL Encoded".
Neste exemplo existe a necessidade de incluir algumas informações no Header, como o Content-Type e alguns parâmetros utilizando via URL Encoded.
{
"Url" : "https://api-homologacao.cliente.com.br/credenciamento/auth/oauth/v2/token" ,
"AuthenticateType" : "BASIC" ,
"UserName" : "0fd71627-a1a1-b1b1-9cd4-69c6ef34fb74" ,
"Password" : "e34af389-6054-9958-a8c4-c304244c9b81" ,
"RequestMethod" : "POST" ,
"Header": "Content-Type:application/x-www-form-urlencoded",
"Body": "scope=onboarding-sap&grant_type=client_credentials"
}'
¶ 2.5. Chamada passando uma Cookie.
Existem casos onde é necessário passar o TOKEN dentro de uma Cookie, que fica no Header.
{
"Url": "https://servicos.cliente.com.br/isw/api/v1/siteware/acompanhamentoFinanceiroProjeto",
"RequestMethod": "POST",
"Header": "Cookie: iPlanetDirectoryPro=\"My00YTk0LTljZDQtNjljNmVmMzRmYjc0OmUzN\"; Content-Typ
"Body": "[{\"ano\": 2020, \"codigo\": 900001, \"despesaOrcado\": 1.50, \"despesaRealizado\":
}
¶ 2.6. Chamada POST enviando dados.
O envio do dados para uma API utiliza a mesma lógica de mensagem, a única diferença é que no Body estará o JSON com os dados a serem enviados.
{
"Url": "http://sapqas.cliente.com:8001/sysphera/sysphera_getdata",
"RequestMethod" : "POST" ,
"AuthenticateType": "BASIC",
"UserName": "SYSPHERA",
"Password": "agrC4DkbyJuHSFwCU@",
"Body": "[
{\"ano\": 2023, \"codigo\": 900001, \"despesaOrcado\": 1.50, \"despesaRealizado\": 1.60, \"mes
{\"ano\": 2023, \"codigo\": 900002, \"despesaOrcado\": 2.40, \"despesaRealizado\": 2.30, \"mes
{\"ano\": 2023, \"codigo\": 900003, \"despesaOrcado\": 3.20, \"despesaRealizado\": 3.50, \"mes
{\"ano\": 2023, \"codigo\": 900004, \"despesaOrcado\": 1.80, \"despesaRealizado\": 1.60, \"mes
...
]"
}
¶ 2.7. Chamada oAuth.
O serviço permite a utilização do protocolo oAuth. Este protocolo funciona como se fossem duas chamadas, uma para a autenticação e outra para o serviço em si, mas tudo configurado numa única execução conforme exemplo abaixo.
{
"Url": "https://dev-api.cliente.com.br/sb/dados-contabeis/v1/contas?Periodo=01/01/2020",
"AuthenticateType": "oAuth",
"Header": "client_id:5ca627ad-a1a1-3680-87ac-0ededaffc59d; access_token:{{oAuthAccessToken}};
"RequestMethod": "POST",
"UserName": "",
"Password": "",
"Body":"",
"oAuthAuthEndpoint": "https://api.cliente.com.br/oauth/grant-code",
"oAuthAuthRequestMethod": "POST",
"oAuthAuthRequestHeader": "Content-Type:application/json",
"oAuthAuthRequestBody": "{\"client_id\": \"5ca627ad-608a-3680-87ac-0ededaffc59d\", \"redirect_
"oAuthAuthRequestAuthenticateType": "",
"oAuthAuthRequestUserName": "",
"oAuthAuthRequestPassword": "",
"oAuthTokenEndpoint": "https://api.cliente.com.br/oauth/access-token",
"oAuthTokenRequestMethod": "POST",
"oAuthTokenRequestHeader": "Content-Type:application/x-www-form-urlencoded",
"oAuthTokenRequestBody": "grant_type=authorization_code&code={{oAuthGrantCode}}",
"oAuthTokenRequestAuthenticateType": "Basic",
"oAuthTokenRequestUserName": "5ca627ad-608a-3680-87ac-0ededaffc59d",
"oAuthTokenRequestPassword": "87d147d1-a607-3d0f-9de2-78d9a11c0fe8"
}')
¶ 3. API REST de Formulários de Dados.
O T6 Enterprise possui uma segunda forma de disponibilizar os dados para consumo do cliente, através de uma API REST incorporada em cada formulário de dados do tipo JANELA. São duas chamadas de APIs autenticadas através de um token. A primeira API retorna os metadados da consulta, com a quantidade de linhas e o descritivo das colunas, enquanto a segunda API retorna o dataset com os dados do formulário. A chamada da primeira não é obrigatória e a segunda API (offset) permite a paginação quando temos um volume grande de dados.
¶ 3.1. Configuração do Token de Acesso.
Para que possamos utilizar as APIs, algum usuário administrador multi-aplicações precisa criar um token de acesso. Isso deve ser feito na criação do usuário, na aba de Services conforme apresentado na figura abaixo.
O token é um conjunto de caracteres que pode ter uma validade e permitirá o acesso às APIs dos formulários. Ele fará a autenticação ao invés de um usuário e senha. Este token pode ter um prazo de validade e poderá ser revogado/excluido a qualquer momento.
¶ 3.2. O Formulário de Dados.
Os gestores da aplicação irão definir qual (ou quais) formulário será utilizado para acessar os dados via API. Qualquer formulário do tipo janela poderá ser criado, independente se foi criado através de uma tabela de dados ou através de consulta.
A informação importante para usar na API é o código do formulário conforme apresentado a seguir:
¶ 3.3 Usando a API Execute.
A API utilizada é a "Services/Execute". Ela é do tipo POST e possui um body em JSON com as configurações que usaremos.
A partir do seu endereço no Tech6Cloud, concatene no final "/api/Services/Execute". Abaixo o exemplo de nosso ambiente DEV de treinamento:
https://dev-treinamento.tech6cloud.com/api/Services/Execute
O JSON possui dois ou três parâmetros:
- URL: API que será chamada;
- Token: o token criado e que será utilizado para acesso
- Data: Opcional. Quando chamaremos uma API de POST e precisamos passar algo no BODY.
¶ 3.4. API CreateOrGet.
Esta é a primeira API que chamaremos. Nela, teremos a listagem com os nomes das colunas que iremos acessar e a quantidade de linhas existente no Dataset.
Para esta chamada, não precisaremos do parâmetro data, usaremos apenas a URL e o Token.
A URL será Worksheet/CreateOrGet?type=dataform&typeCode=1996, sendo o typeCode (neste exemplo o 1996) o código do formulário de dados a ser consumido.
{
"Url":"Worksheet/CreateOrGet?type=dataform&typeCode=1996",
"Token":"1fae0b70e3d24d88b67208301b1c1eb1"
}
Abaixo a chamada da API e o retorno, apresentando que o formulário possui 51 linhas e o cabeçalho das colunas.
Por padrão o Content-Type virá com o tipo Text/Plain, como no Body temos um JSON, precisamos alterar o Content-Type para Application/JSON, caso contrário, será gerado o seguinte erro: 415 - Unsupported Media Type.
¶ 3.5. API Offset.
A API Offset é utilizada efetivamente para consumir os dados. Dependendo do volume de dados, ela pode ser paginada, pois além do código do formulário de dados (typeCode), também temos como atributo a linha inicial e a quantidade de linhas que iremos buscar.
A URL será Worksheet/Offset?code=&type=dataform&typecode=1996&start=0&length=20&metadata=false. Neste exemplo estou iniciando da primeira linha "0" e vou trazer apenas 20 linhas do total de 51.
Nesta chamada o parâmetro Data do Body é necessário e será fixo, sempre passando da seguinte forma:
"Data":
{
"Url":"Worksheet/Offset?code=&type=dataform&typecode=1996&start=0&length=20&metadata=false
"Token":"1fae0b70e3d24d88b67208301b1c1eb1",
"Data":{"Comparator":0,"Operator":0,"Filters":[]}
}
Abaixo a chamada da API retornando os dados. O retorno será sempre no mesmo formado de lista encadeada com LINHA e COLUNAS.
Veja que iniciamos com a linha RowIndex=0 e depois todas as suas colunas ColumnIndex=0, 1, 2... O valor é o que está no campo VALUE. Ou seja, a célula {0,5} tem o valor "10"
Neste exemplo acima, verificando no formulário o que temos na ROW=0 e COLUM=5, temos o valor 10.
¶ 3.5.1. CURL - Offset
Podemos também efetuar a chamada da API via CURL, utilizando o CMD. Para isso, vamos executar o CMD como administrador e em seguida executar a seguinte chamada CURL:
echo. && curl --location "http://seu-domínio/api/Services/Execute" --header "Content-Type: application/json" --data "{\"Url\":\"Worksheet/Offset?code=^&type=dataform^&typecode=6935^&start=0^&length=255^&metadata=false\",\"Token\":\"3ef450hp121247c68fc9faaabbb123\",\"Data\":{\"Comparator\":0,\"Operator\":0,\"Filters\":[]}}"
Ao executar este CURL, teremos a exibição dos dados do objeto informado conforme exemplo abaixo:
¶ 3.6. Valores dos Parâmetros nas APIs
Para localizarmos os valores dos parâmetros de uma API, vamos utilizar uma ferramenta para captura de tráfego de rede durante a execução do T6Enterprise, para conseguirmos visualizar os valores que estão sendo utilizados durante a execução das ações no sistema. Neste exemplo iremos utilizar a API Offset e demonstrar como localizar os parâmetros necessários para aplicarmos filtros através do campo Data no request body da própria API.
Para aplicarmos filtros na API Offset, precisaremos utilizar uma ferramenta que faça a captura do tráfego de rede (em nosso exemplo, utilizaremos o Fiddler Classic).
- Execute o Fiddler;
- Acesse o T6Enterprise no seu navegador, enquanto o Fiddler está em execução;
- Selecione um objeto do tipo Formulário de Dados que será utilizado na chamada da API;
- Precisaremos utilizar o código do objeto no request body da API;
- Acesse o formulário e na ribbon, clique em Filtros;
- Será exibido um novo panel na lateral, onde iremos filtrar os valores que desejamos;
- Após alterar os filtros conforme desejado, retornaremos ao Fiddler, onde iremos localizar a API utilizada ao realizarmos a aplicação dos filtros, pois precisaremos da informação nela gerada para podermos completar nosso request body;
- Ao acessarmos o Fiddler após ter alterado os filtros no formulário de dados, vamos localizar a API disparada na listagem à esquerda, e seguir os passos conforme exibido na imagem abaixo;
- 1º: Vamos selecionar a API com início
/api/Worksheet/Offset...com um duplo clique; - 2º: Vamos selecionar a aba Inspectors;
- 3º: Na aba Inspectors, vamos selecionar a aba Raw;
- 4º: Na última linha, teremos a informação que precisamos para completar nosso request body, copie toda a linha e em seguida, insira a informação copiada no request body da sua API no campo Data;
{
"Url":"Worksheet/Offset?code=&type=dataform&typecode=3232&start=0&length=20&metadata=false
"Token":"1fae0b70e3d24d88b67268302b1d1eb1",
"Data":{"Comparator":0,"Operator":0,"Filters":[{"Comparator":0,"Operator":0,"Filters":[],"Code":"413|codUser","Value":"admin"},{"Comparator":0,"Operator":0,"Filters":[{"Comparator":0,"Operator":0,"Filters":[],"Type":"column","Code":"1026","Value":"Brindes"}],"Type":"column","Code":"1026"}]}
}
Desta forma, ao executar a API, teremos o retorno somente dos dados conforme os filtros aplicados.
¶ 4. Integração Para Usuários
Para que um usuário possa acessar o sistema sem utilizar as credenciais, vamos precisar de um Token de acesso para ele, com o qual iremos gerar uma URL para o acesso. Para isso iremos utilizar a API Integration.
¶ 4.1 Token
Para termos acesso ao Token de um usuário, precisaremos fazer uma consulta em nosso banco de dados, iremos utilizar o seguinte comando SQL:
select dbo.UrlEncode(dbo.VarBinaryToBase64(dbo.Encrypt('bmeredyk?~/l/cms/home'))) as token
Ao utilizar este comando, o banco nos retornará o Token que iremos utilizar para gerar a URL que concederá o acesso ao usuário. No exemplo acima, temos o caminho 'bmeredyk?/l/cms/home', no qual bmeredyk é o usuário que iremos gerar o token de acesso e /l/cms/home é o endpoint da página que será aberta assim que o usuário clicar na URL, neste caso, a página Home da nossa aplicação. Podemos alterar o endpoint fazendo com que o usuário acesse o sistema em uma página específica.
¶ 4.2 Gerando a URL via Powershell
Para gerarmos a URL de acesso, iremos utilizar um script do Powershell, para isso, precisaremos instalar o módulo Invoke-SQLcmd do SQLServer (Invoke-SQLcmd) em nosso Powershell. Utilizaremos o seguinte script:
$tokenDS = Invoke-Sqlcmd -Query "select dbo.UrlEncode(dbo.VarBinaryToBase64(dbo.Encrypt('bmeredyk?~/l/explorer/2437'))) as token;" -As DataSet -ConnectionString "Server=TESTE;Database=EXEMPLO;TrustServerCertificate=true;user id=****;password=****"
$token = $tokenDS.Tables[0].token
$Url = $('http://TESTE:9900/api/Authentication/Integration?token=' + $token + '')
Write-Host "URL gerada: $Url"
Invoke-WebRequest -URI $Url -UseBasicParsing -Headers @{'content-type' = 'application/json'} -Method 'GET'
Para utilizar este script, o usuário deve ter acesso ao banco de dados, e utilizar suas credenciais de login na connectionstring.
Ao executar este script, uma URL de acesso será gerada conforme exemplo abaixo:
