Pengantar

Name: OneEntry SDK
Author: OneEntry

Kelola produk e-commerce dengan katalog dinamis, penyaringan, dan pencarian.

Informasi lebih lanjut tentang Katalog di panel admin OneEntry: https://doc.oneentry.cloud/docs/category/catalog

🎯 Apa yang dilakukan modul ini?

Modul Products (Katalog) memungkinkan Anda untuk mengambil, menyaring, mencari, dan mengurutkan produk di toko online atau koleksi multimedia Anda. Anda mengelola katalog di panel admin OneEntry (Katalog > Produk); aplikasi Anda mengambil produk secara dinamis, sehingga mengubah harga atau atribut di admin akan langsung terlihat tanpa perlu redeploy.

Selain e-commerce, Katalog juga cocok untuk galeri multimedia, portofolio, perpustakaan dokumen, dan koleksi konten lainnya.

🚀 Memulai dengan Cepat

Inisialisasi modul dari defineOneEntry:


const { Products } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Ambil halaman produk dan baca field-nya:

// Fetch the first 20 products (empty body = no filters).
const { items, total } = await Products.getProducts([], "en_US", { limit: 20 });

console.log(`Loaded ${items.length} of ${total} products`);

items.forEach((product) => {
  console.log(product.id, product.localizeInfos.title, product.price);
});

Sebagian besar metode listing memiliki bentuk yang sama: filter body opsional, langCode, dan userQuery opsional (paginasi/penyortiran). Lihat Parameter di bawah untuk set lengkapnya.

✨ Konsep Kunci

Apa itu Produk?

Sebuah produk adalah entitas katalog (IProductsEntity) yang terdiri dari:

Info dasar - localizeInfos (judul, dll.), sku, harga
Gambar - foto produk / galeri (disimpan sebagai atribut)
Atribut kustom - field apa pun yang Anda definisikan (attributeValues): merek, material, ukuran, warna, varian, stok, …
Lokalisasi - konten per bahasa

Tidak ada tipe produk tetap dalam SDK — struktur apa pun (varian, opsi, unduhan, bundel) dimodelkan dengan atribut kustom yang Anda konfigurasi untuk katalog.

Organisasi Produk

Produk diorganisir melalui beberapa fitur katalog:

Kategori - bagian dari katalog (halaman tipe Katalog, dibuat di modul Halaman)
Status Produk - kondisi penyaringan tambahan di luar filter atribut (misalnya "tersedia", "diskon")
Tautan Produk - menghubungkan produk berdasarkan kriteria atribut (misalnya semua ponsel hitam bersama)
Filter Produk - pencarian cepat berdasarkan kriteria filter yang ditentukan
Atribut kustom - merek, ukuran, warna, material, …

Contoh hierarki:

📁 Electronics
  ├─ 📱 Smartphones
  │   ├─ iPhone 15 Pro
  │   └─ Samsung Galaxy S24
  └─ 💻 Laptops
      ├─ MacBook Pro
      └─ Dell XPS

📁 Clothing
  ├─ 👕 T-Shirts
  └─ 👖 Jeans

📋 Apa yang Perlu Anda Ketahui

Arsitektur Katalog

Kategori katalog adalah halaman tipe Katalog yang dibuat melalui modul Halaman — buat mereka sebelum menambahkan produk:

Buka modul Halaman di panel admin.
Buat halaman dengan tipe Katalog — ini menjadi kategori produk Anda.
Tambahkan produk ke kategori tersebut melalui Katalog > Produk.

Katalog admin juga menyediakan Unggah Katalog massal, Filter Produk, Tautan Produk, Status Produk, dan Pengaturan per katalog.

Paginasi

Jangan memuat semuanya sekaligus — halaman hasil dengan limit dan offset:

Rumus Offset: offset = (pageNumber - 1) * limit

Limit default: Anda dapat mengambil 10 objek secara default. Untuk mempaging lebih banyak, konfigurasikan Izin Modul sesuai kebutuhan Anda.

Penyortiran

Kirim sortKey dan sortOrder dalam userQuery:

sortKey	Apa yang Dilakukan	Contoh Penggunaan
harga	Urutkan berdasarkan harga	Tampilkan yang termurah lebih dulu
tanggal	Urutkan berdasarkan tanggal pembuatan	Tampilkan produk terbaru
judul	Urutkan secara alfabetis	Daftar produk A-Z
posisi	Urutan kustom (default)	Urutan yang dipilih dari admin
id	Urutkan berdasarkan ID	Penyortiran teknis

Urutan sort: ASC (rendah→tinggi) atau DESC (tinggi→rendah, default).

Penyaringan

Penyaringan dilakukan melalui body permintaan (sebuah array dari IFilterParams), bukan userQuery. Setiap kondisi menggabungkan attributeMarker, conditionMarker (eq, neq, in, nin, mth, lth, exs, nexs), dan conditionValue. Gabungkan beberapa kondisi dalam array untuk menyaring berdasarkan beberapa kriteria sekaligus. Referensi kondisi lengkap ada di Parameter di bawah.

📊 Tabel Referensi Cepat - Metode Umum

Metode	Deskripsi	Kasus Penggunaan
getProducts()	Ambil semua produk dengan penyaringan/penyortiran	Halaman katalog utama
getProductById()	Ambil produk tunggal berdasarkan ID	Halaman detail produk
getProductsByPageId()	Ambil produk dari kategori berdasarkan ID halaman	Halaman kategori
getProductsByPageUrl()	Ambil produk dari kategori berdasarkan URL halaman	Halaman kategori berdasarkan URL
getRelatedProductsById()	Ambil produk terkait/similar	Bagian "Anda mungkin juga suka"
searchProduct()	Cari produk berdasarkan kueri	Fungsionalitas pencarian
getProductsCount()	Ambil total jumlah produk	Info paginasi
getProductsCountByPageId()	Ambil jumlah produk berdasarkan ID kategori	Paginasi kategori
getProductsCountByPageUrl()	Ambil jumlah produk berdasarkan URL kategori	Paginasi kategori
getProductBlockById()	Ambil blok produk berdasarkan ID	Blok konten produk
getProductsEmptyPage()	Ambil struktur halaman produk kosong	Penanganan keadaan kosong
getProductsPriceByPageUrl()	Ambil harga produk berdasarkan URL halaman	Penyaringan harga
getProductsByIds()	Ambil produk berdasarkan daftar ID	Keranjang, wishlist, perbandingan
getProductsByVectorSearch()	Pencarian semantik (vektor) untuk produk	Pencarian bertenaga AI

Parameter

Modul ini menerima serangkaian parameter pengguna yang disebut userQuery. Jika parameter tidak diberikan, default-nya diterapkan. Beberapa metode juga menerima body untuk penyaringan — kirim array kosong (atau tidak ada) ketika Anda tidak memerlukan filter.


const userQuery = {
    offset: 0,
    limit: 30,
    sortOrder: 'DESC',
    sortKey: 'id',
    signPrice: 'orders',
}

Catatan: bentuk userQuery tergantung pada metode. Field di atas adalah basis umum (IProductsQueryBase), digunakan oleh getProducts, getProductsByPageId, getProductsByPageUrl dan getProductsEmptyPage. Metode lain berbeda: getRelatedProductsById juga menerima statusMarker dan templateMarker; getProductsPriceByPageUrl juga menerima statusMarker (tanpa sortKey); getProductsByIds hanya menerima signPrice. Penyaringan (attributeMarker / conditionMarker / conditionValue) dilakukan melalui body permintaan, bukan userQuery — lihat di bawah.

Skema

offset: number
Parameter paginasi. Default 0
contoh: 0

limit: number
parameter paginasi. Default 30
contoh: 30

sortKey: string
Field untuk penyortiran (default tidak diatur - penyortiran berdasarkan posisi, nilai yang mungkin: id, title, date, price, position)
Nilai yang tersedia: id, position, title, date, price

sortOrder: string
urutan penyortiran DESC | ASC (default DESC)
contoh: "DESC"

signPrice: string
Penanda penyimpanan urutan untuk perbaikan harga. Jika parameter diatur, harga akan diperbaiki untuk waktu tertentu (lihat bagian Memperbaiki harga di bawah).
contoh: "orders"

Field spesifik metode: statusMarker (getRelatedProductsById, getProductsPriceByPageUrl) dan templateMarker (getRelatedProductsById) — string | null, default null.

Gunakan kondisi untuk menemukan data produk tertentu:

attributeMarker: Pengidentifikasi teks dari atribut yang diindeks yang nilainya disaring. conditionMarker: Jenis kondisi yang diterapkan pada nilai atribut.

Marker	Arti	Contoh
eq	Sama dengan	statusId = 1 (hanya aktif)
neq	Tidak sama dengan	kategori ≠ "arsip"
in	Mengandung (salah satu)	kategori in ["elektronik", "buku"]
nin	Tidak mengandung	merek tidak in ["merek_palsu"]
mth	Lebih besar dari	harga > 100
lth	Kurang dari	stok < 10
exs	Ada (memiliki nilai)	Memiliki deskripsi
nexs	Tidak ada	Tidak ada gambar

conditionValue: Nilai untuk dibandingkan.

Memperbaiki harga (signPrice)

Ketika Anda mengambil produk, Anda dapat mengirimkan parameter signPrice opsional di dalam userQuery (ini juga merupakan argumen pada metode rekomendasi dari modul Blocks). Ini menerima penanda penyimpanan urutan dan meminta server untuk mengunci harga yang dikembalikan untuk waktu terbatas.

signPrice — tipe string

Penanda penyimpanan urutan untuk perbaikan harga. Jika parameter diatur, harga akan diperbaiki untuk waktu tertentu.

Mengapa menggunakannya. Harga dapat berubah saat pelanggan berbelanja — diskon dimulai, atau admin mengedit harga. signPrice menjamin bahwa harga yang ditampilkan di katalog atau keranjang adalah harga yang tepat yang dikenakan saat checkout, sehingga tidak dapat berubah antara menjelajah dan memesan.

Cara kerjanya:

Ambil produk dengan signPrice diatur ke penanda penyimpanan urutan Anda (misalnya "orders").
Setiap produk yang dikembalikan sekarang membawa field signedPrice — token yang ditandatangani yang mengenkripsi harga yang terkunci.
Kirim token signedPrice itu kembali saat Anda membuat pesanan, sehingga server menghormati harga yang diperbaiki.


const { items } = await Products.getProducts([], "en_US", {
  signPrice: "orders"
});

const signedPrice = items[0].signedPrice;

➡️ Token yang dikembalikan digunakan oleh createOrder(). Lihat di mana mengambilnya dan bagaimana mengirimkannya di bagian Harga produk tetap (signedPrice) dari modul Orders.

❓ Pertanyaan Umum (FAQ)

Bisakah saya menyaring berdasarkan beberapa kriteria sekaligus?

Ya — kirim beberapa kondisi dalam array body; mereka digabungkan bersama:

const { items } = await Products.getProducts(
  [
    { attributeMarker: "price", conditionMarker: "mth", conditionValue: 100 },
    { attributeMarker: "brand", conditionMarker: "in", conditionValue: ["apple", "samsung"] },
  ],
  "en_US",
);

Bagaimana cara menangani varian produk (ukuran, warna)?

Varian disimpan dalam attributeValues produk — baca dari objek produk yang diambil. Strukturnya adalah atribut set apa pun yang Anda konfigurasi untuk katalog.

Bagaimana cara mengimplementasikan tombol "Muat Lebih Banyak"?

Tingkatkan offset dengan limit pada setiap klik dan tambahkan items baru ke daftar Anda (gunakan total untuk mengetahui kapan harus berhenti).

Bisakah saya menampilkan produk dari beberapa kategori?

Ya — saring dengan atribut category dan penanda kondisi in, mengirimkan daftar nilai kategori.

Bagaimana cara mengimplementasikan bagian "Produk Baru"?

Urutkan berdasarkan tanggal pembuatan: userQuery: { sortKey: "date", sortOrder: "DESC" }.

🎓 Praktik Terbaik

Selalu paginasi (limit + offset) — jangan pernah mengambil seluruh katalog sekaligus.
Cache daftar produk untuk kategori yang sering diakses untuk mengurangi panggilan API.
Gunakan signPrice ketika harga masuk ke keranjang/checkout sehingga harga tidak dapat berubah.
Tangani hasil kosong (total === 0) dan field yang hilang (harga, gambar) dengan baik.

🔗 Dokumentasi Terkait

Panel Admin OneEntry - Katalog - Dokumentasi resmi panel admin
Modul Halaman - Buat kategori katalog (halaman tipe Katalog)
Modul AttributesSets - Field dan atribut produk kustom
Modul Templates - Template tampilan produk
Modul Blocks - Blok konten produk yang dapat digunakan kembali
Modul Orders - Tangani pesanan produk

🎯 Apa yang dilakukan modul ini?​

🚀 Memulai dengan Cepat​

✨ Konsep Kunci​

Apa itu Produk?​

Organisasi Produk​

📋 Apa yang Perlu Anda Ketahui​

Arsitektur Katalog​

Paginasi​

Penyortiran​

Penyaringan​

📊 Tabel Referensi Cepat - Metode Umum​

Parameter​

Memperbaiki harga (signPrice)​

❓ Pertanyaan Umum (FAQ)​

Bisakah saya menyaring berdasarkan beberapa kriteria sekaligus?​

Bagaimana cara menangani varian produk (ukuran, warna)?​

Bagaimana cara mengimplementasikan tombol "Muat Lebih Banyak"?​

Bisakah saya menampilkan produk dari beberapa kategori?​

Bagaimana cara mengimplementasikan bagian "Produk Baru"?​

🎓 Praktik Terbaik​

🔗 Dokumentasi Terkait​