Google Sheets Connector
Integrasi Google Sheets memungkinkan Anda mengelola katalog produk, mengubah harga, dan menyesuaikan stok langsung melalui antarmuka spreadsheet standar tanpa perlu masuk ke dasbor DagangBot setiap kali ada perubahan.
Stable1. Ikhtisar & Nilai Bisnis
Dalam ekosistem perdagangan digital, usaha kecil hingga menengah (UKM) sering kali menjadikan Google Sheets sebagai basis data utama mereka. Pembuatan konektor Google Sheets pada platform DagangBot v3 dirancang secara spesifik untuk menjembatani jurang antara alat operasional sehari-hari dengan kecerdasan buatan, memungkinkan otomatisasi layanan pelanggan tanpa memaksa pedagang mengubah alur kerja (workflow) yang sudah terbukti efisien. Melalui pendekatan sinkronisasi pasif ini, setiap perubahan sel di dalam spreadsheet dapat direfleksikan menjadi respons instan chatbot WhatsApp.
Nilai bisnis utama yang dihadirkan oleh konektor ini meliputi:
- Manajemen Sumber Kebenaran Tunggal (Single Source of Truth): Anda atau tim admin dapat mengubah harga, memperbaiki jumlah stok, menghentikan penjualan produk sementara, hingga menambah varian baru langsung di Google Sheets. Seluruh anggota tim dapat berkolaborasi di dalam spreadsheet secara real-time, dan pembaruan tersebut akan diserap oleh bot tanpa intervensi teknis.
- Baca-Saja yang Aman (Read-Only Sempurna): Pendekatan koneksi ini beroperasi dalam mode murni baca (read-only). DagangBot menarik data melalui protokol HTTP GET ke titik akhir ekspor CSV publik milik Google. Platform sama sekali tidak meminta izin otorisasi tingkat lanjut (seperti OAuth 2.0 atau Google Sign-In), tidak menyimpan token kredensial Google, dan secara fisik tidak memiliki akses tulis ke akun Google Drive Anda. Risiko korupsi data atau penghapusan file dari sisi DagangBot adalah nol.
- Otomasi Upsert Cerdas dan Resolusi Konflik: Platform ini dilengkapi dengan parser mandiri yang mampu membedakan operasi penambahan (insert) dan pembaruan (update). Algoritma resolusi mendeteksi keberadaan produk melalui pencocokan identitas SKU atau nama. Bila data sudah ada di platform DagangBot, parameter seperti stok, deskripsi, dan harga akan ditimpa; bila belum ada, produk baru akan dibuat.
- Isolasi Multi-Cabang (Multi-Branch Support): Bagi skala enterprise atau franchise yang beroperasi di banyak cabang, produk yang disinkronisasi melalui konektor ini secara otomatis mewarisi parameter relasi cabang (
branch_id). Anda dapat menghubungkan Spreadsheet Katalog Jakarta ke Cabang Jakarta, dan Spreadsheet Katalog Bandung ke Cabang Bandung, mencegah kebocoran informasi inventaris antar-wilayah. - Transmisi Fleksibel (Katalog vs Basis Pengetahuan): Pengguna memiliki kendali penuh kemana aliran data bermuara. Sinkronisasi dapat diarahkan secara khusus menjadi database produk terstruktur (untuk di-checkout ke keranjang belanja), menjadi dokumen basis pengetahuan Retrieval-Augmented Generation (RAG) untuk melatih AI agar fasih menjawab FAQ, atau keduanya sekaligus secara serempak.
Mengingat desain operasi adalah baca-saja (read-only), DagangBot tidak dapat merekam transaksi yang terjadi di WhatsApp kembali ke Google Sheets. Pesanan, pengurangan stok otomatis setelah transaksi, dan pencatatan invoice tidak di-push sebagai baris baru di spreadsheet. Untuk kebutuhan manajemen pesanan dua arah, disarankan beralih ke Integrasi Konektor E-Commerce atau Webhook.
2. Alur Visual & Antarmuka
Proses penyiapan dikemas seringkas mungkin. Anda hanya perlu menyiapkan dokumen di lingkungan Google Drive, membuka perizinan akses tautan, lalu menempelkan tautan tersebut ke dalam dasbor manajemen platform DagangBot.

Begitu link publik Google Sheets siap, buka modal konfigurasi integrasi Google Sheets di dasbor DagangBot untuk menempelkan URL Spreadsheet:

3. Panduan Langkah-demi-Langkah
Berikut merupakan prosedur komprehensif dari hulu ke hilir untuk mengamankan kelancaran impor data massal pertama Anda.
- 1
Langkah 1: Siapkan Struktur Google Spreadsheet
Buat dokumen Google Spreadsheet baru atau gunakan file inventaris yang sudah berjalan. DagangBot sengaja didesain untuk mentolerir keberagaman struktur kolom. Anda tidak harus meletakkan nama kolom di urutan tertentu (misalnya, SKU harus di kolom A). Mesin parser akan memindai maksimal 30 baris teratas untuk mendeteksi header tabel.
Syarat mutlak header adalah keberadaan kolom berlabel
SKU(opsional tapi sangat disarankan) dan turunan nama untuk produk (sepertiNama Produk,Product Name, atauNama). Isikan data katalog secara berurutan ke bawah. Hindari menyisipkan baris kosong di sela-sela data produk karena hal ini bisa diinterpretasikan sebagai akhir dari jangkauan tabel (end-of-file dinamis). - 2
Langkah 2: Hindari Format Sel yang Mengganggu
Sebelum membuka akses ke publik, pastikan tipe data angka terbebas dari format teks mata uang yang rumit. Kolom
HargadanStokharus diisi dengan angka bulat absolut. Sebagai contoh, tulis150000dan bukanRp 150.000,-. Jika Anda menggunakan penanda titik atau koma untuk pemisah ribuan, sistem mungkin secara keliru menganggapnya sebagai format desimal yang salah atau membuangnya ke nilai0. Format teks (Plain Text) adalah tipe data yang paling aman untuk segala kolom, termasuk SKU yang sering kali mengandung angka diawali nol (seperti00234). - 3
Langkah 3: Setel Izin Berbagi ke Viewer Publik
Dari dalam jendela Google Spreadsheet Anda yang sedang aktif:
- Klik tombol Share (Bagikan) berwarna biru di pojut kanan atas layar.
- Di dalam panel General Access, klik menu tarik-turun yang biasanya bertuliskan "Restricted" dan ubah menjadi "Anyone with the link" (Siapa saja yang memiliki tautan).
- Di sisi kanannya, pastikan status peran yang terpilih adalah "Viewer" (Pelihat). Dilarang keras menggunakan pengaturan "Editor" karena URL ini akan disalin ke aplikasi pihak ketiga.
- Klik Copy link, kemudian tekan Done. Tautan telah tersimpan di clipboard perangkat Anda.
- 4
Langkah 4: Daftarkan Tautan di Dasbor DagangBot
Navigasikan web browser Anda ke platform DagangBot. Pastikan Anda memiliki otorisasi ganda (RBAC) dengan permission
integrations:createdanintegrations:update.- Masuk ke menu Integrations (Integrasi).
- Temukan kartu layanan Google Sheets dan klik tombol tambah integrasi baru.
- Beri nama integrasi (misalnya: "Katalog Baju Lebaran").
- Pada dropdown cabang, tentukan apakah integrasi ini untuk Tenant Global (semua cabang) atau didedikasikan untuk cabang spesifik.
- Tempel URL yang disalin pada Langkah 3 ke dalam isian Spreadsheet URL.
- Tentukan Sync Target atau sasaran injeksi data (pembahasan detail ada di sesi Spesifikasi Teknis).
- Simpan konfigurasi. Sistem akan melakukan ping HTTP GET seketika untuk memvalidasi aksesibilitas publik dari tautan tersebut.
- 5
Langkah 5: Praktik Manajemen Stok (Penghapusan vs Nonaktif)
Penting untuk dipahami bahwa algoritma upsert milik DagangBot berpusat pada pembaruan (update) dan penyisipan (insert). Sistem tidak menghapus produk dari database DagangBot hanya karena baris tersebut dihapus dari Google Sheets. Mekanisme ini disengaja untuk mencegah kehilangan keranjang belanja klien atau merusak integritas riwayat pesanan yang sudah mencatatkan Foreign Key ke ID produk tersebut.
Jika Anda berhenti menjual sebuah barang (diskontinu), jangan hapus baris produk dari Google Sheets. Cukup ubah nilai kolom
Stokmenjadi0. Saat sinkronisasi berjalan, DagangBot akan membaca angka0ini dan secara otomatis mengubah status is_active produk menjadifalse, sehingga produk ditarik dari etalase chatbot secara anggun. - 6
Langkah 6: Pemantauan Siklus Sinkronisasi
Anda dapat menekan tombol Sinkronkan Sekarang untuk memaksa tarikan data saat itu juga. Untuk kegiatan operasional rutin, DagangBot menjalankan jadwal cron job asinkron di belakang layar yang akan memperbarui etalase bot secara berkala tanpa memerlukan klik manual dari administrator. Riwayat dan timestamp tarikan data terakhir ditampilkan di kolom Last Sync At pada tabel integrasi.
4. Parameter & Spesifikasi Teknis
Keandalan mesin ingestion Google Sheets DagangBot ditopang oleh metode parsing format koma terpisah (CSV) adaptif. Berbeda dengan pendekatan API berbasis Google Cloud IAM yang kaku dan rawan kedaluwarsa, pemanfaatan titik akhir utilitas /export?format=csv memungkinkan ekstraksi masif berlatensi rendah.
Pemetaan Parameter (Kolom Adaptif)
Konektor commerce.NewGoogleSheetsClient membaca header tabel secara case-insensitive (mengabaikan huruf besar-kecil) dan mendukung serangkaian alias. Jika header yang ditemukan cocok dengan salah satu nilai dalam daftar pemetaan, kolom tersebut akan diadopsi sesuai peruntukannya.
Parser CSV di backend tidak hanya mendukung tabel baris tunggal konvensional. Ia juga memiliki dukungan laten untuk mendeteksi multi-row catalog card layout. Jika dalam pembacaan, baris di bawah produk memuat frasa kunci pola vertikal seperti "Harga: Rp 79.000", nilai tersebut akan diatribusikan ke produk induk di atasnya. Namun, untuk stabilitas mesin, Anda sangat direkomendasikan berpegang teguh pada tata letak kolom murni.
Mesin Anti-Pencemaran (Target Sinkronisasi)
Modul Integrasi memungkinkan Anda menetapkan sasaran akhir data. Konfigurasi sync_target menerima tiga enumerasi string:
catalog_only: Menyasar modul Order & Commerce. Data disalurkan penuh ke fungsiupsertProducts, menimpa atribut tabelproducts. Pengetahuan tidak diindeks ke AI.knowledge_only: Menyasar modul AI Assistant. Data produk diekstrak, diubah formatnya menjadi narasi paragraf melalui utilitasRendererFor("ecommerce"), dikemas, dan disuplai ke utilitas injeksistageProductRecords. Mesin vektor akan melakukan embedding atas perubahan hash SHA-256 (mencegah re-embedding pada teks yang sama persis) ke tabelintegration_recordsyang akan menyokong basis pengetahuan chatbot.both: Eksekusi transaksional ganda ke katalog relasional sekaligus repositori semantik vector space.
Algoritma Pembaruan (Upsert) & Transaksi Batch
Pada eksekusi internal, ConnectorService.upsertProducts memisahkan data menjadi dua keranjang kerja (updates dan inserts) untuk mereduksi beban komputasi I/O database. Algoritma resolusi identitas dijalankan dengan hierarki:
- Melakukan kompilasi seluruh larik SKU dan Nama dari kumpulan memori.
- Menjalankan single query mass lookup ke PostgreSQL
SELECT id, sku, lower(name) FROM products WHERE merchant_id = $1 AND (sku = ANY(...) OR lower(name) = ANY(...)). - Produk yang tersortir memiliki match di level SKU akan mendapatkan binding pembaruan data. Jika tidak ada SKU, kecocokan persis pada
lower(name)menjadi fallback lookup. - Semua parameter non-identitas (Nama (jika terikat via SKU), Deskripsi, Harga, Stok, dan Gambar) akan ditimpa penuh.
- Parameter Boolean
is_activesecara otomatis di-compute melalui operator logikaStock > 0. - Eksekusi dieksekusi melalui utilitas
pgx.Batch{}untuk mencegah deadlock pada pembaruan massal lebih dari 500 baris.
5. Relasi & Integrasi
Konektor Google Sheets beririsan dan bergantung secara ekstensif pada sejumlah subsistem mikro dalam ekologi DagangBot:
- Modul RBAC (Role-Based Access Control):
Untuk meregistrasi dan menghapus konektor, entitas agen pemanggil endpoint wajib meloloskan middleware perlindungan dengan kepemilikan permission
integrations:create,integrations:update, danintegrations:read. Akses baca juga berlaku dalam pengambilan log webhook bila status kegagalan sinkronisasi terjadi. - Isolasi Multi-Cabang (Multi-Branch):
Apabila struktur waralaba Anda mendikte katalog berbeda untuk setiap kota, konektor menyokong isolasi melalui kolom
branch_id. Sebuah produk yang dikawinkan dengan cabang tertentu (melalui kolombranch_idpada entitasintegrations) hanya akan merespons permintaan checkout pengguna WhatsApp yang dikelola oleh Omnichannel instance wilayah cabang tersebut. Ini dikunci ketat viaWHERE branch_id = COALESCE(...)di dalam query batching. - API Internal & Pemanggilan Asinkron: Konektor juga bertindak sebagai entitas API. Hal ini mempermudah sistem middleware eksternal (seperti perangkat lunak ERP dari Agensi White-Label) untuk melacak kesehatan modul atau memaksa sinkronisasi dengan payload REST secara otomatis.
Berikut adalah referensi blok eksekusi API untuk pembuatan dan penciptaan integrasi Google Sheets.
# Permintaan POST untuk menambahkan Google Sheets baru ke sistem
curl -X POST "https://dagangbot.web.id/api/v1/integrations" \
-H "Authorization: Bearer <TOKEN_JWT_ANDA>" \
-H "Content-Type: application/json" \
-d '{
"type": "sheets",
"name": "Katalog Utama Kosmetik",
"is_active": true,
"branch_id": null,
"config": {
"url": "https://docs.google.com/spreadsheets/d/1XyZABCDEFGHIJKL/edit?usp=sharing",
"sync_target": "both"
},
"credentials": {}
}'# Permintaan POST untuk memicu pembaruan instan asinkron (Force Sync)
curl -X POST "https://dagangbot.web.id/api/v1/integrations/<INTEGRATION_ID>/sync" \
-H "Authorization: Bearer <TOKEN_JWT_ANDA>" \
-d '{}'Payload JSON dari response sinkronisasi berhasil akan memperlihatkan rangkuman agregat seberapa banyak SKU yang terekstraksi dan ter-upsert sukses.
6. Pemecahan Masalah (Troubleshooting)
Insiden kegagalan komunikasi konektor sebagian besar bersumber dari kesalahan format tabel dan restriksi lapisan jaringan Google. Matriks di bawah menyajikan panduan diagnosis terarah.
7. Kode Error & Penanganan
Pada lapis terbawah perangkat lunak, log diagnostik konektor Google Sheets menyingkapkan sejumlah exception flags spesifik. Administrator atau pemelihara infrastruktur IT internal Agensi dapat menggunakan matriks log error ini sebagai pijakan debugging sebelum mengeskalasi tiket bantuan teknis.
8. Referensi Terkait
Pemahaman holistik mengenai orkestrasi koneksi data dapat Anda perluas melalui dokumentasi berikut:
Rest API / JSON Dinamis
Langkah evolusi lanjut untuk menghubungkan perangkat lunak ERP modern via jembatan HTTP/JSON Kustom.
Konektor Database MySQL/PgSQL
Penjabaran sinkronisasi data relasional secara terisolasi tanpa latensi batas akses publik web.
Otak AI: Knowledge Base RAG
Pelajari bagaimana sistem embedding dan chunking vektor memanen data tekstual Google Sheets Anda.
Katalog Konektor Integrasi Bisnis
Daftar menyeluruh platform integrasi yang disokong DagangBot untuk eskalasi bisnis enterprise.
