API Dcart

Présentation

L'API de réduction fournit un système complet de gestion des codes de réduction et des cartes-cadeaux dans votre boutique Shopify. Cette API vous permet d'appliquer des réductions par programme, de calculer les économies et d'intégrer la fonctionnalité de réduction à votre boutique en ligne.

Mise en route

Configuration de base

L'API de réduction s'initialise automatiquement au chargement de l'application. Vous pouvez l'utiliser immédiatement via l'objet 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');
});

Fonctionnalités principales

Appliquer des codes de réduction

Utilisez la méthode apply() pour activer des codes de réduction pour les clients.

Appliquer un seul code de réduction :

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

Appliquer plusieurs codes de réduction :

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

Remarque : les codes de réduction sont automatiquement convertis en minuscules et débarrassés de leurs espaces superflus.

Supprimer des codes de réduction

Supprimez les codes de réduction actifs avec la méthode remove().

Supprimer un code de réduction précis :

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

Supprimer tous les codes de réduction actifs :

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

Gérer les cartes-cadeaux

Supprimez les cartes-cadeaux appliquées à l'aide de leur identifiant unique.

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

Calculer les réductions

Prévisualisez les calculs de réduction sans les appliquer au panier.

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
  });

Système d'événements

L'API de réduction fournit un système d'événements complet pour suivre les actions liées aux réductions et les intégrer à votre code personnalisé.

S'abonner aux événements

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);
  });
});

Événements disponibles

dcartAPI.Events.Discount.Calculated

Déclenché lorsque les calculs de réduction sont terminés ou recalculés.

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

Cas d'usage :

• Mettre à jour vos affichages de totaux personnalisés
• Actualiser les récapitulatifs du panier
• Déclencher des événements d'analyse

dcartAPI.Events.Discount.Apply

Déclenché lorsque le bouton d'application est cliqué, avant le traitement de la réduction.

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

Cas d'usage :

• Afficher des états de chargement
• Valider les codes de réduction avant l'envoi
• Suivre les interactions des utilisateurs

dcartAPI.Events.Discount.Applied

Déclenché lorsqu'un code de réduction est appliqué avec succès au panier.

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 });
});

Cas d'usage :

• Afficher des messages de réussite
• Mettre à jour les affichages du panier
• Suivre les applications de réduction réussies
• Déclencher des workflows promotionnels

dcartAPI.Events.Discount.Removed

Déclenché lorsqu'un code de réduction est retiré du panier.

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

Cas d'usage :

• Mettre à jour les affichages du panier
• Retirer les messages promotionnels
• Suivre les suppressions de réduction
• Réinitialiser les états promotionnels

Exemple complet d'intégration des événements

(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 = '';
});
  });
})();

Gestion des erreurs

Prévoyez toujours une gestion d'erreurs pour les opérations de réduction :

// 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.');
    }
});

Bonnes pratiques

Performance

• Opérations groupées : pour appliquer plusieurs codes, utilisez un seul appel apply() avec un tableau
• Limitation des événements : appliquez un délai (debounce) aux calculs de réduction rapprochés pour éviter les problèmes de performance
• Reprise sur erreur : prévoyez une logique de nouvelle tentative en cas d'échec réseau

Expérience utilisateur

• États de chargement : affichez toujours un indicateur de chargement pendant les opérations de réduction
• Retour clair : indiquez immédiatement si une réduction est appliquée ou supprimée
• Validation : validez les codes de réduction côté client lorsque c'est possible, pour limiter les requêtes serveur

Recommandations d'intégration

• Ordre des événements : abonnez-vous aux événements après l'initialisation de l'API
• Gestion de la mémoire : désabonnez-vous des événements lorsque les composants sont détruits
• Solutions de repli : prévoyez des solutions de repli pour les cas où l'API est indisponible

Cas d'usage courants

Appliquer automatiquement les réductions de l'URL

// 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);
  });
}

Intégrer un compte à rebours promotionnel

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

Intégrer des tests 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
  });
});

Référence de l'API

Méthodes

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

Applique un ou plusieurs codes de réduction au panier.

Paramètres :

• codes : une chaîne de code de réduction ou un tableau de codes de réduction

Retour : une promesse qui se résout lorsque les codes sont appliqués

remove(code?: string): Promise

Supprime un code de réduction précis, ou tous les codes si aucun code n'est indiqué.

Paramètres :

• code (facultatif) : le code de réduction à supprimer. S'il est omis, tous les codes sont supprimés

Retour : une promesse qui se résout lorsque le ou les codes sont supprimés

removeGiftCard(id: string): Promise

Retire une carte-cadeau du panier.

Paramètres :

• id : l'identifiant de la carte-cadeau à retirer

Retour : une promesse qui se résout lorsque la carte-cadeau est retirée

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

Calcule les montants de réduction sans les appliquer.

Paramètres :

• codes : tableau des codes de réduction à calculer
• items : tableau des articles du panier sur lesquels effectuer le calcul

Retour : une promesse qui se résout avec les données de calcul de la réduction

setCustomConfig(config: Record): void

Définit des options de configuration personnalisées.

Paramètres :

• config : objet de configuration avec vos réglages personnalisés

cloneAndInjectInfo(targetSelector: string): void

Copie les informations de réduction vers un élément cible.

Paramètres :

• targetSelector : sélecteur CSS de l'élément cible

Événements

Événement	Description
Discount.Calculated	Calculs de réduction terminés
Discount.Apply	Bouton d'application cliqué
Discount.Applied	Réduction appliquée avec succès
Discount.Removed	Réduction retirée du panier

Dépannage

Problèmes courants

Les réductions ne s'appliquent pas

• Vérifiez que le code de réduction est valide et actif
• Vérifiez que le panier respecte les montants minimums requis
• Vérifiez que l'API est correctement initialisée

Les événements ne se déclenchent pas

• Vérifiez que les abonnements aux événements sont effectués après l'initialisation de l'API
• Recherchez les erreurs JavaScript dans la console
• Vérifiez que les noms des événements sont bien orthographiés

Les totaux ne se mettent pas à jour

• Vérifiez que les sélecteurs de totaux sont correctement configurés
• Vérifiez que la configuration personnalisée n'exclut pas les éléments nécessaires
• Vérifiez que les éléments de la page existent lorsque les totaux sont calculés

---

Besoin d'aide ? Écrivez à support@syncu.be.