> ## 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.

# Ações

> Todas as ações do SDK do Aftersell Cart para ler e alterar o carrinho: abrir, fechar, adicionar, remover, atualizar quantidade, trocar variante, ler estado e formatar valores.

Ações **leem e alteram o carrinho**. Elas ficam em `window.aftersell.cart.actions`.

<Note>
  Ações são executadas **depois que o carrinho está pronto**, dentro de `ready()` ou de um handler de [evento](/pt/aftersell/cart/sdk-events).
</Note>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});
```

<Note>
  **Antes de o carrinho carregar, as ações são stubs.** Cada uma registra um aviso no console nomeando a ação, por exemplo `cart.actions.addItem() called before the cart loaded`, e não faz nada. As ações assíncronas ainda resolvem uma Promise, então uma cadeia `.then()` roda normalmente em vez de lançar um erro; `getCart()` retorna `null` e `formatMoney()` retorna uma string vazia.

  Nada quebra se você chamar uma cedo demais, mas nada acontece também. Fique de olho no console procurando esse aviso quando uma ação parecer não fazer nada.
</Note>

<div id="every-action">
  ## Todas as ações
</div>

| Ação                                                     | Assinatura                           | Retorna                 | O que faz                         |
| -------------------------------------------------------- | ------------------------------------ | ----------------------- | --------------------------------- |
| [`open`](#open-and-close)                                | `open()`                             | Nada                    | Abre o drawer.                    |
| [`close`](#open-and-close)                               | `close()`                            | Nada                    | Fecha o drawer.                   |
| [`getCart`](#getcart)                                    | `getCart()`                          | `AftersellCart \| null` | Lê o carrinho atual.              |
| [`formatMoney`](#formatmoneycents)                       | `formatMoney(cents)`                 | `string`                | Formata um valor para exibição.   |
| [`addItem`](#additemvariantid-quantity)                  | `addItem(variantId, quantity?)`      | `Promise`               | Adiciona uma variante.            |
| [`removeItem`](#removeitemkey)                           | `removeItem(key)`                    | `Promise`               | Remove uma linha.                 |
| [`updateItemQuantity`](#updateitemquantitykey-quantity)  | `updateItemQuantity(key, quantity)`  | `Promise`               | Define a quantidade de uma linha. |
| [`replaceLineVariant`](#replacelinevariantkey-variantid) | `replaceLineVariant(key, variantId)` | `Promise`               | Troca a variante de uma linha.    |
| [`refresh`](#refresh)                                    | `refresh()`                          | `Promise`               | Rebusca o carrinho no Shopify.    |
| [`visualRefresh`](#visualrefresh)                        | `visualRefresh()`                    | Nada                    | Repinta sem rebuscar.             |

<Warning>
  Chamar uma ação de dentro de um handler de `cart_updated` pode criar um loop. Leia [as duas regras](/pt/aftersell/cart/sdk-events#the-two-rules) primeiro.
</Warning>

***

<div id="drawer">
  ## Drawer
</div>

<div id="open-and-close">
  ### open e close
</div>

Abrem ou fecham o cart drawer. Ambas são síncronas e não recebem argumentos.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Open the drawer from your own cart link.
document.querySelector('#my-cart-link').addEventListener('click', (event) => {
  event.preventDefault();
  window.aftersell.cart.actions.open();
});
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Close it after the shopper does something in a custom block.
window.aftersell.cart.actions.close();
```

***

<div id="reading">
  ## Leitura
</div>

<div id="getcart">
  ### getCart()
</div>

Retorna o [objeto de carrinho](/pt/aftersell/cart/sdk-cart-object) atual, ou `null` antes de ele ter carregado. O resultado é uma **cópia**, então mutá-lo não altera o carrinho real.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  if (!state) return; // the initial load failed

  console.log(state.itemCount, 'items,', state.items.length, 'lines');
  console.log('Total:', window.aftersell.cart.actions.formatMoney(state.totalPrice));
});
```

Como é um snapshot, não guarde o resultado; leia-o de novo cada vez que precisar de dados atuais. Em um handler de evento você já tem o carrinho atualizado como payload, então `getCart()` é redundante ali.

<div id="formatmoneycents">
  ### formatMoney(cents)
</div>

Formata um valor em unidades menores usando o formato de moeda da sua loja. Todo preço no SDK está em centavos, então é assim que você transforma um deles em algo exibível.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.actions.formatMoney(5779);  // "$57.79"
window.aftersell.cart.actions.formatMoney(0);     // "$0.00"
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Show the cart total in your own header element.
window.aftersell.cart.events.on('cart_updated', (state) => {
  document.querySelector('#header-total').textContent =
    window.aftersell.cart.actions.formatMoney(state.totalPrice);
});
```

Substitua o formato com [`configure({ money_format })`](/pt/aftersell/cart/sdk-configure#money_format).

***

<div id="changing-the-cart">
  ## Alterando o carrinho
</div>

<Note>
  As ações de item identificam uma linha pelo seu **`key`** do Shopify, não pelo ID da variante, porque um carrinho pode conter a mesma variante em várias linhas com propriedades diferentes. Leia-o em `getCart().items[n].key`.
</Note>

<div id="additemvariantid-quantity">
  ### addItem(variantId, quantity?)
</div>

Adiciona uma variante ao carrinho. `quantity` tem padrão `1`. Resolve quando o carrinho estabiliza.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Add one, then show the shopper.
window.aftersell.cart.actions.addItem(41720671830082).then(() => {
  window.aftersell.cart.actions.open();
});
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Add a specific quantity.
window.aftersell.cart.actions.addItem(41720671830082, 3);
```

Adicionar uma variante que já está no carrinho aumenta a quantidade daquela linha em vez de criar uma segunda linha, desde que a linha existente não tenha propriedades de item de linha. Uma linha com propriedades é uma linha distinta, então você recebe uma nova.

<div id="removeitemkey">
  ### removeItem(key)
</div>

Remove uma linha inteiramente.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Remove any free line from the cart.
const gift = window.aftersell.cart.actions
  .getCart()
  .items.find((line) => line.finalLinePrice === 0);
if (gift) window.aftersell.cart.actions.removeItem(gift.key);
```

<div id="updateitemquantitykey-quantity">
  ### updateItemQuantity(key, quantity)
</div>

Define a quantidade de uma linha. Passar `0` remove a linha.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const line = window.aftersell.cart.actions.getCart().items[0];
if (line) window.aftersell.cart.actions.updateItemQuantity(line.key, 3);
```

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Cap a line at one unit.
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items.forEach((line) => {
    if (line.variantId === LIMITED_VARIANT_ID && line.quantity > 1) {
      window.aftersell.cart.actions.updateItemQuantity(line.key, 1);
    }
  });
});
```

Esse segundo exemplo é seguro para rodar em `cart_updated` porque a verificação `> 1` é falsa na segunda passagem. Veja [as duas regras](/pt/aftersell/cart/sdk-events#the-two-rules).

<div id="replacelinevariantkey-variantid">
  ### replaceLineVariant(key, variantId)
</div>

Troca a variante de uma linha mantendo a quantidade e as propriedades. Útil para um seletor de tamanho ou sabor dentro do carrinho.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const line = window.aftersell.cart.actions.getCart().items[0];
window.aftersell.cart.actions.replaceLineVariant(line.key, 41720671862850);
```

<Warning>
  O **selling plan da linha é redefinido** em uma troca. Uma linha de assinatura vira uma compra única, a menos que você reaplique um plano.
</Warning>

A troca é uma adição seguida de uma remoção, não uma edição no lugar, então o resultado é uma **linha nova**: ela recebe um novo `key` e vai para o final do carrinho. Releia `getCart()` depois, em vez de reutilizar o key que você passou.

***

<div id="refreshing">
  ## Atualização
</div>

<div id="refresh">
  ### refresh()
</div>

Rebusca o carrinho no Shopify. Use-o depois que algo fora do SDK alterou o carrinho e o drawer não percebeu.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// After a raw Ajax API call of your own.
fetch('/cart/add.js', { method: 'POST', /* … */ })
  .then(() => window.aftersell.cart.actions.refresh())
  .then(() => { window.aftersell.cart.actions.open(); });
```

Na maior parte do tempo você não precisa disso, já que o Aftersell escuta os eventos padrão de carrinho do Shopify e rebusca sozinho. Recorra a ele quando uma integração personalizada passar por fora deles.

<div id="visualrefresh">
  ### visualRefresh()
</div>

Reexecuta os transforms de renderização sem rebuscar o carrinho no Shopify. Você raramente precisa dele: registrar (ou desregistrar) um [line transform](/pt/aftersell/cart/sdk-hooks#registerlinetransform), [comparator](/pt/aftersell/cart/sdk-hooks#registerlinecomparator), [enricher](/pt/aftersell/cart/sdk-hooks#registercartenricher) ou qualquer um dos [hooks de assinatura](/pt/aftersell/cart/sdk-hooks#registersubscriptionoptionstransform) dispara um para você. Apenas os dois hooks de adicionar ao carrinho não disparam, já que não mudam nada que já está na tela.

Recorra a ele quando algo de que um transform *depende* muda, mas o carrinho em si não:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// A currency switcher changed the format: repaint prices already on screen.
window.myTheme.onCurrencyChange((currency) => {
  window.aftersell.cart.configure({ money_format: FORMATS[currency] });
  window.aftersell.cart.actions.visualRefresh();
});
```

***

<div id="notes-and-edge-cases">
  ## Observações e casos extremos
</div>

* **Ações assíncronas resolvem quando a alteração estabiliza.** Aguardar uma delas permite sequenciar trabalho depois que o carrinho realmente foi atualizado.
* **`getCart()` retorna uma cópia.** Mutá-la não faz nada no carrinho real.
* **Não há ação para códigos de desconto.** Códigos aplicados são legíveis no carrinho (`discountCodes`, `totalDiscount`) e por linha (`discountAllocations`); os compradores os aplicam pelo bloco [Discount code](/pt/aftersell/cart/discount-code-block).
* **Não há ação para atributos ou notas do carrinho.** Atributos são legíveis no objeto de carrinho; os compradores escrevem notas pelo bloco [Notes](/pt/aftersell/cart/notes-block).
* **Para ocultar uma linha em vez de removê-la**, use [`registerLineTransform`](/pt/aftersell/cart/sdk-hooks#registerlinetransform). Remover altera o total do comprador; ocultar não.

<div id="where-to-go-next">
  ## Para onde ir agora
</div>

* **[Objeto de carrinho](/pt/aftersell/cart/sdk-cart-object)**: o que `getCart()` devolve.
* **[Eventos](/pt/aftersell/cart/sdk-events)**: quando executar essas ações.
* **[Hooks](/pt/aftersell/cart/sdk-hooks)**: mude como uma linha é renderizada em vez de mudar o carrinho.
* **[Casos de uso](/pt/aftersell/cart/sdk-use-cases)**: soluções completas para pedidos comuns.