Storefront API¶

La Storefront API ofrece una interfaz de JavaScript (window.GiftHeroAPI) para crear flujos personalizados de selección y compra de tarjetas de regalo en tu tienda online.

Configuración de la Storefront API

Activar la API¶

Ve a For developers en la navegación de la izquierda.
Marca Enable storefront API y guarda.

La interfaz de tarjeta de regalo que genera la app en tu página de producto de tarjeta de regalo se desactiva, y en su lugar se carga window.GiftHeroAPI. Tú construyes la interfaz.

La API no lee saldos de tarjetas de regalo. Recoge las elecciones del comprador y añade la tarjeta de regalo al carrito.

Tiendas headless

En una tienda headless, la API se carga cuando el modo headless y Enable storefront API están ambos activados. Consulta Integración headless.

Inicialización¶

La API se carga de forma asíncrona. Gift Card Hero dispara un evento en window cuando está lista. Escúchalo antes de llamar a cualquier método:

window.addEventListener('gift.hero:initalized', function () {
  const api = window.GiftHeroAPI;
  // API is ready to use
});

El nombre del evento se escribe initalized

El nombre del evento tiene una errata: gift.hero:initalized (sin segunda "i"). Úsalo exactamente como está escrito. El evento se dispara en window, no en document, después de que se cargue el script de la tienda de Gift Card Hero. Si el script no está en la página, o la Storefront API está desactivada, el evento no se dispara.

Al iniciarse, la API selecciona la primera variante (o la indicada en el parámetro de URL ?variant=) y la primera imagen.

Métodos¶

addToCart(quantity?, skipValidation?)¶

Valida los datos de la tarjeta y añade la tarjeta de regalo configurada al carrito con /cart/add.js de Shopify.

try {
  const result = await window.GiftHeroAPI.addToCart(1);
  // result: { status: 200, data: { ... } }
} catch (e) {
  // e: { status: 400, data: { errors: ['...'] } } when validation fails
}

Parámetro	Tipo	Valor por defecto	Descripción
`quantity`	number	1	Número de tarjetas de regalo que se añaden
`skipValidation`	boolean	false	Añade la tarjeta aunque `validate()` informe de errores

Devuelve: una promesa con la respuesta del carrito de Shopify ({ status, data }). Se rechaza con { status: 400, data: { errors } } cuando la validación falla.

generatePreview()¶

Abre una vista previa de cómo se verá la tarjeta de regalo para el destinatario, con los datos introducidos hasta ahora.

window.GiftHeroAPI.generatePreview();

getImages()¶

Devuelve un array de URL de imágenes disponibles para la tarjeta de regalo: tus diseños propios, los diseños integrados seleccionados y, si está activado, las imágenes del producto.

const images = window.GiftHeroAPI.getImages();
// ['https://cdn.shopify.com/...', 'https://cdn.shopify.com/...']

getOptions()¶

Devuelve las opciones del producto, incluidas las denominaciones disponibles.

const options = window.GiftHeroAPI.getOptions();

getTranslations()¶

Devuelve las traducciones de la interfaz para el idioma actual, como las etiquetas y el mensaje de validación.

const translations = window.GiftHeroAPI.getTranslations();

getVariants()¶

Devuelve el array de variantes del producto.

const variants = window.GiftHeroAPI.getVariants();

setCardData(cardData)¶

Define todos los datos de la tarjeta de regalo de una vez.

window.GiftHeroAPI.setCardData({
  variantId: 12345678,
  image: 'https://cdn.shopify.com/...',
  message: 'Happy Birthday!',
  from: 'Alice',
  to: 'Bob',
  deliveryDate: new Date('2026-12-25'),
  email: 'recipient@example.com'
});

Campo	Tipo	Descripción
`variantId`	number	El ID de la variante seleccionada
`image`	string	URL de la imagen de tarjeta seleccionada
`message`	string	Mensaje de la tarjeta de regalo
`from`	string	Nombre del remitente
`to`	string	Nombre del destinatario (opcional)
`deliveryDate`	`Date`	Fecha programada de entrega, como objeto `Date` de JavaScript (opcional)
`email`	string	Correo electrónico del destinatario (opcional)

La entrega por SMS no está disponible a través de la API, así que no hay campo de teléfono.

Métodos individuales¶

Método	Parámetro	Descripción
`setDeliveryDate(date)`	`Date`	Define la fecha de entrega programada. Lanza un error si no es un objeto de fecha válido
`setEmail(email)`	string	Define el correo del destinatario
`setFrom(name)`	string	Define el nombre del remitente
`setTo(name)`	string	Define el nombre del destinatario
`setImage(image)`	string	Define la URL de la imagen de tarjeta seleccionada
`setMessage(message)`	string	Define el mensaje de la tarjeta de regalo
`setVariant(variantId)`	number or string	Define la variante seleccionada
`setProperty(name, value)`	string, string	Añade una propiedad extra al artículo del carrito

validate()¶

Comprueba los datos actuales de la tarjeta de regalo y devuelve { valid, errors }, donde errors es un array de mensajes creados a partir de tus traducciones.

const { valid, errors } = window.GiftHeroAPI.validate();

Reglas de validación:

Si hay un correo del destinatario, la fecha de entrega, el nombre del remitente (from) y el mensaje son obligatorios.
Si hay una fecha de entrega, el correo del destinatario, el nombre del remitente y el mensaje son obligatorios.
Sin correo y sin fecha de entrega, no es obligatorio nada.

setCustomAmount(amount)¶

Selecciona un importe personalizado, en la moneda de tu tienda (por ejemplo 75 para 75.00). Solo funciona si los importes personalizados están activados en tu tienda; si no, lanza Custom amount is not enabled. El método no comprueba tu mínimo y máximo, así que valida el importe tú mismo.

window.GiftHeroAPI.setCustomAmount(75);

Tarjetas de regalo físicas¶

Si vendes tarjetas de regalo físicas, cambia la API a ellas con setCardType('physical') (usa setCardType('eGift') para volver).

Método	Descripción
`setCardType(type)`	`'eGift'` o `'physical'`. Elegir `'physical'` selecciona la primera variante e imagen físicas
`getPhysicalProduct()`	El producto de tarjeta de regalo física
`getPhysicalVariants()`	Variantes del producto físico
`getPhysicalImages()`	URL de las imágenes del producto físico
`setPhysicalVariant(variantId)`	Selecciona una variante física (solo tipo físico)
`setPhysicalDeliveryAddress(address)`	Define la dirección de entrega (solo tipo físico): `firstName`, `lastName`, `address`, `zipCode`, `city`, `country` y `state` opcional
`isPhysicalCard()`	`true` cuando está seleccionado el tipo físico

uploadCustomDesign(file, options?)¶

Sube una imagen propia del comprador y devuelve su URL, que puedes pasar a setImage().

const { url } = await window.GiftHeroAPI.uploadCustomDesign(file);
window.GiftHeroAPI.setImage(url);

El archivo debe ser una imagen JPG, PNG, GIF o WebP, de hasta 5 MB por defecto. Puedes cambiar los límites con options.maxSize (bytes) y options.allowedTypes. El método lanza un error con un mensaje claro cuando se rechaza el archivo.

Ejemplo de integración con React¶

Hay un ejemplo completo de integración con React en JSFiddle. Muestra cómo inicializar la API, crear una interfaz personalizada de selección de tarjetas de regalo y gestionar el flujo de añadir al carrito:

Ver el ejemplo de React en JSFiddle