API do Dcart

Visão geral

A API de descontos oferece um sistema completo para gerenciar códigos de desconto e cartões-presente na sua loja Shopify. Esta API permite aplicar descontos por programação, calcular economias e integrar a funcionalidade de descontos à sua loja virtual.

Primeiros passos

Configuração básica

A API de descontos é inicializada automaticamente quando o seu app carrega. Você pode começar a usá-la imediatamente pelo 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');
});

Funcionalidades principais

Aplicando códigos de desconto

Use o método apply() para ativar códigos de desconto para os clientes.

Aplique um único código de desconto:

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

Aplique vários códigos de desconto:

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

Observação: os códigos de desconto são convertidos automaticamente para minúsculas e os espaços no início e no fim são removidos.

Removendo códigos de desconto

Remova códigos de desconto ativos usando o método remove().

Remova um código de desconto específico:

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

Remova todos os códigos de desconto ativos:

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

Gerenciando cartões-presente

Remova cartões-presente aplicados usando o identificador único de cada um.

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

Calculando descontos

Visualize os cálculos de desconto sem aplicá-los ao carrinho.

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

A API de descontos oferece um sistema completo de eventos para acompanhar as atividades de desconto e integrar com o seu código personalizado.

Assinando 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 disponíveis

dcartAPI.Events.Discount.Calculated

Disparado quando os cálculos de desconto são concluídos ou recalculados.

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

Casos de uso:

• Atualizar exibições de totais personalizadas
• Atualizar resumos do carrinho
• Disparar eventos de analytics

dcartAPI.Events.Discount.Apply

Disparado quando o botão de aplicar é clicado, antes de o desconto ser processado.

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 carregamento
• Validar códigos de desconto antes do envio
• Acompanhar as interações do usuário

dcartAPI.Events.Discount.Applied

Disparado quando um código de desconto é aplicado com sucesso ao carrinho.

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:

• Exibir mensagens de sucesso
• Atualizar as exibições do carrinho
• Acompanhar aplicações de desconto bem-sucedidas
• Disparar fluxos de trabalho promocionais

dcartAPI.Events.Discount.Removed

Disparado quando um código de desconto é removido do carrinho.

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:

• Atualizar as exibições do carrinho
• Remover mensagens promocionais
• Acompanhar remoções de desconto
• Redefinir estados promocionais

Exemplo completo de integração 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 = '';
});
  });
})();

Tratamento de erros

Sempre implemente um tratamento de erros adequado para as operações de desconto:

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

Boas práticas

Considerações de desempenho

• Operações em lote : ao aplicar vários códigos, use uma única chamada apply() com um array
• Limitação de eventos : aplique debounce em cálculos de desconto repetidos para evitar problemas de desempenho
• Recuperação de erros : implemente lógica de nova tentativa para falhas de rede

Experiência do usuário

• Estados de carregamento : sempre mostre indicadores de carregamento durante as operações de desconto
• Feedback claro : forneça feedback imediato quando descontos forem aplicados ou removidos
• Validação : valide os códigos de desconto no lado do cliente quando possível, para reduzir requisições ao servidor

Diretrizes de integração

• Ordem dos eventos : assine os eventos depois que a API for inicializada
• Gerenciamento de memória : cancele a assinatura dos eventos quando os componentes forem destruídos
• Alternativas (fallback) : implemente alternativas para quando a API estiver indisponível

Casos de uso comuns

Aplicando descontos de URL automaticamente

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

Integração de contagem regressiva promocional

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

Integração de testes 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
  });
});

Referência da API

Métodos

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

Aplica um ou mais códigos de desconto ao carrinho.

Parâmetros:

• codes: uma string com um único código de desconto ou um array de códigos de desconto

Retorna: Promise que é resolvida quando os códigos são aplicados

remove(code?: string): Promise

Remove um código de desconto específico ou todos os códigos, se nenhum for informado.

Parâmetros:

• code (opcional): o código de desconto a remover. Se omitido, remove todos os códigos

Retorna: Promise que é resolvida quando o(s) código(s) são removidos

removeGiftCard(id: string): Promise

Remove um cartão-presente do carrinho.

Parâmetros:

• id: o ID do cartão-presente a remover

Retorna: Promise que é resolvida quando o cartão-presente é removido

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

Calcula os valores de desconto sem aplicá-los.

Parâmetros:

• codes: array de códigos de desconto a calcular
• items: array de itens do carrinho para o cálculo

Retorna: Promise que é resolvida com os dados do cálculo de desconto

setCustomConfig(config: Record): void

Define opções de configuração personalizadas.

Parâmetros:

• config: objeto de configuração com as configurações personalizadas

cloneAndInjectInfo(targetSelector: string): void

Clona as informações de desconto para um elemento de destino.

Parâmetros:

• targetSelector: seletor CSS do elemento de destino

Eventos

Evento	Descrição
Discount.Calculated	Cálculos de desconto concluídos
Discount.Apply	Botão de aplicar clicado
Discount.Applied	Desconto aplicado com sucesso
Discount.Removed	Desconto removido do carrinho

Solução de problemas

Problemas comuns

Descontos não são aplicados

• Verifique se o código de desconto é válido e está ativo
• Confira se o carrinho atende aos requisitos mínimos
• Certifique-se de que a API foi inicializada corretamente

Eventos não disparam

• Confirme que as assinaturas de eventos acontecem depois da inicialização da API
• Verifique se há erros de JavaScript no console
• Confirme se os nomes dos eventos estão escritos corretamente

Totais não são atualizados

• Verifique se os seletores de total estão configurados corretamente
• Confirme que a configuração personalizada não exclui elementos necessários
• Certifique-se de que os elementos da página existem quando os totais são calculados

---

Precisa de ajuda? Escreva para support@syncu.be.