Dcart API

Übersicht

Die Discount API bietet ein umfassendes System zur Verwaltung von Rabattcodes und Geschenkgutscheinen in Ihrem Shopify-Shop. Mit dieser API können Sie Rabatte programmatisch anwenden, Ersparnisse berechnen und Rabattfunktionen in Ihren Storefront integrieren.

Erste Schritte

Grundeinrichtung

Die Discount API wird automatisch initialisiert, sobald Ihre App geladen wird. Sie können sie sofort über das globale Objekt dcartAPI verwenden.

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

Kernfunktionen

Rabattcodes anwenden

Verwenden Sie die Methode apply(), um Rabattcodes für Kunden zu aktivieren.

Einen einzelnen Rabattcode anwenden:

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

Mehrere Rabattcodes anwenden:

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

Hinweis: Rabattcodes werden automatisch in Kleinbuchstaben umgewandelt und von Leerzeichen am Anfang und Ende befreit.

Rabattcodes entfernen

Entfernen Sie aktive Rabattcodes mit der Methode remove().

Einen bestimmten Rabattcode entfernen:

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

Alle aktiven Rabattcodes entfernen:

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

Geschenkgutscheine verwalten

Entfernen Sie angewendete Geschenkgutscheine über ihre eindeutige Kennung.

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

Rabatte berechnen

Zeigen Sie Rabattberechnungen an, ohne sie auf den Warenkorb anzuwenden.

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

Ereignissystem

Die Discount API bietet ein umfassendes Ereignissystem, mit dem Sie Rabattaktivitäten verfolgen und in Ihren eigenen Code einbinden.

Auf Ereignisse reagieren

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

Verfügbare Ereignisse

dcartAPI.Events.Discount.Calculated

Wird ausgelöst, wenn Rabattberechnungen abgeschlossen oder neu berechnet wurden.

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

Anwendungsfälle:

• Eigene Gesamtbeträge anzeigen
• Warenkorb-Zusammenfassungen aktualisieren
• Analyse-Ereignisse auslösen

dcartAPI.Events.Discount.Apply

Wird ausgelöst, wenn die Schaltfläche „Anwenden“ geklickt wird, bevor der Rabatt verarbeitet wird.

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

Anwendungsfälle:

• Ladezustände anzeigen
• Rabattcodes vor dem Absenden prüfen
• Nutzerinteraktionen verfolgen

dcartAPI.Events.Discount.Applied

Wird ausgelöst, wenn ein Rabattcode erfolgreich auf den Warenkorb angewendet wurde.

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

Anwendungsfälle:

• Erfolgsmeldungen anzeigen
• Warenkorbanzeigen aktualisieren
• Erfolgreiche Rabattanwendungen verfolgen
• Aktionsabläufe auslösen

dcartAPI.Events.Discount.Removed

Wird ausgelöst, wenn ein Rabattcode aus dem Warenkorb entfernt wird.

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

Anwendungsfälle:

• Warenkorbanzeigen aktualisieren
• Werbebotschaften entfernen
• Entfernte Rabatte verfolgen
• Aktionsstatus zurücksetzen

Vollständiges Beispiel zur Ereignisintegration

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

Fehlerbehandlung

Implementieren Sie für Rabattvorgänge immer eine saubere Fehlerbehandlung:

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

Empfehlungen für die Praxis

Leistung

• Stapelvorgänge: Wenn Sie mehrere Codes anwenden, verwenden Sie einen einzelnen Aufruf von apply() mit einem Array
• Ereignis-Drosselung: Entprellen Sie schnelle Rabattberechnungen, um Leistungsprobleme zu vermeiden
• Fehlerwiederherstellung: Implementieren Sie eine Wiederholungslogik für Netzwerkfehler

Nutzererlebnis

• Ladezustände: Zeigen Sie bei Rabattvorgängen immer Ladeindikatoren an
• Klares Feedback: Geben Sie sofort Rückmeldung, wenn Rabatte angewendet oder entfernt werden
• Validierung: Prüfen Sie Rabattcodes möglichst clientseitig, um Anfragen an den Server zu reduzieren

Integrationsrichtlinien

• Reihenfolge der Ereignisse: Abonnieren Sie Ereignisse erst, nachdem die API initialisiert wurde
• Speicherverwaltung: Beenden Sie das Abonnement von Ereignissen, wenn Komponenten entfernt werden
• Ausweichlösungen: Implementieren Sie Ausweichlösungen für den Fall, dass die API nicht verfügbar ist

Häufige Anwendungsfälle

Rabatte aus der URL automatisch anwenden

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

Integration eines Aktions-Countdowns

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

Integration in A/B-Tests

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

API-Referenz

Methoden

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

Wendet einen oder mehrere Rabattcodes auf den Warenkorb an.

Parameter:

• codes: Ein einzelner Rabattcode als String oder ein Array von Rabattcodes

Rückgabe: Promise, das aufgelöst wird, wenn die Codes angewendet wurden

remove(code?: string): Promise

Entfernt einen bestimmten Rabattcode oder alle Codes, wenn kein Code angegeben ist.

Parameter:

• code (optional): Der zu entfernende Rabattcode. Ohne Angabe werden alle Codes entfernt

Rückgabe: Promise, das aufgelöst wird, wenn die Codes entfernt wurden

removeGiftCard(id: string): Promise

Entfernt einen Geschenkgutschein aus dem Warenkorb.

Parameter:

• id: Die ID des zu entfernenden Geschenkgutscheins

Rückgabe: Promise, das aufgelöst wird, wenn der Geschenkgutschein entfernt wurde

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

Berechnet Rabattbeträge, ohne sie anzuwenden.

Parameter:

• codes: Array der zu berechnenden Rabattcodes
• items: Array der Warenkorbartikel, für die berechnet wird

Rückgabe: Promise, das mit den Rabattberechnungsdaten aufgelöst wird

setCustomConfig(config: Record): void

Legt eigene Konfigurationsoptionen fest.

Parameter:

• config: Konfigurationsobjekt mit eigenen Einstellungen

cloneAndInjectInfo(targetSelector: string): void

Kopiert Rabattinformationen in ein Zielelement.

Parameter:

• targetSelector: CSS-Selektor für das Zielelement

Ereignisse

Ereignis	Beschreibung
Discount.Calculated	Rabattberechnungen abgeschlossen
Discount.Apply	Schaltfläche „Anwenden“ geklickt
Discount.Applied	Rabatt erfolgreich angewendet
Discount.Removed	Rabatt aus dem Warenkorb entfernt

Fehlerbehebung

Häufige Probleme

Rabatte werden nicht angewendet

• Prüfen Sie, ob der Rabattcode gültig und aktiv ist
• Prüfen Sie, ob der Warenkorb die Mindestanforderungen erfüllt
• Stellen Sie sicher, dass die API korrekt initialisiert ist

Ereignisse werden nicht ausgelöst

• Vergewissern Sie sich, dass die Ereignisabonnements nach der Initialisierung der API erfolgen
• Prüfen Sie die Konsole auf JavaScript-Fehler
• Prüfen Sie, ob die Ereignisnamen korrekt geschrieben sind

Summen werden nicht aktualisiert

• Prüfen Sie, ob die Summen-Selektoren richtig konfiguriert sind
• Prüfen Sie, ob die eigene Konfiguration keine nötigen Elemente ausschließt
• Stellen Sie sicher, dass die Seitenelemente vorhanden sind, wenn die Summen berechnet werden

---

Brauchen Sie Hilfe? Schreiben Sie an support@syncu.be.