Lewati ke konten utama

Pendahuluan

Buat dan lacak pesanan pelanggan di seluruh siklus checkout, pembayaran, dan pemenuhan.

Informasi lebih lanjut tentang antarmuka pengguna modul ini https://doc.oneentry.cloud/docs/category/orders

🎯 Apa yang dilakukan modul ini?​

Modul Orders memungkinkan Anda membuat, mengelola, dan melacak pesanan pelanggan — dari checkout hingga pembayaran hingga pemenuhan. Anda membangun antarmuka pengguna keranjang; modul ini mengubah keranjang menjadi pesanan, menampilkan total (diskon, kupon, bonus), melacak status, dan menangani permintaan pengembalian dana.

Pesanan disimpan di dalam penyimpanan pesanan (wadah yang Anda konfigurasi di panel admin) dan dirujuk oleh penanda penyimpanan. Pembayaran didelegasikan ke gateway yang dikonfigurasi untuk akun pembayaran yang dipilih — lihat modul Pembayaran.

🚀 Memulai dengan Cepat​

Inisialisasi modul dari defineOneEntry:


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

Buat pesanan di penyimpanan dan baca kembali hasilnya (autentikasi diperlukan):

// Create an order in the "order_storage_1" storage.
const order = await Orders.createOrder("order_storage_1", {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [{ productId: 2957, quantity: 2 }],
});

console.log(order.id, order.totalSum, order.statusIdentifier);
// 179 "300.00" "inProgress"

✨ Konsep Kunci​

Apa itu Pesanan?​

Pesanan adalah transaksi pembelian pelanggan. Setiap objek pesanan membawa:

  • id — pengidentifikasi pesanan
  • storageId — penyimpanan pesanan yang dimiliki
  • formIdentifier / formData — formulir pesanan dan data yang diajukan pelanggan
  • products — item baris (productId, quantity, price, …)
  • totalSum / currency — total pesanan dan mata uang
  • paymentAccountIdentifier — akun pembayaran yang dipilih
  • paymentUrl — tautan checkout gateway (atau null)
  • statusIdentifier / isCompleted — status saat ini
  • createdDate — cap waktu

Struktur Pesanan​

{
  id: 179,
  storageId: 1,
  createdDate: '2025-07-03T00:43:02.908Z',
  statusIdentifier: 'inProgress',
  formIdentifier: 'orderForm',
  formData: [
    { marker: 'order_name', type: 'string', value: 'Ivan' }
  ],
  attributeSetIdentifier: 'order_form',
  totalSum: '300.00',
  currency: 'USD',
  paymentAccountIdentifier: 'cash',
  paymentAccountLocalizeInfos: { title: 'Cash' },
  paymentUrl: null,
  products: [
    {
      id: 2957,
      title: 'Cosmo',
      sku: null,
      previewImage: null,
      price: 150,
      quantity: 2,
      isGift: false,
    },
  ],
  isCompleted: true,
}

Penyimpanan pesanan vs. pesanan individu​

Penyimpanan pesanan adalah wadah yang mengelompokkan pesanan terkait (misalnya, pesanan dari formulir atau saluran penjualan tertentu). Pesanan individu adalah transaksi aktual di dalam penyimpanan. Anda mengakses penyimpanan dengan penandanya dan pesanan di dalamnya dengan penanda + id.

Status Pesanan​

Setiap penyimpanan mendefinisikan set statusnya sendiri; status saat ini dari pesanan ada di statusIdentifier. Ambil status yang tersedia untuk penyimpanan dengan getAllStatusesByStorageMarker(), dan perbarui status pesanan dengan updateOrderByMarkerAndId().

📋 Apa yang Perlu Anda Ketahui​

Pesanan dibangun dari data keranjang​

Anda menyediakan data formulir pesanan dan item baris; OneEntry menghitung total. Untuk membuat pesanan, Anda mengirimkan:

  1. formIdentifier — formulir pesanan
  2. formData — bidang formulir yang diajukan pelanggan
  3. products — item baris (productId, quantity, signedPrice opsional)
  4. paymentAccountIdentifier — cara pelanggan akan membayar

Apa yang dilakukan dan tidak dilakukan modul ini​

  • ✅ Membuat pesanan dari data keranjang, menampilkan total, memperbarui status, mengelola permintaan pengembalian dana
  • ✅ Mendelegasikan pembayaran ke gateway melalui sesi pembayaran / paymentUrl
  • ❌ Tidak menyediakan antarmuka pengguna keranjang belanja — Anda yang membangunnya
  • ❌ Tidak menyimpan data kartu mentah — pembayaran ditangani oleh gateway

Pengembalian Dana​

Penanganan pengembalian dana berada di modul Orders: minta pengembalian dana dengan createRefundRequest(), daftar permintaan pengembalian dana pesanan dengan getRefunds(), dan batalkan satu dengan cancelRefundRequest().

📊 Tabel Referensi Cepat​

MetodeDeskripsi
createOrder() 🔐Membuat pesanan baru
getAllOrdersByMarker() 🔐Mendapatkan semua pesanan untuk sebuah penyimpanan (terpaginasi)
getOrdersStorageByMarker() 🔐Mendapatkan satu objek penyimpanan pesanan berdasarkan penanda.
getAllOrdersStorage() 🔐Mendapatkan semua objek penyimpanan pesanan.
getOrderByMarkerAndId() 🔐Mendapatkan satu pesanan berdasarkan penanda dan id dari objek penyimpanan pesanan yang dibuat oleh pengguna.
updateOrderByMarkerAndId() 🔐Memperbarui satu pesanan berdasarkan penanda dan id dari objek penyimpanan pesanan yang dibuat oleh pengguna.
previewOrder() 🔐Menampilkan total pesanan, diskon, dan kupon sebelum membuatnya.
getAllStatusesByStorageMarker()Mendapatkan semua status pesanan untuk sebuah penanda penyimpanan.
getRefunds()Mendapatkan semua permintaan pengembalian dana untuk sebuah pesanan.
createRefundRequest()Membuat permintaan pengembalian dana untuk sebuah pesanan.
cancelRefundRequest()Membatalkan permintaan pengembalian dana untuk sebuah pesanan.

🔐 = Memerlukan otorisasi

Harga produk tetap (signedPrice)​

signedPrice adalah token yang ditandatangani yang mengunci harga produk. Ketika ada di baris pesanan, server mengenakan harga tetap yang tepat itu alih-alih mencari harga lagi — jadi jumlah yang dilihat pelanggan di katalog atau keranjang adalah jumlah yang mereka bayar.

signedPrice — tipe string

Harga yang ditandatangani dari produk diperoleh bersama dengan data produk ketika signPrice diatur.

Dari mana mendapatkannya​

Anda tidak menghasilkan signedPrice sendiri — itu datang di dalam data produk, tetapi hanya ketika Anda meminta produk dengan parameter signPrice diatur ke penanda penyimpanan pesanan Anda:

  • Modul Produk — kirim signPrice dalam userQuery (getProducts, getProductsByPageUrl, …).
  • Modul Blocks — kirim signPrice sebagai argumen metode rekomendasi (getCartSimilar, getRecentlyViewed, …).

Setiap produk yang dikembalikan kemudian berisi string signedPrice. Baca lebih lanjut di bagian Memperbaiki harga (signPrice) dari Modul Produk.

Cara menggunakannya​

Kirimkan token kembali di setiap produk dari tubuh createOrder(). Pesanan kemudian mempertahankan harga tetap:


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

const body = {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [
    {
      productId: items[0].id,
      quantity: 2,
      signedPrice: items[0].signedPrice
    }
  ]
};

const order = await Orders.createOrder("my-order", body);

Jika Anda mengabaikan signedPrice, pesanan dibuat dengan harga produk saat ini pada waktu checkout.

❓ Pertanyaan Umum (FAQ)​

Bagaimana cara membuat pesanan dengan beberapa produk?​

Kirimkan array objek produk di bidang products dari tubuh pesanan. Setiap item memerlukan productId dan quantity (dan opsional signedPrice). Total jumlah dihitung secara otomatis.

Bisakah saya memperbarui pesanan setelah dibuat?​

Ya — gunakan updateOrderByMarkerAndId() untuk memodifikasi detail pesanan seperti status, data formulir, atau produk. Hati-hati saat mengubah item atau total setelah pembayaran sedang diproses.

Bagaimana cara melacak perubahan status pesanan?​

Baca bidang statusIdentifier untuk status saat ini, dan ambil status yang tersedia dari penyimpanan dengan getAllStatusesByStorageMarker(). Anda juga dapat menggunakan modul Events untuk bereaksi terhadap perubahan.

Apa perbedaan antara penyimpanan pesanan dan pesanan individu?​

Penyimpanan pesanan adalah wadah yang mengelompokkan pesanan terkait (misalnya, pesanan dari formulir atau saluran penjualan tertentu). Pesanan individu adalah transaksi di dalam penyimpanan tersebut. Gunakan penanda untuk mengidentifikasi dan mengatur penyimpanan.

Bagaimana cara menangani pembatalan dan pengembalian dana pesanan?​

Perbarui status pesanan dengan updateOrderByMarkerAndId(). Untuk pengembalian dana, gunakan metode pengembalian dana Orders: createRefundRequest() untuk meminta satu, getRefunds() untuk mendaftar permintaan pesanan, dan cancelRefundRequest() untuk membatalkan satu.

🎓 Praktik Terbaik​

  • Pratinjau sebelum membuat — panggil previewOrder() untuk menunjukkan diskon, kupon, dan bonus dalam ringkasan checkout.
  • Gunakan signedPrice ketika produk masuk ke checkout sehingga harga tidak berubah antara menjelajah dan memesan.
  • Autentikasi terlebih dahulu — metode pembuatan/membaca/memperbarui pesanan memerlukan pengguna yang terotorisasi (lihat AuthProvider).
  • Paginasi daftar pesanan (offset + limit) — jangan memuat setiap pesanan sekaligus.
  • Rujuk penyimpanan dan formulir dengan penanda, bukan dengan nama tampilan — penanda bersifat stabil.

🔗 Dokumentasi Terkait​