Integración con VTEX
  • 28 Sep 2023
  • Oscuro
    Ligero

Integración con VTEX

  • Oscuro
    Ligero

Article Summary

¿Qué es VTEX?

VTEX es una plataforma de comercio electrónico y solución de comercio en la nube que permite a las empresas crear y gestionar tiendas en línea altamente personalizadas y escalables. Esta plataforma ofrece una amplia gama de características y herramientas para la gestión de productos, procesamiento de pagos, logística, y experiencias de compra personalizadas. VTEX se utiliza en todo el mundo y es conocida por su enfoque en la omnicanalidad y la capacidad de adaptarse a las necesidades de empresas de todos los tamaños y sectores.


Guía de integración VTEX

Para realizar la integración de Zenkipay con la plataforma VTEX, es necesario seguir los siguientes pasos:

1 - Registrar una cuenta

Es necesario tener una cuenta de comercio en Zenkipay para llevar a cabo la integración. En el siguiente enlace podrás encontrar a detalle los pasos a seguir para abrir tu cuenta: Abrir una cuenta de comercio.

2 - Integración del sitio

Una vez que hayas registrado tu cuenta, selecciona la opción Integración con Plugins o API que se muestra en la página principal.

3 - Escanea la URL de tu sitio

Ingresa en la caja de texto la URL de tu sitio para poder ofrecerte la mejor opción con base a la tecnología que estas utilizando.

Paso 3

4 - Selecciona la plataforma de interés

Zenkipay te ofrecerá la mejor opción una vez que haya escaneado tu sitio, sin embargo, tú serás libre de seleccionar la opción que más se ajuste a tus necesidades.

Para comercios con VTEX te mostrará la siguiente opción:


5 - Sincroniza tu sitio

Una vez seleccionada la plataforma, visualizarás en una nueva pantalla donde se mostrará las llaves de integración, éstas serán empleadas más adelante en el portal de VTEX para la configuración del conector de pagos.

  • Identificación del cliente: Clave única de la aplicación
  • Clave secreta del cliente: Clave secreta confidencial para autenticar la aplicación
  • Nombre de la cuenta de VTEX: Identificador comercial en el sistema VTEX, debe coincidir con el Account name de tu tienda VTEX. 

También podrás decidir si quieres realizar una serie de pruebas una vez sincronizada tu tienda, las cuales se irán reflejando en el paso 3 del flujo de integración.

Estas llaves de integración deberás de ingresarlas en la pantalla de configuración de tu tienda VTEX.


Una vez ingresado el Nombre de la cuenta VTEX debes dar clic en el botón “Generar inicio de sesión en secreto” , a continuación se generará la firma secreta.

  • Firma secreta: Firma del webhook para validar el origen de las notificaciones en tu tienda VTEX.


6 - Instalación

6.1 - Creación de Application Key

  • Dentro de tu portal de administración de tu comercio VTEX, selecciona la opción Account Settings > Account Management> Application Keys y da clic en el botón Manage my keys.


  • Da clic en el botón + Generate New

  • Escribe el nombre que deseas darle a tu llave y da clic en el botón + Add Roles, Selecciona los roles con permisos de Administrador y da clic en el botón Generate

  • Busca y selecciona los roles para el acceso a las llaves, estos deben tener un nivel de Administrador para el correcto funcionamiento.
  • Da clic en el botón Add Roles

  • Da clic en el botón Generate 

  • Se creará el key y secret key.
Secret Key
Copia el guarda el secret key mostrada, ya que esta no podrá volverse a visualizar


6.2 - Configuración del conector de pago

  • Dentro de tu portal de administración de tu comercio VTEX, selecciona la opción Transacciones > Pagos > Configuraciones 


  • Selecciona la opción Gateway Affiliations y da clic en el icono +

  •  Selecciona el conector de pago Zenki que se encuentra en las últimas posiciones de la lista

  • Se mostrará la pantalla de configuración del conector de pago donde deberás ingresar los datos generados desde el portal de Zenkipay y el paso anterior:
    • Application key: Key generado desde la opción Application keys de tu tienda
    • Application token: Application token generado desde la opción Application keys de tu tienda
    • Client ID: Corresponde al identificador del cliente mostrado en el portal de Zenkipay.
    • Client Secret: Corresponde a la clave secreta del cliente mostrado en el portal de Zenkipay. 
    • Webhook signing secret: Corresponde a la firma secreta generada en el portal de Zenkipay con el account name de tu tienda.
Modo del conector
Válida que el modo del conector y las llaves ingresadas correspondan al modo de operación deseada Test si se requiere hacer pruebas, Live/Production para iniciar la operación y recepción de pagos en tu tienda.


  • Dar clic en el botón save
  • Selecciona la opción Payment Conditions y da clic en el botón +

  • Busca la opción Zenkipay - Pay with Crypto y selecciónala

  • Se mostrará la siguiente pantalla donde se deberá habilitar y dar clic al botón Save:
    • Status: Habilitar la opción Active


6.3 - Instalación del Payment App

Para instalar el payment app de Zenkipay en VTEX es necesario ejecutar el siguiente comando en el VTEX IO CLI:

  • vtex install zenkipartnermx.zenkipay@0.2.0

Una vez instalado se mostrará las aplicación en la sección de Installed Apps junto con el conector:

  • zenkipartnermx.zenki
  • zenkipartnermx.zenkipay

6.4 - Configuración de Google Tag Manager (GTM)

Para que su tienda VTEX funcione correctamente con Zenkipay, se requieren datos adicionales que se obtienen a través de Google Tag Manager (recomendamos que se cree una cuenta exclusiva para la integración de VTEX con Zenkipay para evitar posibles conflictos con otros contenedores).

Una vez dentro del Contenedor y seleccionado el Espacio de Trabajo (el que trae por default puede servir), habrá que configurar un Activador y una Etiqueta.

6.4.1 - Configurar Activador

  • Seleccionar tipo de evento: Evento personalizado
  • Nombre del evento: .*
  • Marcar checkbox para la opción Utilizar una expresión regular que coincida con
  • Seleccionar la opción Algunos eventos personalizados para la opción Este activador se activa en
  • Configurar condición: Event -> contiene -> payment

6.4.2 - Configurar Etiqueta

  • Tipo de etiqueta: HTML personalizado
  • Agregar siguiente script
  • Vincular Activador previamente configurado
<script>
  $( document ).ready(function() {
  setTimeout(function(){    
    console.log('GTM Zenkipay')    
    $("#payment-group-ZenkipayPaymentGroup > .payment-group-item-text").text("Zenkipay - Pay with Cripto");
    $(".ZenkipayPaymentGroup").empty()
    $(".ZenkipayPaymentGroup").append('<iframe style="width: 100%;height: 593px;border: none;margin: auto;" src="https://vtex-layout-checkout.zenki.fi/"></iframe>')    
  }, 1000)
  });
</script>

6.4.3 - Configurar Google Tag Manager en VTEX

Una vez finalizado el proceso de configuración en el Google Tag Manager, será necesario copia el ID del Contenedor de GTM dentro de la tienda de VTEX, para ello seguiremos los siguientes pasos:

  1. Ingresar a Storefront > Checkout
  2. Dar clic en el botón de configurar (ícono de engrane)
  3. En la siguiente pantalla seleccionar el tab Checkout 
  4. Capturar el ID del contenedor de GTM (que tiene un formato como este GTM-XXXXXX)
  5. Dar clic en Guardar


6.5 - Configuración del hook para aplicar descuento del Crypto Love

Para poder aplicar el descuento del Crypto Love (si se tiene habilitado) a las órdenes pagadas, es necesario configurar un hook en la tienda VTEX. Para poder aplicar este descuento y que los números cuadren en ambas plataformas, es necesario que el estatus de la orden en VTEX cambie a "handling" y que además que también VTEX notifique a Zenkipay cuando este cambio de estatus suceda (esta es la función del hook) para aplicar dicho descuento.

Para ello hay que consumir un servicio del API de VTEX, en este enlace pueden encontrar la documentación oficial.

POST https://{accountName}.{environment}.com.br/api/orders/hook/config

{
	"filter": {
		"type": "FromWorkflow",
		"status": ["handling"]
	},
	"hook": {
		"url": "https://vtex-connector.zenki.fi/order-updates/hook",
		"headers": {
			"x-zenki-client-id": "value",
			"x-zenki-client-secret": "value"
		}
	}
}

Donde los valores "value", deben ser reemplazados con las llaves de integración obtenidas en el portal de Zenkipay.

7 - Pruebas

Una vez integrada tu tienda podrás realizar compras de prueba, las cuales se irán reflejando en la siguiente pantalla.

También podrás omitir realizar las pruebas si así lo deseas y dar clic en “Siguiente” para finalizar el flujo de integración.

8 - Puesta en marcha

Al finalizar el flujo de integración se mostrará una pantalla como la del paso 5, pero con las llaves productivas, en esta se debe ingresar de nuevo el nombre de la cuenta VTEX para generar la Firma secreta productiva.

Modo Productivo
No olvides cambiar el modo de tu Gateway Affiliation de VTEX a Live/Production y actualizar los campos Client ID, Client Secret, Webhook signing secret con los valores productivos.





¿Te ha sido útil este artículo?