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

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.

Stable

1. 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.
Batasan Arah Sinkronisasi

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.

Kartu integrasi Google Sheets live di dasbor integrasi DagangBot
Kartu integrasi Google Sheets di dasbor DagangBot dengan panduan impor stok dan tombol konfigurasi.

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

Modal konfigurasi Google Sheets live dengan kolom URL Spreadsheet dan tombol simpan
Formulir modal konfigurasi Google Sheets dengan input URL dokumen spreadsheet publik untuk sinkronisasi otomatis.

3. Panduan Langkah-demi-Langkah

Berikut merupakan prosedur komprehensif dari hulu ke hilir untuk mengamankan kelancaran impor data massal pertama Anda.

  1. 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 (seperti Nama Produk, Product Name, atau Nama). 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. 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 Harga dan Stok harus diisi dengan angka bulat absolut. Sebagai contoh, tulis 150000 dan bukan Rp 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 nilai 0. Format teks (Plain Text) adalah tipe data yang paling aman untuk segala kolom, termasuk SKU yang sering kali mengandung angka diawali nol (seperti 00234).

  3. 3

    Langkah 3: Setel Izin Berbagi ke Viewer Publik

    Dari dalam jendela Google Spreadsheet Anda yang sedang aktif:

    1. Klik tombol Share (Bagikan) berwarna biru di pojut kanan atas layar.
    2. 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).
    3. 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.
    4. Klik Copy link, kemudian tekan Done. Tautan telah tersimpan di clipboard perangkat Anda.
  4. 4

    Langkah 4: Daftarkan Tautan di Dasbor DagangBot

    Navigasikan web browser Anda ke platform DagangBot. Pastikan Anda memiliki otorisasi ganda (RBAC) dengan permission integrations:create dan integrations:update.

    1. Masuk ke menu Integrations (Integrasi).
    2. Temukan kartu layanan Google Sheets dan klik tombol tambah integrasi baru.
    3. Beri nama integrasi (misalnya: "Katalog Baju Lebaran").
    4. Pada dropdown cabang, tentukan apakah integrasi ini untuk Tenant Global (semua cabang) atau didedikasikan untuk cabang spesifik.
    5. Tempel URL yang disalin pada Langkah 3 ke dalam isian Spreadsheet URL.
    6. Tentukan Sync Target atau sasaran injeksi data (pembahasan detail ada di sesi Spesifikasi Teknis).
    7. Simpan konfigurasi. Sistem akan melakukan ping HTTP GET seketika untuk memvalidasi aksesibilitas publik dari tautan tersebut.
  5. 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 Stok menjadi 0. Saat sinkronisasi berjalan, DagangBot akan membaca angka 0 ini dan secara otomatis mengubah status is_active produk menjadi false, sehingga produk ditarik dari etalase chatbot secara anggun.

  6. 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.

Model Objek DagangBot Kolom Header yang Diterima Tipe Data PostgreSQL Keterangan Operasional
SKU sku VARCHAR (Opsional) Penanda unik internal. Sangat direkomendasikan untuk menghindari bentrok nama produk bila terjadi salah eja.
Name nama produk, nama, product name, name VARCHAR (Wajib) Nama entitas yang akan dimunculkan ke klien. Bila SKU kosong, kolom ini memegang peran identitas primer.
Price harga, price NUMERIC/FLOAT8 Wajib format integer/float. Kegagalan parsing teks huruf mengakibatkan harga jatuh ke 0.
Stock stok, stock, qty, quantity INTEGER Nilai > 0 mengaktifkan produk. 0 menonaktifkannya dari etalase.
Category kategori, category VARCHAR (Opsional) Pengelompokan produk untuk filtering di menu interaktif.
Description deskripsi, description, keterangan TEXT (Opsional) Penjabaran detail yang akan dibaca oleh AI Assistant saat RAG bekerja.
Size ukuran, size VARCHAR Parameter dimensi untuk varian (sepatu, pakaian).
Color warna, color VARCHAR Parameter warna untuk varian.
Material material, bahan VARCHAR Parameter bahan untuk kelengkapan spesifikasi fisik.
Weight berat, weight VARCHAR/NUMERIC Parameter bobot yang bisa berguna untuk integrasi pengiriman logistik di masa depan.
ImageURL foto, gambar, image, foto url VARCHAR Tautan statis https:// menuju berkas gambar. Diperlukan untuk render product card WA.
Skema Tata Letak Ganda (Multi-Row Catalog)

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:

  1. catalog_only: Menyasar modul Order & Commerce. Data disalurkan penuh ke fungsi upsertProducts, menimpa atribut tabel products. Pengetahuan tidak diindeks ke AI.
  2. knowledge_only: Menyasar modul AI Assistant. Data produk diekstrak, diubah formatnya menjadi narasi paragraf melalui utilitas RendererFor("ecommerce"), dikemas, dan disuplai ke utilitas injeksi stageProductRecords. Mesin vektor akan melakukan embedding atas perubahan hash SHA-256 (mencegah re-embedding pada teks yang sama persis) ke tabel integration_records yang akan menyokong basis pengetahuan chatbot.
  3. 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:

  1. Melakukan kompilasi seluruh larik SKU dan Nama dari kumpulan memori.
  2. 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(...)).
  3. 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.
  4. Semua parameter non-identitas (Nama (jika terikat via SKU), Deskripsi, Harga, Stok, dan Gambar) akan ditimpa penuh.
  5. Parameter Boolean is_active secara otomatis di-compute melalui operator logika Stock > 0.
  6. 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, dan integrations: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 kolom branch_id pada entitas integrations) hanya akan merespons permintaan checkout pengguna WhatsApp yang dikelola oleh Omnichannel instance wilayah cabang tersebut. Ini dikunci ketat via WHERE 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.

bash
# 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": {}
  }'
bash
# 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.

Gejala Error (Symptom) Akar Penyebab (Root Cause) Solusi Sistematis (Resolution)
"URL Spreadsheet tidak valid" saat menyimpan form integrasi Format string tidak melewati filter regular expression keamanan. URL tidak memuat substring docs.google.com/spreadsheets. Salin URL utuh dari address bar peramban. Jika Anda menggunakan versi terpublikasi web (publish to web), kembali gunakan tautan dokumen reguler dari fungsi Share.
"Akses ditolak" / "spreadsheet not public or not found (HTTP 403)" Kebijakan Sharing file Anda berstatus Restricted atau dibatasi domain workspace khusus organisasi/perusahaan Anda. Akses menu Share → ganti General Access menjadi "Anyone with the link". Pastikan tidak terkunci di domain organisasi (contoh: PT Maju Mundur Only).
Produk terlaporkan 0 Fetched atau tidak kunjung masuk sistem Struktur tabel tidak dikenali parser C-struct. Entah kolom SKU tidak ada, atau judul tabel tenggelam terlalu dalam melampaui limit kedalaman baris ke-30. Sisipkan secara tegas kolom berlabel SKU dan Nama Produk pada baris ke-1 dokumen. Pastikan tidak ada karakter tak terlihat (seperti spasi spuria) pada header. Hapus baris-baris aesthetic blank space yang sering digunakan untuk memisah judul kop surat tabel.
Harga dan Stok tercatat 0 secara misterius Kesalahan penetapan tipe data. Anda mengetik satuan "pcs" di kolom stok, atau mengetik simbol mata uang di kolom harga. Ubah format kolom menjadi murni angka (contoh: 250000 dan 100). Buang seluruh huruf atau simbol, kemudian gunakan formatting tools bawaan Sheets bila sekadar ingin melihat visual mata uang.
Hanya sheet (tab) pertama yang masuk ke DagangBot Perilaku endpoint standar Google mengekspor tab yang berada pada posisi index-0 bila parameter argumen referensi sheet tidak dikirimkan secara kustom. Pindahkan master data terpadu (Katalog Lengkap) ke Tab paling sebelah kiri. Sisakan tab-tab pendukung lainnya di sebelah kanannya.
Data gagal di-update, duplikasi produk terjadi Modifikasi yang Anda lakukan ke nama produk merusak identitas fallback pencocokan di database lantaran produk tersebut sejak awal tidak dikaruniai SKU unik. Sangat Direkomendasikan: Jangan pernah membiarkan kolom SKU kosong. Buat format bebas (misal: BRG-01, BRG-02) untuk memastikan konsistensi relasi upsert 1:1, tidak peduli apa pun perombakan nama dan harga di masa depan.

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.

Kode Sistem Internal / API Error Penjelasan Mekanika Kegagalan Tindakan Mitigasi Terukur
sheets: spreadsheet_id not configured String extractor regex milik backend gagal merengkuh ID alfanumerik 44-karakter (berada pasca /d/) karena format string anomali. Lakukan paste URL standar (contoh: https://docs.google.com/spreadsheets/d/1BxiMVs.../edit).
sheets: spreadsheet not public or not found (HTTP 401) Ekspor URL format CSV mengalami akses tertutup, ditolak oleh otoritas sesi anonim (tanpa kuki otentikasi) yang diprakarsai klien HTTP Golang internal DagangBot. Bebaskan Share Link menjadi Viewer publik absolut. Jika Google Workspace organisasi mengunci fitur publik secara global, pindahkan ke akun Gmail freemium reguler.
sheets: failed to parse CSV Kesalahan tata letak pemisah pembatas koma CSV Reader. Sering dipicu oleh penyertaan tanda kutip paksa yang tidak diakhiri, atau line-break (Enter) ganda mendalam di satu sel teks. Hapus kolom yang terlalu tebal formatting-nya. Periksa kolom deksripsi yang mungkin menyertakan tanda baca escaping bermasalah.
sheets: spreadsheet is empty Operasi respons selesai dengan HTTP 200 OK, namun rentang badan muatan (HTTP Body Length) menihilkan output, mendeteksi kanvas sel ketiadaan struktur tabel. Isi baris tabel dengan setidaknya satu sampel produk dummy sebelum memicu siklus Test Connection dan sinkronisasi perdana.
sheets: external api call requires google credentials Modul CheckStock realtime atau CreateOrder mencoba mengeksploitasi fungsi penulisan dua arah (bidirectional write). Ditolak paksa pada layer abstraksi konektor interface. Abaikan error ini sebagai batas alamiah sistem. Eksekusi ini tidak akan mencemaskan stabilitas server production; platform dirancang berpusat ke mode pembaruan inventaris.

8. Referensi Terkait

Pemahaman holistik mengenai orkestrasi koneksi data dapat Anda perluas melalui dokumentasi berikut:

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

Dokumentasi teknis DagangBot