Lompat ke konten utama
RoadmapTerakhir diperbarui: 9 Okt 2026, 09.28

Integrasi E-Commerce

Konektor e-commerce menarik katalog produk dari toko daring pihak ketiga dan memasukkan hasilnya ke DagangBot. Arah data bersifat satu arah: DagangBot membaca, platform toko tidak pernah menerima penulisan data dari DagangBot.

Roadmap

1. Ikhtisar & Nilai Bisnis

DagangBot mendukung dua platform toko pada jalur konektor ini: WooCommerce (REST API v3) dan Shopify (Admin API versi 2024-01). Platform lain ditolak di tahap validasi dengan pesan platform '<nama>' belum didukung saat ini (dukungan saat ini: woocommerce, shopify). Penentuan platform dilakukan dari ruas isian platform; bila ruas itu dibiarkan kosong, sistem menyimpulkan sendiri dari store_url — host yang memuat myshopify.com diperlakukan sebagai Shopify, sisanya dianggap WooCommerce.

Nilai bisnis utama konektor ini:

  • Katalog tunggal sebagai sumber jawaban AI. Produk hasil tarikan menjadi data produk yang dipakai modul penjualan sekaligus menjadi dokumen staging untuk Retrieval-Augmented Generation (RAG). Chatbot menjawab stok dan harga dari data yang baru ditarik, bukan dari salinan manual yang basi.
  • Operasi baca-saja (read-only). DagangBot hanya memanggil titik akhir daftar produk. Tidak ada pembuatan pesanan, tidak ada penulisan stok, dan tidak ada perubahan harga yang dikirim balik ke toko. Fungsi dorong pesanan memang belum diimplementasikan dan mengembalikan galat external order push not yet implemented untuk kedua platform.
  • Upsert berbasis identitas. Produk lama dikenali melalui SKU, atau melalui nama produk bila SKU kosong. Produk yang belum ada disisipkan, produk yang sudah ada diperbarui. Tidak ada duplikasi baris pada tarikan berulang.
  • Rute keluaran yang bisa dipilih. Ruas sync_target menentukan apakah hasil tarikan masuk ke katalog produk, ke staging basis pengetahuan, atau ke keduanya.
  • Isolasi tenant. Seluruh pembacaan integrasi, penulisan produk, dan pencatatan staging dijalankan di dalam transaksi ber-tenant, sehingga katalog satu merchant tidak pernah tercampur dengan merchant lain.
Status Antarmuka: Belum Dirilis

Kartu integrasi e-commerce di dasbor saat ini memakai penanda comingSoon: true dan disabled: true. Formulir konfigurasinya sudah tersedia di kode, tetapi kartu layanan belum dapat dipakai dari antarmuka pengguna. Untuk kebutuhan katalog sementara, gunakan konektor Google Sheets atau REST API.

2. Alur Visual & Antarmuka

Kartu layanan e-commerce muncul pada tab integrasi bersama konektor lain. Gambar berikut memperlihatkan penanda status yang tampil pada kartu tersebut.

Kartu integrasi Toko Mandiri dan Marketplace E-Commerce di dasbor DagangBot
Kartu integrasi E-Commerce menampilkan penanda status kemitraan resmi dan panduan sinkronisasi katalog multi-toko.

Formulir konfigurasi memuat empat ruas isian yang berbeda peran:

  • URL Website Toko (store_url) — wajib. Menyimpan alamat lengkap toko termasuk skema HTTPS. Nilai ini dipakai sebagai basis seluruh pemanggilan API.
  • Platform Toko (platform) — wajib. Berisi woocommerce atau shopify. Bila dikosongkan, sistem menyimpulkannya dari store_url.
  • Consumer Key / API Access Token (api_key) — wajib, disimpan sebagai kredensial terenkripsi. Untuk WooCommerce berisi pasangan kunci ck_...; untuk Shopify berisi token shpat_....
  • Consumer Secret (api_secret) — khusus WooCommerce. Boleh dikosongkan saat memakai Shopify.

Selain ruas di atas, lapisan layanan juga membaca nama kredensial alternatif agar cocok dengan konfigurasi lama: consumer_key, consumer_secret, access_token, serta padanan yang berada di dalam blok config bila kredensial terenkripsi belum tersedia.

Setelah konfigurasi tersimpan, tabel integrasi menampilkan kolom Last Sync At. Penekanan tombol Sinkronkan Sekarang mengirim permintaan ke POST /api/v1/integrations/{id}/sync; responsnya berisi fetched, inserted, updated, staged, dan message. Nilai-nilai itulah yang menjadi dasar ringkasan hasil tarikan di antarmuka katalog produk:

Tabel katalog produk DagangBot berisi hasil sinkronisasi konektor e-commerce
Tabel katalog produk menampilkan entri hasil tarikan konektor beserta harga dan status stok terakhir.

3. Panduan Langkah-demi-Langkah

Alur penyiapan terbagi menjadi dua fase: menyiapkan kredensial baca di sisi platform toko, lalu mendaftarkan koneksi di DagangBot.

  1. 1

    Langkah 1: Terbitkan Kunci Baca WooCommerce

    Masuk ke dasbor WordPress toko Anda, buka menu WooCommerce, lalu pilih Settings dan tab Advanced. Buka sub-tab REST API dan tekan Add key. Isi deskripsi kunci, pilih pengguna dengan hak baca katalog, dan setel izin (permissions) ke Read. Sistem akan menampilkan dua string: Consumer key (ck_...) dan Consumer secret (cs_...). Salin keduanya sebelum meninggalkan halaman, karena rahasia hanya ditampilkan satu kali.

  2. 2

    Langkah 2: Terbitkan Token Admin Shopify

    Di panel Shopify, buat aplikasi khusus pada halaman pengembangan aplikasi. Berikan cakupan izin baca produk (read_products) dan inventaris (read_inventory). Setelah aplikasi terpasang pada toko, Shopify menampilkan Admin API access token dengan awalan shpat_. Token ini hanya tampil satu kali; simpan di tempat aman sebelum menutup halaman.

  3. 3

    Langkah 3: Daftarkan Koneksi di DagangBot

    Buka menu Integrations di dasbor DagangBot dan pilih kartu e-commerce. Isi nama integrasi, store_url, platform, serta salah satu pasangan kredensial sesuai platform toko. Bila integrasi ditujukan untuk satu cabang tertentu, pilih cabang pada ruas yang tersedia. Simpan konfigurasi, lalu tekan Test Connection agar sistem memanggil titik akhir pemeriksaan platform sebelum sinkronisasi penuh dijalankan.

  4. 4

    Langkah 4: Pilih Sasaran Data

    Tentukan nilai sync_target sebelum tarikan besar pertama. Pilihan catalog_only mengisi tabel produk saja, knowledge_only mengirim hasil ke staging basis pengetahuan saja, dan both menjalankan keduanya. Nilai bawaan bila ruas ini kosong adalah both. Untuk merchant yang hanya ingin memperkaya jawaban AI tanpa membuka pemesanan produk, knowledge_only adalah pilihan yang paling hemat.

  5. 5

    Langkah 5: Jalankan Sinkronisasi

    Tekan tombol Sinkronkan Sekarang, atau panggil titik akhir POST /api/v1/integrations/{id}/sync dari perangkat Anda. Sistem memuat konfigurasi integrasi di dalam transaksi tenant, memastikan integrasi berstatus aktif, memastikan tipe integrasi bernilai ecommerce, lalu menarik seluruh halaman produk dari platform toko. Respons akan memuat jumlah produk yang terbaca serta jumlah baris yang disisipkan, diperbarui, dan distaging.

  6. 6

    Langkah 6: Verifikasi Hasil

    Periksa kolom Last Sync At dan pesan hasil pada kartu integrasi. Bila jumlah staged bernilai nol pada tarikan pertama, periksa kembali nilai sync_target: konfigurasi catalog_only memang tidak mengirim dokumen apa pun ke basis pengetahuan.

4. Parameter & Spesifikasi Teknis

Ruas Konfigurasi

Ruas Wajib Keterangan
store_url Ya Basis URL toko. Spasi di ujung dipangkas otomatis; tanda garis miring di akhir dibuang oleh klien HTTP.
platform Tidak woocommerce atau shopify. Kosong berarti disimpulkan dari store_url.
api_key Ya Kunci WooCommerce (ck_...) atau token akses Shopify (shpat_...). Disimpan sebagai kredensial terenkripsi.
api_secret WooCommerce Consumer secret (cs_...). Boleh kosong untuk Shopify.
access_token Shopify Alternatif penamaan token akses. Dibaca dari kredensial atau dari blok config.
sync_target Tidak catalog_only, knowledge_only, atau both. Bawaan both.
target_services Tidak Daftar persona penerima dokumen staging. Bila kosong, seluruh persona menerima (all).

Nilai platform dan sync_target dinormalkan menjadi huruf kecil dan dipangkas sebelum dipakai, sehingga WooCommerce dan woocommerce diperlakukan sama.

Titik Akhir

Operasi Rute Izin RBAC
Daftar integrasi GET /api/v1/integrations integrations:read
Simpan/perbarui konfigurasi POST /api/v1/integrations integrations:create atau integrations:update
Uji koneksi POST /api/v1/integrations/test/{kind} integrations:create
Jalankan sinkronisasi POST /api/v1/integrations/{id}/sync integrations:update
Hapus integrasi DELETE /api/v1/integrations/{id} integrations:delete
Lihat Egress IP GET /api/v1/integrations/egress-ip integrations:read

Handler sinkronisasi membaca tipe integrasi lebih dahulu. Tipe yang tidak dikenali mengembalikan galat bertanda SYNC_UNSUPPORTED; kegagalan di dalam proses tarikan dipetakan menjadi SYNC_FAILED dengan status HTTP 400.

Perilaku Pengambilan Data

Platform Titik akhir Penomoran halaman
WooCommerce GET <store_url>/wp-json/wc/v3/products Parameter per_page dan page, dilanjutkan selama halaman penuh.
Shopify GET <store_url>/admin/api/2024-01/products.json Parameter limit=250, dilanjutkan mengikuti tajuk Link dengan relasi next.

Kedua klien memakai netguard.SafeHTTPClient dengan batas waktu 25 detik yang juga menolak target alamat internal. Pada lingkungan pengembangan, daftar host yang diizinkan diperluas ke 127.0.0.1 dan localhost agar pengujian lokal dapat dilakukan tanpa melemahkan pengaman produksi.

Pemetaan produk hasil tarikan mengikuti aturan berikut:

  1. WooCommerce — SKU diambil apa adanya dari respons. Bila kosong, identitas produk jatuh ke ExternalID, lalu ke nama produk.
  2. Shopify tanpa varian — SKU dibentuk sebagai shopify-<product_id> dan harga disetel nol karena harga berada di tingkat varian.
  3. Shopify dengan varian — setiap varian menjadi satu baris tersendiri dengan SKU dari varian; varian tanpa SKU memakai pola shopify-<product_id>-<variant_id>, dan nama digabung sebagai <judul produk> - <judul varian> kecuali varian bertajuk Default Title. Deskripsi HTML dibersihkan menjadi teks biasa sebelum disimpan.

Penulisan ke Katalog dan Staging

upsertProducts melakukan satu kueri pencarian massal atas seluruh SKU dan nama yang dibawa satu batch, lalu mengklasifikasikan tiap produk sebagai sisipan atau pembaruan. Hasilnya dilaporkan pada ruas inserted dan updated.

stageProductRecords menulis ke tabel integration_records dengan source_type bernilai ecommerce. Setiap rekaman memuat teks hasil render, sidik jari SHA-256 dari teks itu, dan ID batch. Bila sidik jari dan isi tidak berubah, rekaman lama dianggap masih segar sehingga tidak dihitung sebagai perubahan. Setelah seluruh rekaman batch ditulis, sistem menjalankan rekonsiliasi anti-yatim: rekaman lama yang tidak muncul pada batch terbaru ditandai is_deleted = true, berstatus archived, dan potongan dokumennya dinonaktifkan. Rekaman yang berstatus training dikecualikan dari rekonsiliasi ini.

Kegagalan pada jalur staging bersifat tidak fatal. Kesalahan dicatat sebagai peringatan pada log layanan, sementara jalur katalog tetap dianggap berhasil dan last_sync_at tetap diperbarui.

5. Integrasi & Relasi

  • Katalog produk. Produk hasil tarikan masuk ke tabel produk kanonik dan langsung dipakai modul penjualan untuk menyusun keranjang serta menjawab ketersediaan barang. Lihat Basis Pengetahuan untuk gambaran pemanfaatan dokumen.
  • Sumber pengetahuan. Rekaman staging muncul di daftar sumber data dengan tipe ecommerce, sejajar dengan sheets, database, rest_api, dan redmine. Filter sumber di halaman sumber pengetahuan memakai tipe yang sama. Rincian alur tinjau dijelaskan pada Sumber Pengetahuan.
  • Persona AI. Ruas target_services menentukan persona mana yang menerima dokumen hasil tarikan. Pengaturan ini mencegah katalog toko satu merek bocor ke persona layanan yang tidak berkepentingan.
  • Cabang. Integrasi dapat diikat ke satu cabang atau dibiarkan global pada tingkat tenant. Produk hasil tarikan mewarisi cakupan cabang yang sama, mengikuti pola pada Operasional Cabang.
  • Webhook keluar. Perubahan katalog dapat diteruskan ke sistem mitra melalui kait webhook yang sudah ada. Format muatan dan verifikasi tanda tangan dijelaskan pada Konfigurasi Webhook.
  • Konektor alternatif. Untuk katalog yang masih dikelola manual di spreadsheet, Google Sheets menyediakan jalur impor tanpa kredensial API. Untuk sumber data yang tidak tercakup keduanya, gunakan REST API.
  • Jejak aktivitas. Setiap penekanan tombol sinkronisasi tercatat bersama aksi administrasi lain pada Log Aktivitas.

6. Pemecahan Masalah

Gejala Sebab Penanganan
integrasi tidak aktif Integrasi dinonaktifkan di dasbor. Aktifkan kembali integrasi sebelum menjalankan sinkronisasi.
tipe integrasi tidak sesuai: <tipe> (diharapkan ecommerce) Tipe integrasi tersimpan bukan ecommerce. Perbarui konfigurasi lewat formulir integrasi standar; jalur lama yang menulis tipe ecommerce_<platform> tidak terhubung ke handler sinkronisasi.
URL toko (store_url) belum diisi Ruas store_url kosong setelah pemangkasan spasi. Isi URL lengkap beserta skema HTTPS.
Consumer/API Key WooCommerce belum diisi Kunci ck_... tidak terbaca pada kredensial maupun konfigurasi. Simpan ulang kredensial konektor.
Consumer Secret WooCommerce belum diisi Rahasia cs_... tidak tersedia padahal platform bernilai WooCommerce. Isi ruas api_secret.
Access Token Shopify belum diisi Token shpat_... tidak tersedia. Terbitkan token baru dan simpan sebagai api_key atau access_token.
platform '<nama>' belum didukung saat ini ... Nilai platform di luar daftar yang didukung. Isi woocommerce atau shopify, atau kosongkan agar sistem menyimpulkan dari store_url.
tidak ada produk yang terbaca dari <platform> Toko mengembalikan daftar kosong, atau kunci tidak berizin baca katalog. Periksa izin kunci dan pastikan toko memiliki produk yang dipublikasikan.
invalid api credentials or unauthorized (HTTP 401/403) Kredensial salah, kedaluwarsa, atau dicabut. Terbitkan ulang kredensial dan simpan kembali.
cannot reach store Koneksi ke toko gagal, sering karena firewall toko membatasi akses masuk. Izinkan alamat keluar DagangBot. Nilai yang perlu diizinkan dapat dibaca dari GET /api/v1/integrations/egress-ip.
Sinkronisasi sukses tetapi basis pengetahuan tidak bertambah sync_target bernilai catalog_only. Ubah ke both atau knowledge_only lalu sinkronkan ulang.
Produk lama hilang dari basis pengetahuan setelah tarikan Rekonsiliasi menandai rekaman yang tidak lagi dikirim toko sebagai archived. Pastikan produk masih dipublikasikan di platform toko sebelum menekan sinkronisasi.

Daftar kode galat tingkat platform tersedia pada Daftar Galat.

7. Referensi Terkait

content/docs/integrations/ecommerce.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot