oh! Gift Card - VTEX Docs

Módulo de consumo en VTEX

Módulo de consumo en VTEX

Configuración de cliente ⚙️

  1. Afiliación llamada Gift Card (nuevo).

Módulo de consumo

  1. Ir a Planes de pago y configurar el plan de pago llamado Vale.

Módulo de consumo

Configuración Cliente y Agencia

Desde el checkout de Vtex se mostrará un solo campo:

Módulo de consumo

Este es el comportamiento por defecto del e-commerce que ofrece VTEX. Para realizar pruebas es posible ingresar concatenados en ese campo Nro de Gift Card (16 dígitos) + Cód. Seguridad (3 dígitos) y con eso la operación funcionará correctamente.

Para pasar a nivel productivo, sin embargo, se recomienda modificar el front de manera que ese único campo quede dividido en dos. Uno para el número de tarjeta y otro para el código de seguridad. Luego, por javascript, juntar esos dos datos y concatenarlos a la hora de hacer la llamada o submit. Esta modificación requiere verificación con VTEX.

Módulo de consumo

Configuración VTEX

Es necesario hacer un llamado PUT a la siguiente API de VTEX para que la integración entre el Gift Card Hub de VTEX y los servicios de Oh! Gift Card queden configurados correctamente.

Es obligatorio para esto que Oh! Gift Card provea un endpoint para incluir en la configuración.

Formato de llamada a la API de VTEX

URL:

https://[accountName][.vtexcommercestable.com.br/api/giftcardproviders/ohgiftcard](http://.vtexcommercestable.com.br/api/giftcardproviders/ohgiftcard)
Aclaración: [accountName] debe ser reemplazado por el nombre del ambiente del cliente.

Headers

Content-Type: application/vnd.vtex.giftcardproviders.v1+json
Accept: application/vnd.vtex.giftcardproviders.v1+json
X-VTEX-API-AppKey: [VTEX App Key]
X-VTEX-API-AppToken: [VTEX App Token]

Body

{
  "id": "ohgiftcard",
  "serviceUrl": "https://demo.ohgiftcard.com/vtex/184545",
  "oauthProvider": "vtex",
  "caption": "oh Gift Card",
  "preAuthEnabled": true,
  "cancelEnabled": true,
  "appKey": "Proporcionadas por Oh!",
  "appToken": "Proporcionadas por Oh!",
  "_self": {
    "href": "[accountName]/giftcardproviders/ohgiftcard"
  }
}

Notas

  • serviceUrl: URL del endpoint donde VTEX enviará los requests a Oh! Gift Card.
  • oauthProvider: No se utiliza un proveedor OAuth externo, debe configurarse como "vtex".
  • caption: Descripción del servicio, en este caso, "oh Gift Card".
  • preAuthEnabled y cancelEnabled: Siempre deben estar en true (aunque el flujo de preautorización no funciona actualmente).
  • _self.href: Endpoint de integración con el sistema de Gift Card Hub nativo de VTEX. El valor [accountName] debe ser reemplazado con el nombre del ambiente del cliente.
  • appKey y appToken: Credenciales asignadas por Oh! Gift Card.
  • X-VTEX-API-AppKey y X-VTEX-API-AppToken: Credenciales proporcionadas por VTEX.

Una vez armado el request y ejecutado contra la API de VTEX indicada en este punto habrá quedado configurada la cuenta para que cada vez que se haga checkout del pago con Gift Card en el e-commerce se impacte la operación contra el servicio de Oh! Gift Card.

A continuación, se indica cómo configurar el ambiente Demo en el campo serviceUrl.

💡 Al momento de pasar a producción se deberá solicitar la URL definitiva a oh! Gift Card.

Configuración cliente Postman para llamada a la API de VTEX

  1. Descargar Postman desde el sitio web oficial.
  2. Crear un request.
  3. Configurar los headers antes mencionados.

Módulo de consumo

  1. Configurar el body de la llamada.

Módulo de consumo

Reemplazando los valores entre llaves {{ }} por los mencionados en el apartado Configuración VTEX y presionando Send debería efectuarse la llamada y, si todo va bien, en el apartado Response obtendremos un Status 200 (OK).

Con esto ya habrá quedado configurada la integración Gift Card Hub - Oh Gift Card correctamente 🔥.

Configuración Provider

Una vez hayas realizado de forma correcta el consumo del endpoint a través de Postman. Deberás dirigirte dentro tu administrador de VTEX y realizar los siguientes pasos:

  1. Dentro de Configuración de la tienda, visita el módulo PAGO.
  2. En la sección Proveedores, busca el proveedor que creaste hace un momento e ingresa dando click en su nombre. Para este ejemplo lo llamamos ohgiftcard (no es necesario colocar dicho nombre).
  3. Deberás tener la misma configuración de la siguiente imagen.

    Recuerda contar con esta configuración. De lo contrario, las tarjetas de regalo podrían presentar errores.

Configuración del checkout en VTEX ⚙️

Una vez, hayas realizado cada una de las configuraciones previas, deberás adicionar código dentro del checkout de VTEX para que las personalizaciones funcionen.

Pasos:

  1. Dentro de tu administrador de VTEX, dirígete a Configuración de la tienda, y dentro del módulo Storefront encontrarás la sección Checkout.
  2. Dirígete a tu checkout por defecto o al que tengas configurado en producción para darle click al botón azul con forma de engranaje.
  3. Verás varias secciones en la parte superior, dirígete a la sección Código. Y luego dentro de archivos, darle click a checkout6-custom.js.
  4. Se habilitará un espacio para poder agregar código dentro del checkout. Deberás copiar el siguiente código.
const giftCardFunction = (function () {
  const giftCardUtils = {
    initializeAjaxHandlers: function () {
      $(document).ajaxStop(function () {
        console.info("ajaxStop");
        giftCardUtils.changeTitleGiftCardContainer();
        giftCardUtils.createGiftCardInputs();
        giftCardUtils.calculateTotalGiftCard();
      });
    },
    initializeEventHandlers: function () {
      $(window).on("orderFormUpdated.vtex", function () {
        console.info("orderFormUpdated.vtex");
      });
      $(window).load(function () {
        console.info("load");
        giftCardUtils.setupGiftCardEventHandlers();
        giftCardUtils.calculateTotalGiftCard();
      });
      $(window).on("hashchange", function () {
        console.info("hashchange");
      });
    },
    initializeDocumentReady: function () {
      $(document).ready(function () {
        console.info("ready");
        giftCardUtils.createGiftCardInputs();
      });
    },
    formatCurrency: function (amount, currency, locale = "en-US") {
      return new Intl.NumberFormat(locale, {
        style: "currency",
        currency: currency,
      }).format(amount);
    },
    parseCurrencyToNumber: function (currencyString) {
      const cleanString = currencyString
        .replace(/[^\d,-]/g, "")
        .replace(",", ".");
      return parseFloat(cleanString);
    },
    setupGiftCardEventHandlers: function () {
      const giftCardButton = document.querySelector("a#show-gift-card-group");
      if (giftCardButton) {
        giftCardButton.addEventListener("click", function () {
          console.log("giftCardButton", giftCardButton);
          giftCardUtils.createGiftCardInputs();
        });
      }
    },
    validateInput: function (inputElement, regex, maxLength) {
      inputElement.addEventListener("input", function () {
        let value = inputElement.value;
        value = value.replace(/[^a-zA-Z0-9]/g, ""); // Remove invalid characters
        inputElement.value = value.slice(0, maxLength); // Limit input length
        if (value.length === maxLength) {
          inputElement.classList.remove("error");
          inputElement.classList.add("success");
        } else {
          inputElement.classList.remove("success");
          inputElement.classList.add("error");
        }
      });
    },
    changeTitleGiftCardContainer: function () {
      const titleGiftCardContainer = document.querySelector(
        "#payment-data .box-step-content #show-gift-card-group"
      );
      if (titleGiftCardContainer) {
        titleGiftCardContainer.textContent = "Tarjeta GiftCard";
      }
    },
    createGiftCardInputs: function () {
      const checkElementExistence = setInterval(() => {
        const labelElement = document.querySelector(
          "p.payment-discounts-options.text.input.form-inline label"
        );
        if (labelElement && !document.querySelector("#cardCode")) {
          clearInterval(checkElementExistence);
          console.log("buscando..")
          const cardCodeInput = document.createElement("input");
          cardCodeInput.setAttribute("type", "text");
          cardCodeInput.setAttribute("id", "cardCode");
          cardCodeInput.setAttribute("placeholder", "Número de tarjeta");
          giftCardUtils.validateInput(cardCodeInput, /^[a-zA-Z0-9]*$/, 16);
          labelElement.style.display = "block";
          labelElement.textContent = "Ingresa tu giftcard";
          labelElement.after(cardCodeInput);
          const securityCodeInput = document.createElement("input");
          securityCodeInput.setAttribute("type", "text");
          securityCodeInput.setAttribute("id", "securityCode");
          securityCodeInput.setAttribute("placeholder", "CVV");
          securityCodeInput.style.width = "50px";
          securityCodeInput.style.marginLeft = ".25rem";
          giftCardUtils.validateInput(securityCodeInput, /^[a-zA-Z0-9]*$/, 3);
          cardCodeInput.after(securityCodeInput);
          const giftCardHiddenInput = document.querySelector(
            "#payment-discounts-code"
          );
          if (giftCardHiddenInput) {
            giftCardHiddenInput.style.display = "none";
          }
          giftCardUtils.setupInputEvents(
            $(cardCodeInput),
            $(securityCodeInput),
            $(giftCardHiddenInput)
          );
        }
      }, 100);
    },
    setupInputEvents: function (cardCode, securityCode, giftCard) {
      [cardCode, securityCode].forEach((input) => {
        input.on("change keyup", function () {
          giftCard.val(cardCode.val() + securityCode.val()).trigger("keyup");
        });
      });
    },
    calculateTotalGiftCard: function () {
      const orderForm = window.vtexjs.checkout.orderForm;
      if (orderForm?.paymentData?.giftCards?.length) {
        const totalGiftCardAmount =
          orderForm.paymentData.giftCards.reduce(
            (sum, giftCard) => sum + giftCard.value,
            0
          ) / 100;
        const cartTable = document.querySelector(
          ".cart-template.mini-cart .summary-template-holder .summary-totalizers.cart-totalizers .accordion-inner .table"
        );
        if (!document.querySelector("#DiscountsGiftCards")) {
          const discountRow = document.createElement("tr");
          discountRow.setAttribute("id", "DiscountsGiftCards");
          discountRow.innerHTML = `
              <td class="info">Descuentos GiftCard</td>
              <td class="space"></td>
              <td class="monetary">-${giftCardUtils.formatCurrency(
                totalGiftCardAmount,
                "ARS",
                "es-AR"
              )}</td>
              <td class="empty"></td>
            `;
          cartTable.querySelector(".totalizers-list .Items").after(discountRow);
        } else {
          document.querySelector("#DiscountsGiftCards .monetary").innerHTML =
            "-" +
            giftCardUtils.formatCurrency(totalGiftCardAmount, "ARS", "es-AR");
        }
        const footerTotal = cartTable.querySelector("tfoot tr .monetary");
        const totalNumber = giftCardUtils.parseCurrencyToNumber(
          footerTotal.textContent
        );
        footerTotal.textContent = giftCardUtils.formatCurrency(
          Math.max(0, totalNumber - totalGiftCardAmount),
          "ARS",
          "es-AR"
        );
      } else if (document.querySelector("#DiscountsGiftCards")) {
        document.querySelector("#DiscountsGiftCards").remove();
      }
    },
  };
  const initializeGiftCardFunctionality = function () {
    giftCardUtils.initializeAjaxHandlers();
    giftCardUtils.initializeEventHandlers();
    giftCardUtils.initializeDocumentReady();
  };
  initializeGiftCardFunctionality();
})(jQuery, window);

En caso ya cuentes con código dentro, se recomienda consultar con un especialista para poder realizar la configuración evitando cualquier incidencia. En cuanto hayas pegado todo el código, en la parte superior aparecerá un botón con el nombre Guardar en color azul, debes darle click y aparecerá un mensaje confirmando el guardado. ¡Y listo! Ya podrás contar con las configuraciones dentro de tu tienda.

Prev

Configuración de scripts

Next

Flujo del cliente

En esta página