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.
Roadmap1. 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 implementeduntuk 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_targetmenentukan 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.
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.

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. Berisiwoocommerceataushopify. Bila dikosongkan, sistem menyimpulkannya daristore_url. - Consumer Key / API Access Token (
api_key) — wajib, disimpan sebagai kredensial terenkripsi. Untuk WooCommerce berisi pasangan kuncick_...; untuk Shopify berisi tokenshpat_.... - 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:

3. Panduan Langkah-demi-Langkah
Alur penyiapan terbagi menjadi dua fase: menyiapkan kredensial baca di sisi platform toko, lalu mendaftarkan koneksi di DagangBot.
- 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_...) danConsumer secret(cs_...). Salin keduanya sebelum meninggalkan halaman, karena rahasia hanya ditampilkan satu kali. - 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 awalanshpat_. Token ini hanya tampil satu kali; simpan di tempat aman sebelum menutup halaman. - 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
Langkah 4: Pilih Sasaran Data
Tentukan nilai
sync_targetsebelum tarikan besar pertama. Pilihancatalog_onlymengisi tabel produk saja,knowledge_onlymengirim hasil ke staging basis pengetahuan saja, danbothmenjalankan keduanya. Nilai bawaan bila ruas ini kosong adalahboth. Untuk merchant yang hanya ingin memperkaya jawaban AI tanpa membuka pemesanan produk,knowledge_onlyadalah pilihan yang paling hemat. - 5
Langkah 5: Jalankan Sinkronisasi
Tekan tombol Sinkronkan Sekarang, atau panggil titik akhir
POST /api/v1/integrations/{id}/syncdari perangkat Anda. Sistem memuat konfigurasi integrasi di dalam transaksi tenant, memastikan integrasi berstatus aktif, memastikan tipe integrasi bernilaiecommerce, lalu menarik seluruh halaman produk dari platform toko. Respons akan memuat jumlah produk yang terbaca serta jumlah baris yang disisipkan, diperbarui, dan distaging. - 6
Langkah 6: Verifikasi Hasil
Periksa kolom Last Sync At dan pesan hasil pada kartu integrasi. Bila jumlah
stagedbernilai nol pada tarikan pertama, periksa kembali nilaisync_target: konfigurasicatalog_onlymemang tidak mengirim dokumen apa pun ke basis pengetahuan.
4. Parameter & Spesifikasi Teknis
Ruas Konfigurasi
Nilai platform dan sync_target dinormalkan menjadi huruf kecil dan dipangkas sebelum dipakai, sehingga WooCommerce dan woocommerce diperlakukan sama.
Titik Akhir
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
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:
- WooCommerce — SKU diambil apa adanya dari respons. Bila kosong, identitas produk jatuh ke
ExternalID, lalu ke nama produk. - Shopify tanpa varian — SKU dibentuk sebagai
shopify-<product_id>dan harga disetel nol karena harga berada di tingkat varian. - 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 bertajukDefault 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 dengansheets,database,rest_api, danredmine. Filter sumber di halaman sumber pengetahuan memakai tipe yang sama. Rincian alur tinjau dijelaskan pada Sumber Pengetahuan. - Persona AI. Ruas
target_servicesmenentukan 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
Daftar kode galat tingkat platform tersedia pada Daftar Galat.
7. Referensi Terkait
- Konsep Inti untuk gambaran tenant, cabang, dan isolasi data.
- Google Sheets sebagai jalur impor katalog tanpa kredensial API.
- Sumber Pengetahuan untuk alur tinjau rekaman staging.
- Basis Pengetahuan untuk pemanfaatan dokumen pada jawaban AI.
- Konfigurasi Webhook untuk penerusan perubahan katalog ke sistem mitra.
- Daftar Galat untuk daftar kode kesalahan platform.
