> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usos comuns da API do Upcart

> Aprenda a colocar a API pública do Upcart para trabalhar com exemplos práticos para copiar e colar.

<div id="how-the-api-pattern-works">
  ## Como funciona o padrão da API
</div>

A maioria dos scripts da API do Upcart segue o mesmo padrão simples:

Escutar um evento do carrinho → Verificar uma condição → Executar uma ação

Por exemplo: "Quando o carrinho carregar → verificar se está vazio → ocultar o botão fixo."

💡 **Novo em APIs?** Comece com [O que é uma API?](/pt/upcart/what_is_an_api) antes de mergulhar nos exemplos abaixo.

***

<div id="where-to-add-your-scripts">
  ## Onde adicionar seus scripts
</div>

Todos os scripts abaixo vão em:

**Cart Editor → Settings → Custom HTML → Scripts (before load)**

Envolva cada snippet em tags `<script>...</script>` e salve. Para testar, abra o console das Ferramentas do Desenvolvedor do seu navegador (`F12`) e procure por mensagens de `console.log`.

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## Uma nota sobre callbacks legados vs. modernos
</div>

O Upcart tem duas maneiras de escutar eventos do carrinho:

| Estilo                | Exemplo                          | Status                                    |
| --------------------- | -------------------------------- | ----------------------------------------- |
| Moderno (recomendado) | `upcartSubscribeAddedToCart(fn)` | Atual                                     |
| Legado (obsoleto)     | `upcartOnAddToCart = fn`         | Ainda funciona, registra aviso no console |

Todos os exemplos abaixo usam a API moderna. Scripts existentes que usam o estilo antigo continuarão funcionando.

***

<div id="example-1-hide-the-sticky-cart-button-when-the-cart-is-empty">
  ## Exemplo 1: ocultar o botão de carrinho fixo quando o carrinho está vazio
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>
```

**Como funciona:** `upcartSubscribeCartLoaded` dispara toda vez que o carrinho é carregado. O callback recebe um `event` com um objeto `cart` contendo um array `items`. Somamos a `quantity` de cada item para determinar se o carrinho está vazio.

⚠️ **IMPORTANTE:** `event.cart` NÃO tem uma propriedade `item_count`. Você deve calcular o total iterando por `event.cart.items`.

***

<div id="example-2-log-when-an-item-is-added-to-the-cart">
  ## Exemplo 2: registrar quando um item é adicionado ao carrinho
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>
```

**Propriedades disponíveis em `event.item`:**

| Propriedade                | Descrição                                     |
| -------------------------- | --------------------------------------------- |
| `event.item.title`         | Título do produto                             |
| `event.item.quantityAdded` | Número de unidades adicionadas nesta ação     |
| `event.item.quantity`      | Quantidade total deste item agora no carrinho |
| `event.item.variantId`     | ID da variante na Shopify                     |
| `event.item.handle`        | Handle do produto                             |
| `event.item.productId`     | ID do produto na Shopify                      |
| `event.item.finalPrice`    | Preço final após descontos                    |
| `event.item.image`         | URL da imagem do produto                      |

***

<div id="example-3-integrate-with-a-third-party-analytics-app-eg-triplewhale">
  ## Exemplo 3: integrar com um app de analytics de terceiros (por exemplo, TripleWhale)
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>
```

> **Nota:** cada app de terceiros é diferente. Verifique com a equipe de suporte do seu app o formato de evento correto.

***

<div id="example-4-open-the-cart-automatically-after-a-product-is-added">
  ## Exemplo 4: abrir o carrinho automaticamente depois que um produto é adicionado
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>
```

> **Nota:** se "Open cart drawer on add to cart" já estiver ativado em **Cart Editor → Settings → Cart settings**, você não precisa deste script.

***

<div id="quick-reference-subscribe-functions-modern-api">
  ## Referência rápida: funções de subscribe (API moderna)
</div>

| Função                                                 | Quando dispara                          | O callback recebe                                                                                    |
| ------------------------------------------------------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `upcartSubscribeCartLoaded(fn)`                        | Os dados do carrinho carregam           | `{ cart }` - cart tem `.items[]`, `.total`, `.currency`                                              |
| `upcartSubscribeAddedToCart(fn)`                       | Item adicionado ao carrinho             | `{ item }` - item tem `.title`, `.variantId`, `.quantityAdded`, `.quantity`                          |
| `upcartSubscribeCartOpened(fn)`                        | O cart drawer abre                      | `{}` (objeto vazio)                                                                                  |
| `upcartSubscribeCartClosed(fn)`                        | O cart drawer fecha                     | `{}` (objeto vazio)                                                                                  |
| `upcartSubscribeCartUpdated(fn)`                       | O conteúdo do carrinho muda             | `{ cart }`                                                                                           |
| `upcartSubscribeItemRemoved(fn)`                       | Item removido                           | `{ item }`                                                                                           |
| `upcartSubscribeCheckoutClicked(fn)`                   | Botão de checkout clicado               | `{ event }` - MouseEvent do navegador                                                                |
| `upcartSubscribeUpsellsAddedToCart(fn)`                | Item de upsell adicionado               | `{ variant }` - tem `.id` e `.title`                                                                 |
| `upcartSubscribeUpsellsRendered(fn)`                   | Os upsells são renderizados no carrinho | `{ item, element }` - item é o produto, element é o nó do DOM                                        |
| `upcartSubscribeNotesTextChanged(fn)`                  | As notas do carrinho são atualizadas    | `{ newNotesText, oldNotesText }` - a nova string de notas e a anterior                               |
| `upcartSubscribeRewardsMilestonesCompletedChanged(fn)` | O status de um marco de recompensa muda | `{ numOfMilestonesCompleted, status }` - `status` é `"promotion"`, `"demotion"` ou `"initial-state"` |

***

<div id="direct-action-functions">
  ## Funções de ação direta
</div>

| Função                             | O que ela faz                                                             |
| ---------------------------------- | ------------------------------------------------------------------------- |
| `window.upcartOpenCart()`          | Abre o cart drawer                                                        |
| `window.upcartCloseCart()`         | Fecha o cart drawer                                                       |
| `window.upcartRefreshCart()`       | Atualiza os dados do carrinho                                             |
| `window.upcartGetCart()`           | Retorna o objeto atual do carrinho                                        |
| `window.upcartRegisterAddToCart()` | Registra o add-to-cart para construtores de páginas (Replo, PageFly etc.) |
| `window.upcartFormatMoney()`       | Formata um preço usando o formato de moeda da sua loja                    |

Para a documentação completa da API, veja a [documentação da API pública do Upcart](https://rokt.notion.site/upcart-public-api).

***

<div id="troubleshooting">
  ## Solução de problemas
</div>

* **O script não está rodando?** Verifique novamente o posicionamento: ele deve estar em *Scripts (before load)*, não em after load.
* **Elemento não encontrado?** Certifique-se de que o seletor (por exemplo, `#upCartStickyButton`) corresponde ao ID real do elemento no seu carrinho.
* **Algo quebrou?** Comente seu script adicionando `//` no início de cada linha, salve e recarregue.
* **Ainda travado?** Veja o [FAQ da API](/pt/upcart/upcart_api_frequently_asked_questions) para mais etapas de solução de problemas.