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

# Visão geral

> Como funciona o Cart SDK da Aftersell: o ponto de entrada global, as quatro partes da API, quando ele carrega e como executar código com ele com segurança.

O **Cart SDK** é uma API JavaScript para o Aftersell Cart na sua loja. Ele permite mudar como o carrinho se comporta, reagir ao que os compradores fazem e ler ou alterar o conteúdo do carrinho a partir de código.

Você executa código do SDK por meio de [Scripts personalizados](/pt/aftersell/cart/custom-scripts), ou pelo modo React de um [bloco Custom code](/pt/aftersell/cart/custom-code-blocks) para um bloco que renderiza sua própria UI.

<Note>
  Muito do que os lojistas pedem ao SDK já é uma configuração. Antes de escrever um script, verifique se um [bloco do carrinho](/pt/aftersell/cart/blocks-overview), as [condições por mercado/país/moeda](/pt/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency) ou uma [configuração do carrinho](/pt/aftersell/cart/cart-settings) já fazem isso. Esses continuam funcionando após redesigns do carrinho, e seu script pode não continuar.
</Note>

<div id="the-global-entry-point">
  ## O ponto de entrada global
</div>

Tudo parte de um único global:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart
```

<Note>
  **Todo snippet destes docs escreve `window.aftersell.cart` por extenso**, então qualquer um deles funciona sozinho quando você o cola. Criar um alias uma vez (`const cart = window.aftersell.cart;`) e usar `cart` daí em diante também é perfeitamente válido, e seguro mesmo antes de o carrinho carregar. Só lembre de incluir essa linha se você encurtar um snippet, já que um `cart` solto por si só lança `cart is not defined`.
</Note>

Quatro partes fazem o trabalho:

<Columns cols={2}>
  <Card title="Configure" icon="sliders" href="/pt/aftersell/cart/sdk-configure">
    Defina como o carrinho se comporta: quando o drawer abre, como o dinheiro é formatado, se a Aftersell intercepta o adicionar ao carrinho.
  </Card>

  <Card title="Events" icon="tower-broadcast" href="/pt/aftersell/cart/sdk-events">
    Reaja ao que acontece: o carrinho carregou, um item foi adicionado, o drawer abriu, o checkout foi clicado.
  </Card>

  <Card title="Actions" icon="wand-magic-sparkles" href="/pt/aftersell/cart/sdk-actions">
    Leia e altere o carrinho: abra-o, adicione um item, atualize uma quantidade, leia o estado atual.
  </Card>

  <Card title="Hooks" icon="plug" href="/pt/aftersell/cart/sdk-hooks">
    Mude como o próprio carrinho funciona: oculte ou renomeie linhas, reordene-as, anexe dados extras, controle o adicionar ao carrinho.
  </Card>
</Columns>

<Note>
  Se um script seu parou de disparar no adicionar ao carrinho, comece por [Interceptação do adicionar ao carrinho](/pt/aftersell/cart/add-to-cart-interception). Ela explica por que o Aftersell assume a adição e todas as maneiras de isentar um formulário.
</Note>

Mais três membros menores:

| Membro       | Para que serve                                                              |
| ------------ | --------------------------------------------------------------------------- |
| `ready()`    | Uma Promise que resolve assim que o carrinho carregou pela primeira vez.    |
| `context`    | Contexto do comprador renderizado pelo servidor, legível de forma síncrona. |
| `shadowRoot` | O shadow root do carrinho, para consultar elementos dentro do drawer.       |

<div id="events-actions-or-hooks">
  ## Eventos, ações ou hooks?
</div>

Os três são fáceis de confundir, e escolher o errado é o motivo mais comum de um script não fazer o que seu autor esperava:

| Você quer…                                    | Use        | Exemplo                                                    |
| --------------------------------------------- | ---------- | ---------------------------------------------------------- |
| Executar código *quando algo acontece*        | **Evento** | Enviar um evento de analytics quando um item é adicionado. |
| *Mudar o que está* no carrinho                | **Ação**   | Adicionar um brinde quando o total passar de \$50.         |
| Mudar *como o carrinho funciona ou renderiza* | **Hook**   | Ocultar linhas de brinde no drawer.                        |

A distinção que mais importa: uma **ação altera o carrinho real do comprador** (e o total dele), enquanto um **hook só altera o que renderiza**. Ocultar uma linha com um hook a mantém no carrinho e no total; removê-la com uma ação a tira de verdade.

<div id="how-and-when-it-loads">
  ## Como e quando ele carrega
</div>

O carrinho carrega em dois estágios, e o SDK foi construído para que você não precise pensar em ordem:

1. Um pequeno **stub** cria `window.aftersell.cart` imediatamente, então ele está sempre lá.
2. O SDK completo carrega logo depois e assume, atualizando o stub no lugar, de modo que uma referência capturada antes continua funcionando.

Isso dá a você duas categorias de chamada:

<Columns cols={2}>
  <Card title="Chamadas de configuração: seguras imediatamente" icon="circle-check">
    `configure(...)`, `events.on(...)` e toda chamada `hooks.register*`. São armazenadas em buffer antes do boot e reproduzidas em ordem assim que o SDK carrega. Coloque-as no topo do seu script.
  </Card>

  <Card title="Ações: aguarde ready()" icon="clock">
    Tudo sob `actions.*`. Execute-as dentro de `ready()` ou de um handler de evento. Chamadas cedo demais, elas avisam no console e não fazem nada, com segurança: as assíncronas ainda resolvem, então uma cadeia `.then()` não quebra.
  </Card>
</Columns>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Set-up: fine at the top level, before the cart has loaded.
window.aftersell.cart.configure({ open_on_add_to_cart: 'always' });

window.aftersell.cart.events.on('item_added', (payload) => {
  console.log('Added', payload.item.title);
});

// Actions: wait until the cart is ready.
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});
```

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

`ready()` retorna uma Promise que resolve assim que o primeiro carregamento do carrinho **termina**. Ela resolve tanto em falha quanto em sucesso, então um comprador com conexão instável nunca deixa seu script travado. Verifique se `getCart()` é `null` em vez de presumir que um carrinho chegou.

Chamar `ready()` depois que o carrinho já carregou resolve imediatamente, então é seguro usá-la como um portão geral de "o carrinho existe agora" em qualquer lugar do seu código.

<Tip>
  Você não precisa de `ready()` dentro de um handler de evento. Quando `cart_loaded`, `cart_updated` ou `item_added` dispara, o carrinho está carregado e é seguro chamar ações.
</Tip>

<div id="context">
  ## context
</div>

`window.aftersell.cart.context` contém dados do comprador renderizados pelo servidor, legíveis de forma síncrona, sem precisar de `ready()`. Use-o para ramificações por mercado ou país que precisam acontecer antes de o carrinho carregar.

| Campo                     | Descrição                                                                            | Disponível antes do boot                          |
| ------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `shopify_market`          | O mercado Shopify do comprador.                                                      | Sim                                               |
| `customer_country`        | Código de país de duas letras.                                                       | Sim                                               |
| `customer_currency`       | Código da moeda ativa.                                                               | Sim                                               |
| `money_format`            | O formato de dinheiro Shopify da loja.                                               | Sim                                               |
| `backend_url`             | Host direto do backend, usado como fallback quando o app proxy não está configurado. | Sim                                               |
| `storefront_access_token` | Token para chamadas à Storefront API.                                                | **Não** — adicionado quando o carrinho inicializa |

<Warning>
  `storefront_access_token` é o único campo de `context` que o servidor não renderiza em `cart.context`. Ele é adicionado a `context` quando o carrinho inicializa, então lê-lo no topo do seu script retorna `undefined`. Aguarde `window.aftersell.cart.ready()` primeiro.
</Warning>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
if (window.aftersell.cart.context.customer_country === 'CA') {
  // Canada-only behavior, decided before the cart loads.
}
```

<Note>
  Para mostrar configurações de bloco diferentes por mercado, país ou moeda, use as [condições no editor do carrinho](/pt/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency) em vez disso. Nenhum script necessário. A UI completa de Conditions está disponível hoje em [Rewards](/pt/aftersell/cart/rewards-block#per-market-rewards).
</Note>

<div id="shadowroot">
  ## shadowRoot
</div>

O carrinho renderiza dentro de um shadow root, então `document.querySelector` **não consegue ver nada dentro do drawer**. Para alcançar um elemento no carrinho, consulte o shadow root:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const root = window.aftersell.cart.shadowRoot;
const button = root?.querySelector('.cart-external-checkout-button');
```

Mire nas mesmas **classes públicas `cart-external-*`** que o [Custom CSS](/pt/aftersell/cart/custom-css) usa. Esses são os pontos de apoio suportados. As gêmeas `cart-internal-*` são o encanamento interno do carrinho, então consulte as externas.

<Warning>
  Recorra ao shadow root somente quando nenhum bloco, configuração ou hook resolver. Um hook sobrevive a um redesign do carrinho; uma consulta ao DOM é problema do seu código manter.
</Warning>

O shadow root só existe depois que o carrinho inicializou, então leia-o dentro de `ready()` ou de um handler de evento, e não no topo do seu script.

<div id="debugging">
  ## Depuração
</div>

Um script quebrado nunca deve derrubar o adicionar ao carrinho ou o drawer, então o SDK contém as falhas em vez de deixá-las se propagar. Onde uma falha aparece depende do que quebrou:

| O que falhou                                                                     | Onde aparece                                              |
| -------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Seu script lançou um erro no nível superior                                      | `console.error`, indicando a linha e o que nunca executou |
| Um handler de [evento](/pt/aftersell/cart/sdk-events) lançou um erro             | `console.error`; os outros handlers ainda executam        |
| Um [hook](/pt/aftersell/cart/sdk-hooks) lançou um erro                           | Silencioso. Vai para o canal de debug abaixo              |
| Uma [ação](/pt/aftersell/cart/sdk-actions) executou antes de o carrinho carregar | `console.warn`; a chamada não faz nada                    |

<div id="when-your-script-throws">
  ### Quando seu script lança um erro
</div>

Um script personalizado **para no primeiro erro**, então todo `configure`, `events.on` e `hooks.register*` abaixo daquela linha nunca executa. O carrinho diz isso explicitamente:

```
[aftersell-cart] Initialization script error on line 12 — 4 more line(s) did not run;
any configure/events/hooks below are unregistered.
```

Essa é a mensagem a procurar quando um handler que você com certeza registrou nunca dispara: ele provavelmente nunca foi alcançado. O número da linha é a instrução de nível superior onde a execução parou, não a função interna que lançou o erro, e ele é omitido em vez de adivinhado se a stack do navegador não for utilizável.

Seus scripts também executam com seus próprios nomes de arquivo, então aparecem como `aftersell-cart-init.js` e `aftersell-cart-cart-update.js` no DevTools. Você pode abri-los no painel Sources e definir breakpoints como em qualquer outro arquivo.

<div id="the-debug-channel">
  ### O canal de debug
</div>

As falhas de hooks são deliberadamente mantidas fora do console para que os compradores nunca as vejam. Elas vão para cá em vez disso:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// After reproducing the problem, inspect what was swallowed:
window.aftersellCartDebugEvents.filter((entry) => entry.level === 'ERROR');

// Or watch them live:
window.addEventListener('aftersell-cart-debug', (event) => console.log(event.detail));
```

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

<Columns cols={2}>
  <Card title="Configure" icon="sliders" href="/pt/aftersell/cart/sdk-configure">
    Toda opção, com um exemplo de cada.
  </Card>

  <Card title="Events" icon="tower-broadcast" href="/pt/aftersell/cart/sdk-events">
    Todo evento, quando dispara e o que não fazer em um handler.
  </Card>

  <Card title="Actions" icon="wand-magic-sparkles" href="/pt/aftersell/cart/sdk-actions">
    Toda ação, com um snippet de cada.
  </Card>

  <Card title="Hooks" icon="plug" href="/pt/aftersell/cart/sdk-hooks">
    Todo hook, e como os registros se compõem.
  </Card>

  <Card title="Cart object" icon="table-list" href="/pt/aftersell/cart/sdk-cart-object">
    O formato do carrinho e de suas linhas.
  </Card>

  <Card title="Use cases" icon="book-open" href="/pt/aftersell/cart/sdk-use-cases">
    Soluções completas e executáveis para pedidos comuns.
  </Card>
</Columns>