¶ 1. Visión General
Existe una gran demanda de integración de datos entre las diversas plataformas y sistemas disponibles en el mercado. T6 Enterprise posibilita esta integración mediante el uso de WebServices o API REST, transmitiendo los datos en formato JSON de tres formas:
- Obtener datos de una API/REST: consumiendo los datos de un servicio proporcionado por el cliente/proveedor;
- Enviar datos a una API/REST: encapsular los datos almacenados en T6 Enterprise y enviarlos a un servicio proporcionado por el cliente/proveedor;
- Disponibilizar los datos para consulta: ofrecer una estructura de datos a través de nuestra API de formularios para que algún servicio consuma los datos según la necesidad del origen.
Para ver la lista completa de APIs T6, podemos usar Swagger, para información sobre configuración y uso, visita nuestro centro de ayuda: Swagger
Internamente en T6 Enterprise, las cargas de datos (ETL) se crean mediante nuestro proceso de flujo de trabajo, lo que permite diversos controles, envío de correos electrónicos y la interacción con el usuario. A continuación, un ejemplo de flujo de carga:
¶ 2. DataloadREST
La herramienta que proporcionamos para interactuar con cualquier API/REST externa a T6 es DataloadREST. A través de él, podemos realizar llamadas en varios protocolos, métodos y autenticaciones, lo que permite consumir datos o enviar datos a WebServices disponibles en la red.
¶ 2.1. Llamada GET
Por defecto, el servicio utiliza el método POST, pero también es posible utilizar el método GET, pasando los parámetros concatenados en la URL como se muestra en el siguiente ejemplo. Como en el caso anterior, la inserción está dentro de un Procedimiento Almacenado, que concatena dinámicamente el año y el mes en la URL.
{
"Url": "https://apiqas.cliente.com.br:6244/teste-e/sysphera/integracao?ano='+@ano+'&mes='+@mes
"RequestMethod": "GET",
"AuthenticateType": "None",
"Body": ""
}
¶ 2.2. Autenticación Básica
Esta es la configuración más simple, utilizando el método POST. Incluye la URL del servicio, el método de autenticación básica, nombre de usuario, contraseña y los parámetros que se pasan en el cuerpo (método clásico de paso de 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. Llamada SIN Autenticación o Incluida en el Servicio (URL)
Cuando el servicio no requiera autenticación, colocar None en los 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. Llamada con Pase de Parámetros en el Encabezado "URL Codificada"
En este ejemplo, hay una necesidad de incluir cierta información en el encabezado, como el Content-Type y algunos parámetros utilizando la codificación de URL.
{
"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. Llamada pasando una Cookie.
Hay casos en los que es necesario pasar el TOKEN dentro de una Cookie, que se encuentra en el encabezado.
{
"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. Llamada POST enviando datos.
El envío de datos a una API utiliza la misma lógica de mensaje, la única diferencia es que en el cuerpo (Body) se encontrará el JSON con los datos a enviar.
{
"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. Llamada oAuth.
El servicio permite la utilización del protocolo oAuth. Este protocolo funciona como si fueran dos llamadas, una para la autenticación y otra para el servicio en sí, pero todo configurado en una única ejecución como se muestra en el ejemplo a continuación.
{
"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 Formularios de Datos
T6 Enterprise cuenta con una segunda forma de proporcionar datos para el consumo del cliente, a través de una API REST incorporada en cada formulario de datos del tipo VENTANA. Se trata de dos llamadas de API autenticadas mediante un token. La primera API devuelve los metadatos de la consulta, con la cantidad de filas y la descripción de las columnas, mientras que la segunda API devuelve el conjunto de datos con los datos del formulario. La llamada a la primera no es obligatoria y la segunda API (offset) permite la paginación cuando se tiene un volumen grande de datos.
¶ 3.1. Configuración del Token de Acceso
Para poder utilizar las API, algún usuario administrador multiaplicaciones debe crear un token de acceso. Esto debe hacerse en la creación del usuario, en la pestaña de Servicios como se muestra en la figura a continuación.
El token es un conjunto de caracteres que puede tener una validez y permitirá el acceso a las API de los formularios. Realizará la autenticación en lugar de un nombre de usuario y contraseña. Este token puede tener una fecha de caducidad y puede ser revocado o eliminado en cualquier momento.
¶ 3.2. El Formulario de Datos
Los administradores de la aplicación determinarán qué formulario (o formularios) se utilizará para acceder a los datos a través de la API. Se puede crear cualquier formulario del tipo ventana, ya sea creado a partir de una tabla de datos o mediante una consulta.
La información importante para utilizar en la API es el código del formulario, como se muestra a continuación:
¶ 3.3. Utilizando la API Execute
La API utilizada es "Services/Execute". Es de tipo POST y tiene un cuerpo en JSON con las configuraciones que utilizaremos.
A partir de su dirección en Tech6Cloud, concatenar al final "/api/Services/Execute". A continuación, se muestra un ejemplo de nuestro entorno de desarrollo (DEV):
https://dev-treinamento.tech6cloud.com/api/Services/Execute
El JSON tiene dos o tres parámetros:
- URL: API que será llamada;
- Token: el token creado que se utilizará para el acceso
- Data: Opcional. Cuando llamamos a una API de tipo POST y necesitamos pasar algo en el CUERPO.
¶ 3.4. API CreateOrGet
Esta es la primera API que llamaremos. En ella, obtendremos la lista con los nombres de las columnas a las que accederemos y la cantidad de filas existentes en el conjunto de datos.
Para esta llamada, no necesitaremos el parámetro de datos (Data), usaremos solo la URL y el Token.
La URL será Worksheet/CreateOrGet?type=dataform&typeCode=1996, siendo el typeCode (en este ejemplo el 1996) el código del formulario de datos que se consumirá.
{
"Url":"Worksheet/CreateOrGet?type=dataform&typeCode=1996",
"Token":"1fae0b70e3d24d88b67208301b1c1eb1"
}
A continuación se muestra la llamada a la API y la respuesta, indicando que el formulario tiene 51 filas y los encabezados de las columnas.
Por defecto, el Content-Type vendrá con el tipo Text/Plain. Como en el Body tenemos un JSON, necesitamos cambiar el Content-Type a Application/JSON. De lo contrario, se generará el siguiente error: 415 - Unsupported Media Type.
¶ 3.5. API Offset
La API Offset se utiliza eficazmente para consumir los datos. Dependiendo del volumen de datos, puede ser paginada, ya que además del código del formulario de datos (typeCode), también tenemos como atributo la fila inicial y la cantidad de filas que vamos a buscar.
La URL será Worksheet/Offset?code=&type=dataform&typecode=1996&start=0&length=20&metadata=false. En este ejemplo, estoy comenzando desde la primera fila "0" y solo voy a traer 20 filas del total de 51.
En esta llamada, el parámetro Data del cuerpo es necesario y será fijo, siempre pasando de la siguiente manera: "Data":
{
"Url":"Worksheet/Offset?code=&type=dataform&typecode=1996&start=0&length=20&metadata=false
"Token":"1fae0b70e3d24d88b67208301b1c1eb1",
"Data":{"Comparator":0,"Operator":0,"Filters":[]}
}
A continuación se muestra la llamada a la API que devuelve los datos. La respuesta siempre seguirá el mismo formato de una lista enlazada con FILAS y COLUMNAS.
Observe que comenzamos con la fila RowIndex=0 y luego todas sus columnas ColumnIndex=0, 1, 2... El valor es el que se encuentra en el campo VALUE. Es decir, la celda {0,5} tiene el valor "10".
En este ejemplo anterior, al verificar en el formulario lo que tenemos en FILA=0 y COLUMNA=5, tenemos el valor 10.
¶ 3.6. Valores de los Parámetros en las APIs
Para localizar los valores de los parámetros de una API, utilizaremos una herramienta para capturar el tráfico de red durante la ejecución de T6Enterprise. Esto nos permitirá visualizar los valores que se están utilizando durante la ejecución de las acciones en el sistema. En este ejemplo, utilizaremos la API Offset y demostraremos cómo localizar los parámetros necesarios para aplicar filtros a través del campo Data en el request body de la propia API.
Para aplicar filtros en la API Offset, necesitaremos utilizar una herramienta que capture el tráfico de red (en nuestro ejemplo, usaremos Fiddler Classic).
- Ejecute Fiddler;
- Acceda a T6Enterprise en su navegador mientras Fiddler está en ejecución;
- Seleccione un objeto del tipo Formulario de Datos que será utilizado en la llamada a la API;
- Necesitaremos usar el código del objeto en el request body de la API.
- Acceda al formulario y, en la cinta, haga clic en Filtros;
- Se mostrará un nuevo panel lateral, donde filtraremos los valores que deseamos;
- Después de modificar los filtros según lo deseado, volveremos a Fiddler, donde localizaremos la API utilizada al aplicar los filtros, ya que necesitaremos la información generada para completar nuestro request body.
- Al acceder a Fiddler después de modificar los filtros en el formulario de datos, localizaremos la API disparada en la lista a la izquierda y seguiremos los pasos como se muestra en la imagen a continuación:
- 1º: Seleccione la API que comienza con
/api/Worksheet/Offset...haciendo doble clic; - 2º: Seleccione la pestaña Inspectors;
- 3º: En la pestaña Inspectors, seleccione la pestaña Raw;
- 4º: En la última línea, encontrará la información necesaria para completar su request body. Copie toda la línea y luego insértela en el campo Data del request body de su API.
{
"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"}]}
}
De esta forma, al ejecutar la API, obtendremos únicamente los datos según los filtros aplicados.