# Casos de uso da API de commerce: sete projetos que você não consegue fazer com um widget

> Quando um widget de loja não tem o formato certo: commerce embutido em SaaS, catálogos em várias superfícies, lojas white-label, UX personalizada, agentes de IA e BI sob medida. Com exemplos de código do SDK JS da Shoprocket.

Ryan Badger - 4 de agosto de 2025 - 5 min de leitura

## Para que serve uma API de e-commerce para embutir

A maioria das plataformas de e-commerce entrega um widget. Cole um script e pronto: você tem uma loja. Funciona bem para 95% das lojas.

Uma API de commerce é o que você usa quando quer fazer algo que um widget não faz: renderizar produtos dentro da sua própria interface, embutir o checkout no painel de um SaaS, distribuir um catálogo por várias superfícies (web + mobile + voz) ou montar fluxos de compra personalizados que nenhuma plataforma entrega pronta.

A Shoprocket oferece os dois. O [widget](https://v3.shoprocket.io/pt/blog/headless-commerce-tres-niveis-opcoes-reais-e-qual-voce-provavelmente-quer.md) é o padrão. O [SDK `@shoprocket/core`](https://github.com/shoprocket/shoprocket-js) é para quando você ultrapassa o widget ou nunca precisou de um.

## Casos de uso que exigem uma API, e não um widget

Estes são os projetos em que um widget não basta. Se a sua ideia está nesta lista, você está em território de API.

### 1. Commerce dentro do seu produto SaaS

O painel do seu SaaS já tem a própria interface. Você quer que os clientes comprem complementos, pacotes de créditos, planos premium ou merch físico sem sair do seu app.

Um widget seria o formato errado: ele não conhece os seus usuários, não combina com o seu design system e presume uma loja em página inteira. A API permite renderizar cartões de produto com os seus próprios componentes, chamar `cart.addItem()` no clique do botão e abrir o seu próprio painel de checkout (ou redirecionar para um checkout hospedado se você quiser adiar o trabalho de conformidade).

```
import { ShoprocketCore } from '@shoprocket/core'

const sr = new ShoprocketCore({ publicKey: 'pk_...' })

// Renderiza os cartões de complementos dentro do painel do seu SaaS
const addons = await sr.products.list({ category: 'addons' })

// O usuário clica no botão "Adicionar créditos"
await sr.cart.addItem(addon.id, 1)
```

### 2. Catálogo em várias superfícies (web + app nativo + voz + chat)

Um catálogo de produtos, renderizado de forma diferente em cada lugar. A loja web mostra o detalhe completo do produto, o app nativo de iOS mostra uma lista compacta, o assistente de voz descreve os itens em voz alta, uma integração de chat responde com um link de compra.

As quatro superfícies chamam a mesma API. Quando você atualiza o preço de um produto no painel da Shoprocket, todas as superfícies refletem a mudança na próxima leitura. Sem sincronização de conteúdo por superfície.

### 3. Lojas white-label / de parceiros

Você é uma plataforma em que outras pessoas vendem seus produtos: um marketplace de comunidade, um diretório de parceiros, uma rede de franquias com sites individuais de revendedores. Cada parceiro tem uma identidade visual própria, e não a sua.

O site de cada parceiro roda o seu framework, mas chama a API de commerce com a `publicKey` dele. Produtos, pedidos e repasses de cada um, tudo separado por conta. Nenhum widget atrapalha a identidade visual deles.

### 4. UX de compra totalmente personalizada

Configuradores interativos de produto (montagem de PC sob medida, joias personalizadas, móveis feitos sob encomenda). Visualizadores 3D de produto. Galerias de fotos do tipo "compre o ambiente", em que clicar em pixels de uma imagem adiciona o produto ao carrinho. Botões de recompra rápida dentro do e-mail.

O widget não faz nada disso. A API faz. Você renderiza a interface que o seu designer imaginou; a API cuida da mecânica de commerce por trás.

### 5. Agentes de IA e commerce agêntico

Um agente de IA (ChatGPT, Claude, um agente próprio) que consegue navegar por produtos e concluir compras em nome do usuário. O agente precisa de acesso programático ao seu catálogo e ao carrinho, e não de um widget no DOM que ele tenha de interpretar.

A Shoprocket oferece feeds para protocolos de commerce com IA, além do acesso padrão pela API. Um agente que pergunta "o que tem em estoque por menos de US$ 50 com frete grátis" recebe uma resposta estruturada, e não uma raspagem de tela.

### 6. Commerce embutido em ferramentas de conteúdo

Uma página do Notion em que blocos podem ser comprados. Um design do Framer com pontos clicáveis de compra. Uma ferramenta de newsletter em que os assinantes tocam num cartão de produto e pagam sem sair do e-mail. Tudo construído sobre uma API.

### 7. Relatórios personalizados e painéis de BI

O painel da Shoprocket mostra receita, conversão e produtos mais vendidos. O que ele não mostra são as *suas* métricas próprias: valor do cliente ao longo do tempo por coorte, pedidos por origem de indicação, margem depois do custo do fornecedor. A API expõe os dados de pedidos e clientes para você levá-los à sua ferramenta de BI, planilha ou painel interno.

## O que o SDK oferece hoje

Do `@shoprocket/core`:

```
// Products
sr.products.list({ limit, offset, sort, category })
sr.products.get(productId)

// Cart
sr.cart.get()
sr.cart.addItem(productId, quantity)
sr.cart.updateItem(itemId, quantity)
sr.cart.removeItem(itemId)

// Session
sr.session.create()
sr.setSessionToken(token)
```

Além da API REST completa para tudo o que o SDK ainda não cobre (pedidos, clientes, descontos, escrita de produtos). Veja a referência completa em [api.shoprocket.io/docs](https://api.shoprocket.io/docs).

## Onde começar pela API é um erro

Alguns casos em que o widget é a escolha certa e a API é exagero:

- **Uma loja simples com 10 a 200 produtos.** O widget renderiza isso perfeitamente; escrever a sua própria interface de catálogo é refazer um trabalho já resolvido.
- **Você não tem capacidade dedicada de engenharia de frontend.** Começar pela API exige que você entregue e mantenha os seus próprios estados de carregamento, interface de variantes, tratamento de erros, acessibilidade e i18n em 21 idiomas. São semanas de trabalho que o widget dá de graça.
- **Sua principal preocupação é a velocidade de lançamento.** O widget leva minutos; começar pela API leva semanas, no mínimo.

Use o widget como padrão. Recorra à API quando esbarrar em algo que o widget não faz.

## Um primeiro projeto realista

O projeto mais comum de "preciso da API": um produto SaaS que quer vender créditos, assinaturas ou complementos avulsos dentro do próprio painel.

Abordagem:

1. Instale o `@shoprocket/core` no seu frontend
2. Crie na Shoprocket uma categoria chamada "Complementos" ou parecida
3. Adicione produtos com o preço e a descrição exatos que você quer
4. Renderize a lista de produtos no seu painel com a sua própria biblioteca de componentes
5. No clique, adicione ao carrinho + redirecione para o checkout hospedado da Shoprocket (ou embuta o checkout na própria página, se você se sentir à vontade com o trabalho extra)
6. Configure um endpoint de webhook para receber eventos `order.paid`, para liberar o que a compra desbloqueia (créditos, acesso, envio)

É isso. Um punhado de arquivos, um dia de trabalho para quem está acostumado a chamar APIs. Sem widget, sem iframe, sem concessões na interface do seu produto.

## O que não recomendamos

Não reconstrua uma interface de catálogo completa que se pareça muito com o que o widget já faz. Se você está gastando semanas numa "grade de produtos com filtros e busca", está escrevendo o que o widget entrega em minutos. Use o widget para esse formato e a API para os formatos genuinamente diferentes.

> **Dica:** Se você está pensando em começar pela API porque o estilo padrão do widget não combina com a sua marca, tente primeiro os [ganchos de estilo do widget](https://github.com/shoprocket/shoprocket-js). O widget aceita muito mais personalização em CSS do que parece. Reconstruir tudo pela API é um trabalho bem mais pesado.

## Resumo

- **Widget** = padrão, cobre 95% das lojas
- **API / SDK** = quando o widget não tem o formato certo (commerce embutido em SaaS, várias superfícies, white-label, UX personalizada, agentes de IA, BI sob medida)
- **Cobertura atual do SDK:** produtos, carrinho, sessões; mais a API REST completa para pedidos / clientes / descontos
- **Padrão de primeiro projeto:** painel de SaaS vendendo créditos ou complementos via SDK + liberação acionada por webhook
- **Não reconstrua pela API** o que o widget já faz bem; escolha o seu formato

[Comece um teste grátis](https://app-v3.shoprocket.io/signup) e pegue uma chave pública; o SDK é gratuito em qualquer plano da Shoprocket. 14 dias, sem cartão.

---

- HTML version: https://v3.shoprocket.io/pt/blog/casos-de-uso-api-de-commerce-sete-projetos-que-widget-nao-faz
- Language: Português (pt)
- Also in: [العربية](https://v3.shoprocket.io/ar/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Deutsch](https://v3.shoprocket.io/de/blog/commerce-api-anwendungsfaelle-sieben-builds-ohne-widget.md), [Ελληνικά](https://v3.shoprocket.io/el/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [English](https://v3.shoprocket.io/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Español](https://v3.shoprocket.io/es/blog/casos-de-uso-api-de-comercio-siete-proyectos-que-un-widget-no-puede-hacer.md), [Français](https://v3.shoprocket.io/fr/blog/api-commerce-sept-cas-usage-impossibles-avec-un-widget.md), [עברית](https://v3.shoprocket.io/he/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [हिन्दी](https://v3.shoprocket.io/hi/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Bahasa Indonesia](https://v3.shoprocket.io/id/blog/kasus-penggunaan-commerce-api-tujuh-hal-yang-tidak-bisa-dilakukan-widget.md), [Italiano](https://v3.shoprocket.io/it/blog/api-commerce-sette-casi-duso-che-un-widget-non-copre.md), [日本語](https://v3.shoprocket.io/ja/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Lietuvių](https://v3.shoprocket.io/lt/tinklarastis/prekybos-api-panaudojimo-atvejai-septyni-sprendimai-kuriu-nepadarysite-su-valdykle.md), [Norsk](https://v3.shoprocket.io/nb/blogg/handels-api-sju-ting-du-ikke-kan-bygge-med-en-widget.md), [Nederlands](https://v3.shoprocket.io/nl/blog/commerce-api-use-cases-zeven-projecten-zonder-widget.md), [Polski](https://v3.shoprocket.io/pl/blog/api-do-e-commerce-siedem-zastosowan-ktorych-nie-zrobisz-widzetem.md), [Română](https://v3.shoprocket.io/ro/blog/cazuri-de-utilizare-api-comert-sapte-proiecte-fara-widget.md), [Русский](https://v3.shoprocket.io/ru/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [ไทย](https://v3.shoprocket.io/th/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Türkçe](https://v3.shoprocket.io/tr/blog/commerce-api-kullanim-senaryolari-widget-ile-yapilamayan-yedi-proje.md), [中文](https://v3.shoprocket.io/zh/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md)