API de Dcart¶

Descripción general¶

La API de descuentos ofrece un sistema completo para gestionar códigos de descuento y tarjetas de regalo en tu tienda Shopify. Esta API te permite aplicar descuentos mediante programación, calcular ahorros e integrar la funcionalidad de descuentos en el código de tu tienda online.

Primeros pasos¶

Configuración básica¶

La API de descuentos se inicializa automáticamente al cargar la app. Puedes empezar a usarla de inmediato a través del objeto global dcartAPI.

// Wait for the API to be ready
window.addEventListener('DCART:appApi.initialized', function() {
  // API is now ready to use
  console.log('Discount API ready');
});

Funcionalidad principal¶

Aplicar códigos de descuento¶

Usa el método apply() para activar códigos de descuento para los clientes.

Aplica un único código de descuento:

dcartAPI.apply('SAVE20')
  .then(() => {
      console.log('Discount applied successfully');
  })
  .catch((error) => {
      console.error('Failed to apply discount:', error);
  });

Aplica varios códigos de descuento:

dcartAPI.apply(['SAVE20', 'FREESHIP'])
  .then(() => {
    console.log('All discounts applied successfully');
  });

Nota: Los códigos de descuento se convierten automáticamente a minúsculas y se les quitan los espacios sobrantes.

Eliminar códigos de descuento¶

Elimina los códigos de descuento activos con el método remove().

Elimina un código de descuento concreto:

dcartAPI.remove('SAVE20')
  .then(() => {
    console.log('Discount removed successfully');
  });

Elimina todos los códigos de descuento activos:

dcartAPI.remove()
  .then(() => {
    console.log('All discounts removed');
  });

Gestionar tarjetas de regalo¶

Elimina las tarjetas de regalo aplicadas usando su identificador único.

dcartAPI.removeGiftCard('giftcard_id_here')
  .then(() => {
    console.log('Gift card removed successfully');
  });

Calcular descuentos¶

Previsualiza los cálculos de descuento sin aplicarlos al carrito.

const discountCodes = ['SAVE20', 'FREESHIP'];
const cartItems = [
  { id: 123, quantity: 2, price: 2500 },
  { id: 456, quantity: 1, price: 1000 }
];

dcartAPI.calculate(discountCodes, cartItems)
  .then((discountData) => {
    console.log('Calculated savings:', discountData);
    // discountData contains totals, savings, and applied discounts
  });

Sistema de eventos¶

La API de descuentos ofrece un sistema de eventos completo para hacer seguimiento de la actividad de descuentos e integrarla con tu código personalizado.

Suscribirse a eventos¶

window.addEventListener('DCART:appApi.initialized', function() {
  // Subscribe to discount events
  dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Applied, function(data) {
    console.log('Discount was applied:', data);
  });
});

Eventos disponibles¶

`dcartAPI.Events.Discount.Calculated`¶

Se activa cuando los cálculos de descuento se completan o se recalculan.

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Calculated, function(discountData) {
  console.log('Discount calculated:', discountData);
  // Update UI with new totals
  updateCartTotals(discountData);
});

Casos de uso:

Actualizar las pantallas de totales personalizadas
Refrescar los resúmenes del carrito
Disparar eventos de analíticas

`dcartAPI.Events.Discount.Apply`¶

Se activa cuando se hace clic en el botón de aplicar, antes de procesar el descuento.

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Apply, function(data) {
  console.log('User clicked apply button');
  // Show loading indicator
  showLoadingSpinner();
});

Casos de uso:

Mostrar estados de carga
Validar los códigos de descuento antes de enviarlos
Hacer seguimiento de las interacciones del usuario

`dcartAPI.Events.Discount.Applied`¶

Se activa cuando un código de descuento se aplica correctamente al carrito.

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Applied, function(data) {
  console.log('Discount successfully applied:', data);
  // Show success message
  showSuccessMessage('Discount applied!');
  // Track conversion
  gtag('event', 'discount_applied', { discount_code: data.code });
});

Casos de uso:

Mostrar mensajes de éxito
Actualizar las pantallas del carrito
Hacer seguimiento de las aplicaciones de descuento correctas
Disparar flujos de trabajo promocionales

`dcartAPI.Events.Discount.Removed`¶

Se activa cuando se elimina un código de descuento del carrito.

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Removed, function(data) {
  console.log('Discount removed:', data);
  // Update UI to reflect removal
  removeDiscountFromDisplay(data.code);
});

Casos de uso:

Actualizar las pantallas del carrito
Eliminar mensajes promocionales
Hacer seguimiento de las eliminaciones de descuentos
Restablecer los estados promocionales

Ejemplo completo de integración de eventos¶

(function() {
  window.addEventListener('DCART:appApi.initialized', function() {
  // Track all discount interactions
  dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Apply, function() {
  // User started applying discount
  document.querySelector('.discount-form').classList.add('loading');
});

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Applied, function(data) {
  // Discount successfully applied
  document.querySelector('.discount-form').classList.remove('loading');
  showNotification('Discount applied: ' + data.code, 'success');

  // Track in analytics
  if (typeof gtag !== 'undefined') {
    gtag('event', 'discount_applied', {
      discount_code: data.code,
      discount_amount: data.amount
    });
  }
});

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Calculated, function(discountData) {
  // Update custom total displays
  const savings = discountData.originalTotal - discountData.total;
  if (savings > 0) {
    document.querySelector('.savings-display').textContent =
      'You saved $' + (savings / 100).toFixed(2);
  }
});

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Removed, function(data) {
  // Handle discount removal
  showNotification('Discount removed: ' + data.code, 'info');
  document.querySelector('.savings-display').textContent = '';
});
  });
})();

Gestión de errores¶

Implementa siempre una gestión de errores adecuada para las operaciones de descuento:

// Handle specific error types
dcartAPI.apply('INVALID_CODE') .then(() => { console.log('Success'); })
  .catch((error) => {
    console.error('Error applying discount:', error);
    if (error.message.includes('expired')) {
       showErrorMessage('This discount code has expired');
    } else if (error.message.includes('invalid')) {
       showErrorMessage('Invalid discount code');
    } else {
       showErrorMessage('Unable to apply discount. Please try again.');
    }
});

Buenas prácticas¶

Consideraciones de rendimiento¶

Operaciones por lotes : Al aplicar varios códigos, usa una sola llamada a apply() con un array
Limitación de eventos : Aplica debounce a los cálculos de descuento rápidos para evitar problemas de rendimiento
Recuperación de errores : Implementa lógica de reintento para fallos de red

Experiencia de usuario¶

Estados de carga : Muestra siempre indicadores de carga durante las operaciones de descuento
Feedback claro : Ofrece retroalimentación inmediata cuando se aplican o eliminan descuentos
Validación : Valida los códigos de descuento en el cliente siempre que sea posible para reducir las solicitudes al servidor

Pautas de integración¶

Orden de eventos : Suscríbete a los eventos después de que la API esté inicializada
Gestión de memoria : Cancela la suscripción a los eventos cuando se destruyan los componentes
Gestión de alternativas : Implementa alternativas para cuando la API no esté disponible

Casos de uso habituales¶

Aplicar descuentos desde la URL automáticamente¶

// Check URL for discount parameters and auto-apply
const urlParams = new URLSearchParams(window.location.search);
const discountCode = urlParams.get('discount');

if (discountCode) {
  window.addEventListener('DCART:appApi.initialized', function() {
    dcartAPI.apply(discountCode);
  });
}

Integración de cuenta atrás promocional¶

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Applied, function(data) {
  // Start countdown timer for time-sensitive discounts
  if (data.expiresAt) {
    startCountdownTimer(data.expiresAt);
  }
});

Integración de pruebas A/B¶

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Calculated, function(discountData) {
  // Track discount effectiveness for A/B testing
  analytics.track('discount_calculated', {
    test_variant: getTestVariant(),
    discount_amount: discountData.totalSavings,
    cart_total: discountData.total
  });
});

Referencia de la API¶

Métodos¶

`apply(codes: string | string[]): Promise`¶

Aplica uno o varios códigos de descuento al carrito.

Parámetros:

codes: Una cadena con un código de descuento o un array de códigos de descuento

Devuelve: Promise que se resuelve cuando los códigos se aplican

`remove(code?: string): Promise`¶

Elimina un código de descuento concreto o todos los códigos si no se indica ninguno.

Parámetros:

code (opcional): El código de descuento que se va a eliminar. Si se omite, elimina todos los códigos

Devuelve: Promise que se resuelve cuando se eliminan los códigos

`removeGiftCard(id: string): Promise`¶

Elimina una tarjeta de regalo del carrito.

Parámetros:

id: El ID de la tarjeta de regalo que se va a eliminar

Devuelve: Promise que se resuelve cuando la tarjeta de regalo se elimina

`calculate(codes: string[], items: any[]): Promise`¶

Calcula los importes de descuento sin aplicarlos.

Parámetros:

codes: Array de códigos de descuento que se van a calcular
items: Array de artículos del carrito sobre los que calcular

Devuelve: Promise que se resuelve con los datos del cálculo de descuentos

`setCustomConfig(config: Record): void`¶

Define opciones de configuración personalizadas.

Parámetros:

config: Objeto de configuración con ajustes personalizados

`cloneAndInjectInfo(targetSelector: string): void`¶

Copia la información de descuentos a un elemento de destino.

Parámetros:

targetSelector: Selector CSS del elemento de destino

Eventos¶

Evento	Descripción
`Discount.Calculated`	Cálculos de descuento completados
`Discount.Apply`	Se hace clic en el botón de aplicar
`Discount.Applied`	Descuento aplicado correctamente
`Discount.Removed`	Descuento eliminado del carrito

Solución de problemas¶

Problemas habituales¶

Los descuentos no se aplican

Verifica que el código de descuento sea válido y esté activo
Comprueba que el carrito cumple los requisitos mínimos
Asegúrate de que la API esté inicializada correctamente

Los eventos no se disparan

Confirma que las suscripciones a eventos se realizan después de inicializar la API
Busca errores de JavaScript en la consola
Verifica que los nombres de los eventos estén bien escritos

Los totales no se actualizan

Comprueba que los selectores de totales estén bien configurados
Verifica que la configuración personalizada no excluya elementos necesarios
Asegúrate de que los elementos de la página existan cuando se calculen los totales

¿Necesitas ayuda? Escribe a support@syncu.be.

API de Dcart¶

Descripción general¶

Primeros pasos¶

Configuración básica¶

Funcionalidad principal¶

Aplicar códigos de descuento¶

Eliminar códigos de descuento¶

Gestionar tarjetas de regalo¶

Calcular descuentos¶

Sistema de eventos¶

Suscribirse a eventos¶

Eventos disponibles¶

dcartAPI.Events.Discount.Calculated¶

dcartAPI.Events.Discount.Apply¶

dcartAPI.Events.Discount.Applied¶

dcartAPI.Events.Discount.Removed¶

Ejemplo completo de integración de eventos¶

Gestión de errores¶

Buenas prácticas¶

Consideraciones de rendimiento¶

Experiencia de usuario¶

Pautas de integración¶

Casos de uso habituales¶

Aplicar descuentos desde la URL automáticamente¶

Integración de cuenta atrás promocional¶

Integración de pruebas A/B¶

Referencia de la API¶

Métodos¶

apply(codes: string | string[]): Promise¶

remove(code?: string): Promise¶

removeGiftCard(id: string): Promise¶

calculate(codes: string[], items: any[]): Promise¶

setCustomConfig(config: Record): void¶

cloneAndInjectInfo(targetSelector: string): void¶

Eventos¶

Solución de problemas¶

Problemas habituales¶

`dcartAPI.Events.Discount.Calculated`¶

`dcartAPI.Events.Discount.Apply`¶

`dcartAPI.Events.Discount.Applied`¶

`dcartAPI.Events.Discount.Removed`¶

`apply(codes: string | string[]): Promise`¶

`remove(code?: string): Promise`¶

`removeGiftCard(id: string): Promise`¶

`calculate(codes: string[], items: any[]): Promise`¶

`setCustomConfig(config: Record): void`¶

`cloneAndInjectInfo(targetSelector: string): void`¶