La API en Postman

Introducción y estructura de datos

En la documentación de la API de Sales Layer hablamos de las llamadas de tipo GET para obtener información, y las llamadas de tipo POST para importar información.

En los ejemplos anteriores en los que desarrollamos el uso de nuestra API hablamos de cómo utilizarla usando nuestro SDK pero en este nuevo ejemplo, explicaremos cómo probar nuestra API en Postman, programa que permite testear llamadas a la API con llamadas de tipo GET y de tipo POST.

Para probar las llamadas de tipo GET tendremos que crear un conector de exportación y, para las llamadas de tipo POST, un conector de importación. Podremos editarlos desde la Tienda de canales:

En el conector de exportación configuramos los parámetros según nuestras necesidades teniendo en cuenta los idiomas a exportar y el estado de los ítems, y en la pestaña de Datos de Salida, configuraremos las tablas a exportar y todos sus campos.

Con el conector de importación empezamos, del mismo modo, seleccionando en parámetros los idiomas a importar y, en Datos de Salida, los campos que queremos importar para cada tabla en Sales Layer. En este punto es muy importante que, en la columna de nombres al importar, los valores sean exactamente iguales a la estructura input_data que vamos a importar.

Otra punto importante a destacar en los conectores de importación es la opción que nos ofrece de decidir si queremos o no importar solo los ítems existentes:

Si queremos importar nuevos ítems, habrá que seleccionar No en la primera opción.

En Postman

Para comenzar debemos tener la aplicación instalada o acceso a su versión cloud. En este punto debemos haber leído toda la documentación de nuestra API para tener claros los parámetros, tanto obligatorios como opcionales, y su funcionamiento.

Una vez creados los conectores de importación y exportación podremos comenzar la prueba con Postman.

Atento: los siguientes pasos son los mismos tanto para la llamada GET como para la llamada POST.

Inicialmente, empezaremos por definir la URL de la llamada, https://api.saleslayer.com

Como sabemos, la API de Sales Layer tiene cuatro parámetros obligatorios, tanto para importación como exportación:

code: identificador del conector
time: fecha actual en UNIX
unique: número aleatorio de seguridad
key: combinación de los 3 parámetros anteriores más la clave privada
key256: combinación de los 3 parámetros anteriores más la clave privada

Será el momento de definirlos en los parámetros de Postman, en la columna Key.

Atento: si usamos una codificación de tipo SHA256, tenemos que llamar el parámetro key como key256.

Como tenemos que configurar un pequeño script para el apartado Value, tendremos que definir los tres últimos parámetros, creando cada valor como una variable:

Terminando con lo siguiente:

Después, entramos en el apartado Pre-request Script y añadimos lo siguiente:

pm.globals.set("code", "ID_connector");

var secret_key = "secret_key";

var unique = Math.round(Math.random()*100000);

pm.globals.set("unique", unique);

var timeInSeconds = parseInt((new Date()).getTime() / 1000);

pm.globals.set("time", timeInSeconds);

var sigString = pm.globals.get("code") + secret_key + timeInSeconds + unique;

var CryptoJS = require('crypto-js');

var key = CryptoJS.SHA256(sigString);

pm.globals.set("key256", key.toString());

Atento: estamos mostrando una de las maneras de cumplimentarlo, pero existen más vías que también serían óptimas.

Para mayor comprensión, vamos a observar línea por línea e interpretar su significado:

pm.globals.set("code", "ID_connector"); - en esta línea definimos en la variable global {{code}} el identificador del conector en Sales Layer. Por tanto, donde tenemos ID_connector deberíamos añadir el código del conector;

var secret_key = "secret_key"; - en esta línea hemos creado una variable llamada secret_key, por tanto donde vemos secret_key deberíamos de poner la clave privada del conector. Atento a este parámetro porque lo usaremos más tarde para crear el parámetro {{key256}};

var unique = Math.round(Math.random()*100000); - en esta línea creamos una variable llamada unique donde generamos un valor aleatorio;

pm.globals.set("unique", unique); - en este punto guardamos el valor creado en la línea anterior en la variable global {{unique}};

var timeInSeconds = parseInt((new Date()).getTime() / 1000); - en este otro generamos un timestamp de la fecha actual;

pm.globals.set("time", timeInSeconds); - con el que guardamos el valor creado en la línea anterior en la variable global {{time}};

var sigString = pm.globals.get("code") + secret_key + timeInSeconds + unique; - en esta línea guardamos la combinación de los parámetros creados y generados con anterioridad.

const CryptoJS = require('crypto-js'); - importación de biblioteca para la codificación en SHA256 del parámetro generado en la línea anterior.

var key = CryptoJS.SHA256(sigString); - punto en el que se calcula el hash SHA256 de la cadena sigString creada en la línea anterior y que se almacena en la variable key.

pm.globals.set("key256", key.toString()); se convierte a String la variable de la línea anterior y se almacena en la variable gllobal {{key256}}.

Para llamadas de tipo POSThay que cambiar el tipo de llamada y enviar información en el apartado Body, seleccionando la opción Raw y JSON, y añadiendo la estructura input_data con los campos que queremos importar en Sales Layer.

En este conector de importación estamos subiendo los siguientes campos. Habrá que prestar especial atención porque el Alias de la tabla tiene que ser igual al nombre de la tabla que se envía en input_data:

Una vez hecho los pasos anteriores, le damos a Send.

Interpretación de resultados

Llamada GET

Una vez hecha la llamada obtenemos la siguiente respuesta:

Atento: la imagen no está completa. La API devuelve un JSON con todas las estructuras conocidas como data_schema con los nombres de los campos exportados por cada tabla y data con la información modificada. En el caso de que se trabaje con el parámetro last_update - es conveniente echarle un ojo al apartado extra: “trabajar con parámetros opcionales del presente artículo”. Cuando haya información para eliminar, la API exportará estos ítems como eliminados “D”.

Llamada Post

Una vez hecha la llamada obtenemos el siguiente resultado:

Atento: el resultado de la API en la importación puede variar dependiendo de la versión de la API que estamos usando. En este caso, usamos la versión por defecto de la API 1.17.

Extra: trabajar con Parámetros opcionales

Nuestra API tiene varios parámetros opcionales para la exportación. Para trabajar con ellos bastaría enviarlos por separado en la llamada. Usaremos, por ejemplo, el parámetro last_update.

Normalmente cogemos el response_timede la llamada anterior:

Y lo ponemos como last_updatedel parámetro de la llamada siguiente:

Y así tenemos los modificados entre la sincronización actual y la anterior.

Probaremos ahora el parámetro group_category_id con Postman. Este parámetro recibe los valores 0 y 1; enviemos el valor dependiendo de cómo se desee exportar los datos multicategoría:

Ejecutando la llamada y enviando el parámetro en 1, la API nos devolverá los productos multicategorías agrupados en uno solo.