VTOL-VTEX Integrator - Manual de usuario 






REVISIONES


Fecha

Revisión

Cambios – Motivo

13/11/2020

1.0

Creación del documento



CONTENIDO


1. Acerca del manual

1.1 Propósito y alcance

El presente manual tiene por finalidad la capacitación de los usuarios que deseen utilizar el módulo de Vtex Integration Service del producto VTOL.

Brinda la información necesaria, con el nivel de detalle suficiente para que el usuario pueda configurar el módulo para operar con el E-commerce VTEX.


1.2 Referencias

Se mencionan los documentos que acompañan a este manual:


2. VTOL-VTEX Integrator

2.1 Introducción

VTOL-Vtex Integrator es un sistema que permite la conexión entre VTOL Server y el E-Commerce VTEX para realizar transacciones con tarjetas de crédito y débito.

A continuación se explica el funcionamiento de VTOL-Vtex Integrator:

  • VTOL-Vtex Integrator recibe una transacción desde el E-Commerce, se valida y se rutea hacia Vtol Server.
  • VTOL Server procesa la transacción y envía la respuesta a VTOL-Vtex Integrator.
  • VTOL-Vtex Integrator registra la respuesta de VTOL Server en su base de datos y construye una respuesta para el E-commerce Vtex.


2.2 Arquitectura de componentes

A continuación se muestra un gráfico de la arquitectura de VTOL-VTEX Integrator.


3. Servicios de configuración

Para el correcto funcionamiento de este módulo es necesario previamente realizar las configuraciones que se describen a continuación:


3.1 Instancias de VTOL Server

En el módulo de VTOL-Vtex Integrator se deben configurar las instancias de VTOL Server, por medio de las cuales se procesarán las transacciones.

Para configurar dichas instancias, se podrá realizar por medio de la base de datos (mongoDB), o por medio de webservices (API Rest)


Configuración por Base de datos:

Para modificar los parámetros de conexión a través de la base de datos, se puede utilizar una herramienta de administración de base de datos MongoDB, como ser Robo3T.

Para configurar los datos, es necesario editar la collection “VtolConfig” de la base de VTOL-VtexIS.

Los parámetros más importantes de conexión son:

  • code: Instancia de VTOL Server que procesará las transacciones.
  • hostIP: Ip de VTOL Server.
  • hostPort: Puerto de VTOL Server.
  • vtolMessageStrategy: Indica la estrategia que se utilizará para rutear las transacciones a las diferentes instancias de VTOL Server. Valores posibles:
    • global.napse.vtol.integration.restGateway.model.strategy.VTOLCDARMessageStrategy
    • global.napse.vtol.integration.restGateway.model.strategy.VTOLCDMXMessageStrategy
  • region: Indica la conexión regional de la Instancia de Vtol Server. Valores posibles:
    • AR
    • MX


Ejemplo:



Configuración por API Rest

El servicio /vtolConfig permite configurar los datos de las instancias de VTOL Server que estarán habilitadas en VTOL-Vtex Integrator.

Documentación en Swagger

El detalle completo del servicio de Configuración de instancias de VTOL Server se encuentra documentado en Swagger:

https://{IP}:{Port}/vtolRest/swagger-ui.html#/VtolConfig


Alta de Instancia de VTOL Server

Permite dar de alta una Instancia de VTOL Server dentro del módulo VTOL-VTEX Integrator.

MétodoPOST
Urlhttps://{{baseUrl}}/vtolRest/vtolConfig


Invocar al servicio

Para dar de alta una Instancia de VTOL Server, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/VtolConfig

  2. Dirigirse a la sección:



  3. Presionar el botón:


  4. Completar los datos del JSON vtolConfigRequest:


  5. Presionar el botón Execute:


  6. Si los datos informados en el JSON son correctos, se creará la Instancia de VTOL Server, retornando el código HTTP201 y un eco de los parámetros enviados:


Modificar Instancia de VTOL Server

Permite modificar una Instancia de VTOL Server dentro del módulo VTOL-VTEX Integrator.

MétodoPUT
Urlhttps://{{baseUrl}}/vtolRest/vtolConfig


Invocar al servicio

Para modificar una Instancia de VTOL Server, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/VtolConfig

  2. Dirigirse a la sección:

  3. Repetir los mismos pasos del alta.


Consultar Instancias de VTOL Server

Permite realizar una consulta de las Instancias de VTOL Server que están configuradas dentro del módulo VTOL-VTEX Integrator.

MétodoGET
Urlhttps://{{baseUrl}}/vtolRest/vtolConfigs


Invocar al servicio

Para consultar las Instancias de VTOL Server, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/VtolConfig

  2. Dirigirse a la sección:

  3. Repetir los mismos pasos del alta.


Eliminar Instancia de VTOL Server

Permite eliminar una Instancia de VTOL Server dentro del módulo VTOL-VTEX Integrator.

MétodoDELETE
Urlhttps://{{baseUrl}}/vtolRest/vtolConfig


Invocar al servicio

Para eliminar una Instancia de VTOL Server, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/VtolConfig

  2. Dirigirse a la sección:


  3. Repetir los mismos pasos del alta.



3.2 Merchant

Configuración por API Rest

El servicio /merchant permite configurar los datos de la compañía en VTOL-Vtex Integrator.

Documentación en Swagger

El detalle completo del servicio de Alta de Merchant, se encuentra documentado en Swagger:

https://{IP}:{Port}/vtolRest/swagger-ui.html#/Merchant


Alta de Merchant

Permite dar de alta un Merchant dentro del módulo VTOL-VTEX Integrator.

MétodoPOST
Urlhttps://{{baseUrl}}/vtolRest/merchant


Los datos necesarios para el alta son:

merchantCode

Código de la compañía en Vtol Server.

merchantName

Nombre de la compañía.

merchantStoreCode

Código del local en Vtol Server

token

appKey

Llave de token de validación. Dato provisto por Vtex.

appToken

Token de validación. Dato provisto por Vtex.

vtolCode

Configuración de la instancia de VTOL Server por el cual se procesarán las transacciones.

Este dato debe corresponderse con alguna instancia de VTOL Server configurada en el servicio /VtolServer.

Por ejemplo si en el servicio /VtolServer se configura una instancia de VTOL Server con el siguiente code:

  • VTOLCDMX

Entonces en este campo (vtolCode) se deberá cargar el valor: VTOLCDMX


Invocar al servicio

Para dar de alta un Merchant, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/Merchant

  2. Dirigirse a la sección:



  3. Presionar el botón:


  4. Completar los datos del JSON:


  5. Presionar el botón Execute:


  6. Si los datos informados en el JSON son correctos, se creará el Merchant, retornando el código HTTP201 y un eco de los parámetros enviados:


Modificar Merchant

Permite modificar un Merchant dentro del módulo VTOL-VTEX Integrator.

MétodoPUT
Urlhttps://{{baseUrl}}/vtolRest/merchant


Invocar al servicio

Para modificar un Merchant, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/Merchant

  2. Dirigirse a la sección:



  3. Repetir los mismos pasos del alta.


Consultar Merchant

Permite realizar una consulta de los Merchant que están configurados dentro del módulo VTOL-VTEX Integrator.

MétodoGET
Urlhttps://{{baseUrl}}/vtolRest/merchants


Invocar al servicio

Para consultar los Merchant, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/Merchant

  2. Dirigirse a la sección:

  3. Repetir los mismos pasos del alta.


Eliminar Merchant

Permite eliminar un Merchant dentro del módulo VTOL-VTEX Integrator.

MétodoDELETE
Urlhttps://{{baseUrl}}/vtolRest/merchant


Invocar al servicio

Para eliminar un Merchant, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/Merchant

  2. Dirigirse a la sección:


  3. Repetir los mismos pasos del alta.



3.3 PaymentMethod

Configuración por API Rest

El servicio /paymentMethod permite configurar las tarjetas soportadas por el módulo VTOL-Vtex Integrator.

Documentación en Swagger

El detalle completo del servicio de Alta de Merchant, se encuentra documentado en Swagger:

https://{Ip}:9080/vtolRest/swagger-ui.html#/PaymentMethod


Alta de Medios de Pago

Permite el alta de un medio de pago dentro del módulo VTOL-Vtex Integrator.

MétodoPOST
Urlhttps://{{baseUrl}}/vtolRest/v1/payment-method


Los datos necesarios para el alta son:

name

Nombre de la tarjeta.

country

País de la tarjeta. Valor por defecto: “Global”

X-VTEX-API-AppKeyLlave de token de validación. Dato provisto por Vtex.
X-VTEX-API-AppTokenToken de validación. Dato provisto por Vtex.


Invocar al servicio

Para dar de alta una tarjeta, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/PaymentMethod

  2. Dirigirse a la sección:



  3. Presionar el botón:


  4. Completar los datos: X-VTEX-API-AppKey, X-VTEX-API-AppToken y paymentMethod (JSON)


  5. Presionar el botón: Execute


  6. Si los datos informados son correctos, se creará el Medio de Pago, retornando el código HTTP200 y la lista de paymentMethod soportados:


Modificar Medios de pago

Permite modificar un Medio de Pago dentro del módulo VTOL-VTEX Integrator.

MétodoPUT
Urlhttps://{{baseUrl}}/vtolRest/v1/payment-method


Invocar al servicio

Para modificar un Medio de pago, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/PaymentMethod

  2. Dirigirse a la sección:



  3. Repetir los mismos pasos del alta.


Consultar Medios de pago

Permite realizar una consulta de los Medios de Pago que están configurados dentro del módulo VTOL-VTEX Integrator.

MétodoGET
Urlhttps://{{baseUrl}}/vtolRest/v1/payment-methods


Invocar al servicio

Para consultar los Merchant, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/PaymentMethod

  2. Dirigirse a la sección:



  3. Repetir los mismos pasos del alta.


Eliminar Medio de pago

Permite eliminar un Medio de Pago dentro del módulo VTOL-VTEX Integrator.

MétodoDELETE
Urlhttps://{{baseUrl}}/vtolRest/v1/payment-method


Invocar al servicio

Para eliminar un Medio de Pago, se puede utilizar la herramienta Swagger, de la siguiente manera:

  1. Abrir la url: https://{Ip}:{Port}/vtolRest/swagger-ui.html#/PaymentMethod

  2. Dirigirse a la sección:


  3. Repetir los mismos pasos del alta.



4. Servicios de Transacciones

VTOL-Vtex Integrator expone los servicios requeridos por el E-commerce Vtex para realizar transacciones de crédito-débio. Todos los servicios de transacciones reciben en el header los parámetros: “X-VTEX-API-AppKey” y “X-VTEX-API-AppToken”. Estos datos se utilizan para autenticar el requerimiento, y se contrastan contra los parámetros “appKey” y “appToken” respectivamente, de la entidad Merchant de la base de datos del módulo VTOL-Vtex Integrator.


4.1 Preautorizacion

Recibe un requerimiento de preautorizacion del Ecommerce Vtex y la reenvía a Vtol Server. Si expira el tiempo de procesamiento de la transacción, el servicio retorna el código “V01” con status: “Undefinied”, esto indica al E-Commerce Vtex que debe consultar el status de la preautorización.

URL del Servicio:

https://{{baseUrl}}/v1/payments/v1/payments


4.2 Cancelación de preautorizacion

Recibe un requerimiento de cancelación preautorizacion, previamente aprobada, desde el  E-Commerce Vtex y la reenvía a Vtol Server. Si expira el tiempo de procesamiento de la transacción, el servicio retorna el código “V01” con status: “Undefinied”, esto indica al E-Commerce Vtex que debe consultar el status de la preautorización.

URL del Servicio:

https://{{baseUrl}}/v1/payments/:paymentId/cancellations


4.3 Captura

Recibe un requerimiento de captura de una preautorizacion, previamente aprobada, desde el E-commerce Vtex y la reenvía a Vtol Server. Si expira el tiempo de procesamiento de la transacción, el servicio retorna el código “V01” con status: “Undefinied”, esto indica al E-Commerce Vtex que debe consultar el status de la preautorización.

URL del Servicio: https://{{baseUrl}}/v1/payments/:paymentId/settlements


4.4 Devolución

Recibe un requerimiento de una devolución de una captura, previamente aprobada, desde el E-commerce Vtex y la reenvía a Vtol Server. Si expira el tiempo de procesamiento de la transacción, el servicio retorna el código “V01” con status: “Undefinied”, esto indica al E-Commerce Vtex que debe consultar el status de la preautorización.

URL del Servicio:

https://{{baseUrl}}/v1/payments/:paymentId/refunds

Nota:

Para más detalle de los servicios de transacciones que expone el modulo VtexIS, ingrese en la definición de Swagger: https://{{baseUrl}}/ /vtolRest/swagger-ui.html#/


5. Proceso de contingencia

El proceso de contingencia del módulo VtexIS, se ejecuta en background cada 15 minutos y su objetivo es sincronizar las transacciones con Vtol Server. Obtiene las transacciones que están pendientes en Vtol  y decide si debe enviar un Commit o un Rollback.

Funcionamiento: Cada vez que se ejecuta el proceso, obtiene para cada Merchant todas las transacciones pendientes en Vtol Server.

  1. Si la transacción que está pendiente en Vtol Server y se encuentra en la collection Transaction de VtexIS, enviara un Commit.
  2. Si la transacción que esta pendiente en Vtol Server, pero no se encuentra la collection Transacction, se la agrega en la collection TransactionPending de VtexIS y no se realiza ninguna acción, es decir no se envía el 3er mensaje a Vtol Server.
  3. Si la transacción que está pendiente en Vtol Server no se encuentra en la collecttion Transaction y además se encuentra en la collection TransactionPending, quiere decir que es la segunda vez que se procesa, entonces se envía un Rollback a Vtol Server y se elimina de la collection TransactionPending.


6. VTEX E-Commerce Payment Provider Test Suite

El E-Commerce Vtex provee un sitio para realizar una prueba de los servicios de integración que expone el módulo VtexIS de Vtol.

La url de la suite de test es: https://napsemx.myvtex.com/admin/test-suite/payment-provider Es necesario previamente estar registrado en el sitio de Vtex.

Los datos de prueba son:

    1. Connector Name: NAPSEVTOL
    2. X-VTEX-API-AppKey: vtexappkey-napsemx-XELDAN
    3. X-VTEX-API-AppToken: LTHDQKBHNZRCYDWYBEQJVZMLYSOMIUOQUATUQFNKKNOQIQSTTRSQJUTLGVFXWPYSKBIXJBHVRFYHLWDHAVSRCYHAGHNUAQOVPWFHIUJRKWZDVMAKSXWBWHPMTHQCOMVA
    4. Service URL: https://demodev.napse.global:55559/vtolRest/v1



Además, es necesario tener el emulador de CA corriendo y con la configuración de canal BanamexEG (BanamexEG.properties)

response.0100.class=iso.message.BanamexEGResponses.BanamexEGResponse110OKVTEX



  • Sem rótulos