# Kasus penggunaan Commerce API: tujuh pembuatan yang tidak bisa dilakukan dengan widget

> Saat widget storefront bukan bentuk yang tepat: commerce tertanam di SaaS, katalog multi-permukaan, toko white-label, UX kustom, agen AI, BI kustom. Plus contoh kode dari Shoprocket JS SDK.

Ryan Badger - 4 Agustus 2025 - 5 menit baca

## Untuk apa API ecommerce untuk embedding

Kebanyakan platform ecommerce memberi Anda widget. Tempel skrip, dapat storefront. Berfungsi baik untuk 95% toko.

Commerce API adalah yang Anda cari ketika ingin melakukan sesuatu yang tidak bisa dilakukan widget: menampilkan produk di dalam UI Anda sendiri, menanamkan checkout di dalam dashboard SaaS, mendistribusikan katalog ke banyak permukaan (web + mobile + suara), atau membangun alur pembeli kustom yang tidak disediakan platform mana pun secara bawaan.

Shoprocket menyediakan keduanya. [Widget](https://v3.shoprocket.io/id/blog/headless-commerce-tiga-tingkatan-pilihan-nyata-dan-mana-yang-anda-butuhkan.md) adalah defaultnya. [SDK `@shoprocket/core`](https://github.com/shoprocket/shoprocket-js) untuk saat Anda melampaui widget atau sejak awal memang tidak membutuhkannya.

## Kasus penggunaan yang membutuhkan API, bukan widget

Inilah pembuatan di mana widget tidak cukup. Kalau ide Anda ada di daftar ini, Anda berada di wilayah API.

### 1. Commerce di dalam produk SaaS Anda

Dashboard SaaS Anda sudah punya UI sendiri. Anda ingin pelanggan membeli add-on, paket kredit, tingkat premium, atau merchandise fisik tanpa keluar dari aplikasi Anda.

Widget akan menjadi bentuk yang salah: ia tidak tahu tentang pengguna Anda, tidak cocok dengan design system Anda, dan mengasumsikan storefront satu halaman penuh. API memungkinkan Anda menampilkan kartu produk dengan komponen Anda sendiri, memanggil `cart.addItem()` saat tombol diklik, dan memunculkan panel checkout Anda sendiri (atau mengalihkan ke checkout yang di-hosting jika Anda ingin menunda pekerjaan kepatuhan).

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

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

// Tampilkan kartu add-on di dalam dashboard SaaS Anda
const addons = await sr.products.list({ category: 'addons' })

// Pengguna mengeklik tombol "Tambah kredit"
await sr.cart.addItem(addon.id, 1)
```

### 2. Katalog multi-permukaan (web + aplikasi native + suara + chat)

Satu katalog produk, ditampilkan secara berbeda di setiap tempat. Storefront web menampilkan detail produk lengkap, aplikasi iOS native menampilkan daftar ringkas, asisten suara menjelaskan barang secara lisan, integrasi chat membalas dengan tautan yang bisa langsung dibeli.

Keempat permukaan memanggil API yang sama. Saat Anda memperbarui harga produk di dashboard Shoprocket, setiap permukaan mencerminkannya pada pengambilan berikutnya. Tanpa sinkronisasi konten per permukaan.

### 3. Storefront white-label / mitra

Anda adalah platform tempat orang lain menjual barang mereka: marketplace komunitas, direktori mitra, jaringan waralaba dengan situs dealer masing-masing. Setiap mitra punya branding milik mereka, bukan milik Anda.

Situs setiap mitra menjalankan framework Anda tetapi memanggil commerce API dengan `publicKey` mereka. Produk mereka, pesanan mereka, pembayaran mereka, semuanya dibatasi per akun. Tidak ada widget yang menghalangi branding mereka.

### 4. UX pembeli yang sepenuhnya kustom

Konfigurator produk interaktif (rakitan PC kustom, perhiasan personal, furnitur sesuai pesanan). Penampil produk 3D. Galeri foto "belanja ruangan" di mana mengklik piksel pada gambar menambahkan produk ke keranjang. Tombol pesan ulang cepat di dalam email.

Widget tidak bisa melakukan satu pun dari ini. API bisa. Anda menampilkan UI apa pun yang dibayangkan desainer Anda; API menangani mekanisme commerce di baliknya.

### 5. Agen AI dan agentic commerce

Agen AI (ChatGPT, Claude, agen kustom) yang bisa menjelajahi produk dan menyelesaikan pembelian atas nama pengguna. Agen membutuhkan akses terprogram ke katalog dan keranjang Anda, bukan widget DOM yang harus ia urai.

Shoprocket menyediakan feed untuk protokol commerce AI di samping akses API standar. Agen yang ditanya "apa yang ada stoknya di bawah $50 dengan gratis ongkir" mendapat jawaban terstruktur, bukan hasil scraping layar.

### 6. Commerce tertanam di alat konten

Halaman Notion di mana blok-bloknya bisa dibeli. Desain Framer dengan hotspot klik-untuk-beli. Alat newsletter di mana pelanggan bisa mengetuk kartu produk dan membayar tanpa meninggalkan email. Semuanya dibangun di atas API.

### 7. Pelaporan kustom dan dashboard BI

Dashboard Shoprocket menampilkan pendapatan, konversi, produk teratas. Yang tidak ditampilkan adalah metrik kustom *Anda*: lifetime value per kohort pelanggan, pesanan per sumber rujukan, margin setelah biaya pemasok. API mengekspos data pesanan dan pelanggan sehingga Anda bisa mengalirkannya ke alat BI, spreadsheet, atau dashboard internal Anda sendiri.

## Yang diberikan SDK saat ini

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

Plus REST API lengkap untuk apa pun yang belum dibungkus SDK (pesanan, pelanggan, diskon, penulisan produk). Lihat [api.shoprocket.io/docs](https://api.shoprocket.io/docs) untuk referensi lengkapnya.

## Di mana API-first adalah kesalahan

Beberapa kasus di mana widget adalah pilihan yang tepat dan API berlebihan:

- **Storefront sederhana dengan 10-200 produk.** Widget menampilkannya dengan sempurna; menulis UI katalog sendiri berarti mengulang pekerjaan yang sudah terselesaikan.
- **Anda tidak punya kapasitas engineering frontend khusus.** API-first mengharuskan Anda merilis dan memelihara sendiri status loading, UI varian, penanganan galat, aksesibilitas, i18n di 21 lokal. Itu berminggu-minggu kerja yang diberikan widget secara gratis.
- **Perhatian utama Anda adalah kecepatan peluncuran.** Widget hitungan menit; API-first minimal berminggu-minggu.

Jadikan widget sebagai default. Gunakan API saat Anda menemui sesuatu yang tidak bisa dilakukan widget.

## Proyek pertama yang realistis

Proyek "saya butuh API" yang paling umum: produk SaaS yang ingin menjual kredit, langganan, atau add-on sekali beli di dalam dashboard-nya sendiri.

Pendekatan:

1. Pasang `@shoprocket/core` di frontend Anda
2. Buat kategori di Shoprocket bernama "Add-ons" atau sejenisnya
3. Tambahkan produk dengan harga / deskripsi persis seperti yang Anda inginkan
4. Tampilkan daftar produk di dashboard Anda memakai pustaka komponen Anda sendiri
5. Saat diklik, tambahkan ke keranjang + alihkan ke checkout yang di-hosting oleh Shoprocket (atau embed checkout secara inline jika Anda nyaman dengan pekerjaan tambahannya)
6. Atur endpoint webhook untuk menerima event `order.paid` agar Anda bisa memberikan apa pun yang dibuka oleh pembelian itu (kredit, akses, pengiriman)

Itu saja. Beberapa file, sehari kerja bagi orang yang terbiasa memanggil API. Tanpa widget, tanpa iframe, tanpa kompromi pada UI produk Anda.

## Yang tidak kami sarankan

Jangan membangun ulang UI katalog lengkap yang sangat mirip dengan yang sudah dilakukan widget. Kalau Anda menghabiskan berminggu-minggu untuk "grid produk dengan filter dan pencarian", Anda menulis apa yang disediakan widget dalam hitungan menit. Gunakan widget untuk bentuk itu, gunakan API untuk bentuk yang benar-benar berbeda.

> **Tips:** Kalau Anda berpikir untuk API-first karena gaya default widget tidak cocok dengan brand Anda, coba dulu [styling hook widget](https://github.com/shoprocket/shoprocket-js). Widget menerima kustomisasi CSS jauh lebih banyak daripada kelihatannya. Membangun ulang dengan API penuh adalah pekerjaan yang jauh lebih berat.

## TL;DR

- **Widget** = default, mencakup 95% toko
- **API / SDK** = ketika widget bukan bentuk yang tepat (commerce tertanam di SaaS, multi-permukaan, white-label, UX kustom, agen AI, BI kustom)
- **Cakupan SDK saat ini:** produk, keranjang, sesi; plus REST API lengkap untuk pesanan / pelanggan / diskon
- **Pola proyek pertama:** dashboard SaaS yang menjual kredit atau add-on lewat SDK + provisioning berbasis webhook
- **Jangan bangun ulang dengan API** apa yang sudah dilakukan widget dengan baik; pilih bentuk Anda

[Mulai uji coba gratis](https://app-v3.shoprocket.io/signup) dan ambil public key; SDK gratis dipakai di paket Shoprocket mana pun. 14 hari, tanpa kartu.

---

- HTML version: https://v3.shoprocket.io/id/blog/kasus-penggunaan-commerce-api-tujuh-hal-yang-tidak-bisa-dilakukan-widget
- Language: Bahasa Indonesia (id)
- 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), [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)