Skip to main content

​
Visão geral

Aqui estão as respostas para algumas das dúvidas mais comuns sobre o uso da API do Upcart.

​
Onde adicionar os scripts da API do Upcart?

Você pode adicionar scripts nas configurações de Custom HTML do Upcart ou diretamente no código do seu tema da Shopify. A melhor opção depende das suas necessidades de personalização.

​
Como uso o Custom HTML do Upcart?

  1. Acesse Upcart → Settings → Custom HTML
  2. Use scripts de API para modificar o comportamento do carrinho, como o momento de abertura ou a exibição de upsells
  3. Ajuste elementos fora do Upcart, como ocultar botões da página de produto

​
💡 Exemplo: ocultar o botão fixo do carrinho quando o carrinho está vazio

Nota sobre versões antigas: os callbacks window.upcartOnCartLoaded ainda funcionam, mas estão obsoletos e registram avisos no console. Use upcartSubscribeCartLoaded em todos os scripts novos. Observe que event.cart não tem uma propriedade item_count — use event.cart.items.reduce((total, item) => total + item.quantity, 0) para calcular o total de itens.

​
Preciso ser desenvolvedor para usar a API do Upcart?

Não! A API do Upcart é fácil de usar, mesmo sem conhecimentos de programação. Muitos recursos são integrados, e nossa documentação de personalização inclui scripts prontos que você pode copiar para as configurações de Custom HTML do Upcart — sem precisar programar! Se quiser escrever scripts personalizados, conhecimentos básicos de JavaScript ajudam. Se você é iniciante em JavaScript, não se preocupe! Estes recursos para iniciantes — W3Schools e MDN Web Docs — podem ajudar você a começar.

​
A API do Upcart pode se integrar a outros apps de terceiros?

Sim! A API do Upcart funciona com apps de tradução, análise, upsells e muito mais. Alguns se integram automaticamente, enquanto outros podem precisar de um pequeno script. Por exemplo, se você usa o TripleWhale para rastreamento, você precisará adicionar o seguinte script para garantir que ele registre corretamente a atividade do carrinho:
Nota sobre versões antigas: os callbacks window.upcartOnAddToCart ainda funcionam, mas estão obsoletos e registram avisos no console. Use upcartSubscribeAddedToCart em todos os scripts novos. Observe que as propriedades do evento estão em event.item (com variantId e quantityAdded), e não são passadas como parâmetros separados.
Como cada app é diferente, consulte a equipe de suporte do seu app para saber se é necessário código adicional. O Upcart não oferece suporte a scripts de apps de terceiros, mas seu fornecedor de app pode ter um guia de integração.

​
Como testo se minhas alterações na API estão funcionando?

Depois de adicionar um script nas configurações de Custom HTML do Upcart, siga estas etapas para garantir que ele funcione:
  1. Atualize sua loja e adicione um item ao carrinho.
  2. Limpe o cache e tente novamente para ver as alterações mais recentes.
  3. Adicione uma mensagem de teste: insira console.log("The script works!"); antes de </script> para verificar se o script é executado.
  4. Verifique o console do navegador:
    • Abra as Dev Tools (F12 ou Ctrl + Shift + J no Windows, Cmd + Option + J no Mac).
    • Vá à aba Console e procure por “The script works!”
    • Se você vir a mensagem, seu script está rodando! Caso contrário, o script pode não estar sendo executado corretamente.
  5. Teste diferentes ações (por exemplo, remover um item) para garantir o comportamento esperado.
Solucione problemas verificando erros de digitação ou erros no console e ajustando o código conforme necessário.

​
O que devo fazer se um script da API não estiver funcionando?

Se o seu script de API não está funcionando, tente estas etapas de solução de problemas:
  • Verifique erros de digitação – Mesmo erros pequenos podem quebrar um script. Procure caracteres faltando ou sintaxe incorreta.
  • Verifique a posição do script – Certifique-se de que o script está na seção correta em Upcart → Settings → Custom HTML. O Upcart tem dez seções de script (nove pontos de injeção de HTML mais uma seção de Scripts before load) — Confira essas seções aqui.
  • Verifique o console do navegador – Siga as etapas acima para procurar erros.
  • Teste um script diferente – Experimente outro script pronto da API do Upcart para ver se o problema é com o seu código.
  • Ainda travado? – Se você está modificando seu tema da Shopify ou integrando apps de terceiros, um Shopify Expert do Shopify Partner Directory pode ajudar.
Essas etapas devem ajudar você a identificar e resolver a maioria dos problemas com scripts!

​
Como desfaço as alterações se eu adicionar um script que quebra algo?

Se você adicionar um script que não funciona como esperado, pode removê-lo ou desativá-lo facilmente:
  • Acesse as configurações de Custom HTML do Upcart onde o script foi adicionado.
  • Remova o script ou desative-o temporariamente adicionando // no início de cada linha (isso o transforma em comentário, impedindo sua execução).
  • Salve as alterações e atualize sua loja para verificar se o problema foi resolvido.
Se o problema persistir, tente limpar o cache ou reverter alterações recentes no tema — isso costuma resolver conflitos ocultos.
🚧 Procurando personalizações avançadas? Precisa de personalizações em toda a loja ou de integrações com apps de terceiros? Talvez seja necessário um desenvolvedor para adicionar a API do Upcart ao seu tema da Shopify. Considere contratar um Shopify Expert pelo Shopify Partner Directory e compartilhe nossa documentação da API com ele para obter ajuda