# Casos de uso de una API de comercio: siete proyectos que no puedes hacer con un widget

> Cuando un widget de tienda no es la forma adecuada: comercio embebido en SaaS, catálogos multisuperficie, tiendas de marca blanca, UX a medida, agentes de IA y BI personalizada. Con ejemplos de código del SDK JS de Shoprocket.

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

## Para qué sirve una API de ecommerce para embeber

La mayoría de las plataformas de ecommerce te dan un widget. Pegas un script y obtienes una tienda. Funciona bien para el 95 % de las tiendas.

Una API de comercio es lo que necesitas cuando quieres hacer algo que un widget no puede: mostrar productos dentro de tu propia interfaz, embeber el checkout en el panel de un SaaS, distribuir un catálogo por varias superficies (web + móvil + voz) o construir flujos de compra a medida que ninguna plataforma ofrece de serie.

Shoprocket ofrece ambas. El [widget](https://v3.shoprocket.io/es/blog/headless-commerce-tres-niveles-opciones-reales.md) es la opción por defecto. El [SDK `@shoprocket/core`](https://github.com/shoprocket/shoprocket-js) es para cuando el widget se te queda pequeño o nunca lo necesitaste.

## Casos de uso que requieren una API, no un widget

Estos son los proyectos en los que un widget no basta. Si tu idea está en esta lista, estás en terreno de API.

### 1. Comercio dentro de tu producto SaaS

El panel de tu SaaS ya tiene su propia interfaz. Quieres que tus clientes compren complementos, paquetes de créditos, planes premium o merchandising físico sin salir de tu aplicación.

Un widget tendría la forma equivocada: no conoce a tus usuarios, no encaja con tu sistema de diseño y da por hecho una tienda a página completa. La API te permite mostrar tarjetas de producto con tus propios componentes, llamar a `cart.addItem()` al pulsar un botón y abrir tu propio panel de checkout (o redirigir a un checkout alojado si prefieres posponer el trabajo de cumplimiento normativo).

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

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

// Muestra los complementos dentro del panel de tu SaaS
const addons = await sr.products.list({ category: 'addons' })

// El usuario pulsa el botón // User clicks "Add credits" buttonquot;Añadir créditos// User clicks "Add credits" buttonquot;
await sr.cart.addItem(addon.id, 1)
```

### 2. Catálogo multisuperficie (web + app nativa + voz + chat)

Un solo catálogo de productos, presentado de forma distinta en cada lugar. La tienda web muestra el detalle completo del producto, la app nativa de iOS una lista compacta, el asistente de voz describe los artículos en voz alta y una integración de chat responde con un enlace de compra.

Las cuatro superficies llaman a la misma API. Cuando cambias el precio de un producto en el panel de Shoprocket, todas lo reflejan en la siguiente consulta. Sin sincronizar contenido superficie por superficie.

### 3. Tiendas de marca blanca / de socios

Eres una plataforma donde otras personas venden sus productos: un marketplace comunitario, un directorio de socios, una red de franquicias con sitios individuales para cada distribuidor. Cada socio tiene una marca propia, no la tuya.

El sitio de cada socio funciona con tu framework pero llama a la API de comercio con su `publicKey`. Sus productos, sus pedidos, sus pagos, todo acotado por cuenta. Ningún widget se interpone en su marca.

### 4. Experiencia de compra totalmente a medida

Configuradores de producto interactivos (PCs a medida, joyería personalizada, muebles bajo pedido). Visores de producto en 3D. Galerías de fotos tipo "compra la estancia" donde hacer clic en los píxeles de una imagen añade el producto al carrito. Botones de recompra rápida dentro de un email.

El widget no puede hacer nada de esto. La API sí. Tú muestras la interfaz que haya soñado tu diseñador; la API se encarga de la mecánica de comercio que hay detrás.

### 5. Agentes de IA y comercio agéntico

Un agente de IA (ChatGPT, Claude, un agente propio) que pueda explorar productos y completar compras en nombre del usuario. El agente necesita acceso programático a tu catálogo y a tu carrito, no un widget del DOM que tenga que interpretar.

Shoprocket ofrece feeds para los protocolos de comercio con IA además del acceso estándar por API. Si a un agente le preguntan "qué hay en stock por menos de 50 $ con envío gratis", recibe una respuesta estructurada, no una captura de pantalla que tenga que rastrear.

### 6. Comercio embebido en herramientas de contenido

Una página de Notion donde los bloques se pueden comprar. Un diseño de Framer con zonas interactivas de compra con un clic. Una herramienta de newsletters donde los suscriptores pueden tocar una tarjeta de producto y pagar sin salir del email. Todo construido sobre una API.

### 7. Informes personalizados y paneles de BI

El panel de Shoprocket muestra ingresos, conversión y productos más vendidos. Lo que no muestra son *tus* métricas: valor de vida por cohorte de clientes, pedidos por fuente de recomendación, margen tras el coste del proveedor. La API expone los datos de pedidos y clientes para que los lleves a tu propia herramienta de BI, a una hoja de cálculo o a un panel interno.

## Lo que te da el SDK hoy

Desde `@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)
```

Además, la API REST completa para todo lo que el SDK aún no envuelve (pedidos, clientes, descuentos, escritura de productos). Consulta [api.shoprocket.io/docs](https://api.shoprocket.io/docs) para la referencia completa.

## Dónde apostar por la API primero es un error

Hay casos en los que el widget es la elección correcta y la API es excesiva:

- **Una tienda sencilla con entre 10 y 200 productos.** El widget la muestra a la perfección; escribir tu propia interfaz de catálogo es rehacer un trabajo ya resuelto.
- **No tienes capacidad de ingeniería frontend dedicada.** Apostar por la API primero exige crear y mantener tus propios estados de carga, interfaz de variantes, gestión de errores, accesibilidad e i18n en 21 idiomas. Son semanas de trabajo que el widget te da gratis.
- **Tu prioridad es la velocidad de lanzamiento.** El widget son minutos; la API primero son semanas como mínimo.

Empieza por el widget. Recurre a la API cuando te topes con algo que el widget no puede hacer.

## Un primer proyecto realista

El proyecto más habitual de "necesito la API": un producto SaaS que quiere vender créditos, suscripciones o complementos puntuales dentro de su propio panel.

El enfoque:

1. Instala `@shoprocket/core` en tu frontend
2. Crea en Shoprocket una categoría llamada "Complementos" o similar
3. Añade los productos con el precio y la descripción exactos que quieras
4. Muestra la lista de productos en tu panel con tu propia biblioteca de componentes
5. Al hacer clic, añade al carrito y redirige al checkout alojado de Shoprocket (o embebe el checkout en línea si te sientes cómodo con el trabajo adicional)
6. Configura un endpoint de webhook para recibir eventos `order.paid` y poder activar lo que desbloquee la compra (créditos, acceso, envío)

Eso es todo. Un puñado de archivos, un día de trabajo para quien está acostumbrado a llamar a APIs. Sin widget, sin iframe, sin renunciar a la interfaz de tu producto.

## Lo que no recomendamos

No reconstruyas una interfaz de catálogo completa que se parezca mucho a lo que el widget ya hace. Si estás dedicando semanas a una "cuadrícula de productos con filtros y búsqueda", estás escribiendo lo que el widget ofrece en minutos. Usa el widget para esa forma y la API para las formas realmente distintas.

> **Consejo:** si estás pensando en apostar por la API porque el estilo por defecto del widget no encaja con tu marca, prueba primero los [ganchos de estilo del widget](https://github.com/shoprocket/shoprocket-js). El widget admite mucha más personalización con CSS de la que parece. Reconstruirlo todo con la API es un esfuerzo mucho mayor.

## Resumen

- **Widget** = la opción por defecto, cubre el 95 % de las tiendas
- **API / SDK** = cuando el widget no tiene la forma adecuada (comercio embebido en SaaS, multisuperficie, marca blanca, UX a medida, agentes de IA, BI personalizada)
- **Superficie actual del SDK:** productos, carrito, sesiones; más la API REST completa para pedidos / clientes / descuentos
- **Patrón del primer proyecto:** un panel SaaS que vende créditos o complementos mediante el SDK y activa lo comprado a través de webhooks
- **No reconstruyas con la API** lo que el widget ya hace bien; elige tu forma

[Empieza una prueba gratuita](https://app-v3.shoprocket.io/signup) y consigue una clave pública; el SDK es gratis en cualquier plan de Shoprocket. 14 días, sin tarjeta.

---

- HTML version: https://v3.shoprocket.io/es/blog/casos-de-uso-api-de-comercio-siete-proyectos-que-un-widget-no-puede-hacer
- Language: Español (es)
- 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), [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), [Português](https://v3.shoprocket.io/pt/blog/casos-de-uso-api-de-commerce-sete-projetos-que-widget-nao-faz.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)