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

Integrasi Bisnis Universal: Katalog Konektor & Sumber Data

Bisnis modern beroperasi menggunakan berbagai perangkat lunak yang saling melengkapi. Ketersediaan barang mungkin tersimpan di Google Sheets atau WooCommerce, penagihan melalui Midtrans, dan pelacakan keluhan di Redmine. DagangBot bertindak sebagai jembatan penghubung (Universal Business Middleware) yang menyinkronkan seluruh aliran data tersebut ke dalam satu mesin AI tanpa pengetikan manual.

Stable

1. Ikhtisar & Nilai Bisnis

Modul Integrasi Bisnis memungkinkan Anda untuk tidak memigrasikan database atau mengubah perangkat lunak yang sudah digunakan. Anda menghubungkan konektor yang tersedia, dan AI secara otomatis membaca stok, memperbarui harga, serta menerbitkan tautan pembayaran (invoice) secara real-time.

Pendekatan Universal Business Middleware dirancang untuk bisnis yang sudah memiliki infrastruktur IT matang. Daripada memaksa pedagang menggunakan satu sistem tunggal, platform bertindak sebagai agregator yang secara pasif (read-only) dan aman memantau perubahan eksternal, lalu menerjemahkannya ke dalam aksi pada percakapan pelanggan.

  • Katalog Konektor Lengkap: Mendukung sinkronisasi via Google Sheets, koneksi database (PostgreSQL, MySQL, MariaDB), jembatan event-driven lewat Webhook, E-commerce (WooCommerce/Shopify), dan pelacakan tiket internal (Redmine). Pembayaran (Payment Gateway) didukung secara native melalui Midtrans dan Xendit.
  • Keamanan Read-Only & IP Egress Terisolasi: DagangBot menyediakan IP publik keluar (egress IP) statis resmi yang dapat Anda daftarkan (whitelist) pada firewall server Anda. Koneksi database dipastikan hanya membutuhkan hak akses baca-saja. Modul konektor database secara otomatis menolak setiap perintah tulis, memberikan jaminan keamanan arsitektur tingkat tinggi.
  • Penahapan RAG Cerdas (Staging RAG): Untuk aliran data produk bervolume besar dari E-commerce dan Redmine, platform menyediakan alur Staging RAG. Mode sinkronisasi dapat diarahkan secara fleksibel: menyisipkan data secara langsung ke katalog terstruktur (catalog), menginjeksikannya ke ruang pencarian vektor Knowledge Base (knowledge_only), atau keduanya secara simultan (both).
  • Keandalan Tinggi & Penanganan Pemutusan: Sistem dirancang dengan ketahanan asinkron. Jika layanan gateway pembayaran atau server E-commerce Anda mengalami kegagalan, modul integrasi memiliki mekanisme Circuit Breaker. Koneksi yang terus-menerus gagal akan diputus sementara untuk mencegah kelebihan muatan, dan diuji kembali secara otomatis setelah periode pemulihan.
Prinsip Keamanan Read-Only

Untuk integrasi database SQL (PostgreSQL / MySQL), selalu buat pengguna khusus dengan hak akses terbatas: GRANT SELECT ON tabel_produk TO dagangbot_user;. Jangan memberikan izin INSERT, UPDATE, atau DROP. Sistem melewati (skip) pembacaan pada tabel internal/sistem seperti pg_catalog.

2. Arsitektur Konektor & Penyelarasan Alur Data

Arsitektur konektor mengandalkan antarmuka penyatuan (ProductConnector) di lapisan infrastruktur Golang. Layanan luar diimplementasikan menggunakan pembungkus asinkron (asynchronous wrapper) yang mengekstraksi data menjadi struktur dinamis map[string]any sebelum disaring berdasarkan tipe integrasi. Proses ini berlangsung dalam mode terisolasi agar satu entitas tidak mempengaruhi merchant lainnya.

A. Sinkronisasi Database Relasional (PostgreSQL & MySQL)

Konektor membuka koneksi TCP berprotokol SSL/TLS pada port standar (5432 untuk PostgreSQL dan 3306 untuk MySQL). Ketika operasi sinkronisasi berjalan, fungsi utama (SyncDatabase) membaca pemetaan konfigurasi kredensial Host, Port, dan Nama Database yang terenkripsi AES-256-GCM. Fungsi internal ReadGenericRecords mengekstrak data di semua tabel yang ditentukan. Sistem kebal terhadap manuver serangan injeksi SQL karena pembacaan tabel difilter pada awal permintaan (prepared statement validation).

B. Pemrosesan Sinkronisasi E-commerce (WooCommerce & Shopify)

Konektor memanggil REST API milik instalasi e-commerce eksternal klien menggunakan metode validasi HMAC atau OAuth (Consumer Key dan Consumer Secret). Saat fungsionalitas asinkron SyncEcommerce dipanggil, modul menyedot seluruh katalog barang beserta variasi harga, kategori, dan ketersediaan stok. Seluruh rekaman diproses di dalam wadah transaksional per merchant. Data produk lama yang berstatus kedaluwarsa dibersihkan otomatis menggunakan penyelarasan rekaman tertinggal (reconcileOrphanRecords).

C. Manajemen Payment Gateway Terintegrasi (Midtrans & Xendit)

Konektor fasilitas pelunasan bersifat dwiarah. Pada lalu lintas aliran keluar, sistem merakit objek permintaan (request payload) dan mengirimkannya melalui perintah HTTP POST ke target API Midtrans Snap untuk menghasilkan URL pemanggilan QRIS atau Virtual Account. Pada jaringan penerimaan (inbound), mekanisme pembacaan webhook dilengkapi verifikasi keaslian menggunakan VerifyMidtransSignature berdasarkan Order ID, Status Code, dan Gross Amount. Kunci validasi dikelola secara rahasia dan dilengkapi pelindung penanganan duplikasi idempoten (midtrans-settle:ID:paid), memastikan bahwa pelunasan pesanan tidak menggelembung nilainya akibat percobaan notifikasi callback berkali-kali.

D. Redmine & Sinkronisasi Ekstraksi Pengetahuan

Integrasi sistem Redmine (SyncRedmineDirect) menarik daftar isi, judul keluhan terbuka, serta pembaruan solusi. Data teks tidak terstruktur dipompa ke fasilitas Staging RAG. Antrean penyematan vektor otomatis (embedding queue) membaca uraian tiket dan mengubah data tersebut menjadi sekumpulan vektor pengetahuan. AI dapat langsung memberikan jawaban atas status dukungan dengan menarik konteks spesifik tersebut.

3. Alur Visual & Antarmuka

Berikut adalah tampilan katalog konektor integrasi bisnis serta panel konfigurasi pembayaran (payment gateway):

Katalog konektor integrasi bisnis universal pada dashboard DagangBot
Katalog modul integrasi bisnis terpadu
Konfigurasi kredensial Midtrans pada dashboard
Panel konfigurasi kredensial Payment Gateway Midtrans

4. Panduan Langkah-demi-Langkah

Ikuti alur berikut untuk mengaktifkan konektor bisnis ke sistem toko Anda:

  1. 1

    Langkah 1: Akses Menu Integrasi Bisnis Utama

    Buka halaman navigasi di platform dasbor pada rute /app/integrations. Di bagian atas halaman, Anda dihadapkan pada papan daftar konektor siap pakai. Pilih jenis konektor eksternal yang paling sesuai (misal: E-commerce WooCommerce atau penagihan Midtrans). Sistem akan merilis sesi tipe integration_id seketika.

  2. 2

    Langkah 2: Daftarkan Kunci Kredensial Akses

    Masukkan rincian informasi konfigurasi otentikasi. Untuk koneksi database, lengkapi atribut jaringan: alamat Host, Port koneksi, Username dan Password. Pada integrasi Midtrans, tambahkan nilai Server Key rahasia serta nilai Client Key milik akun Anda. Semua input sensitif dibungkus enkripsi AES-256-GCM ke dalam atribut tabel basis data credentials_encrypted.

  3. 3

    Langkah 3: Konfigurasi Aturan Jaringan (Whitelist IP)

    Apabila database SQL internal Anda terlindungi firewall berlapis, Anda perlu menyalin nilai IP Egress statis dari dasbor. Daftarkan angka IP tersebut pada Inbound Rules firewall Amazon AWS Security Group, Google Cloud VPC Firewall, atau perute mikrotik.

  4. 4

    Langkah 4: Tentukan Tujuan Data & Skema Target (Staging)

    Pada konektor penarikan produk (WooCommerce), atur preferensi penarikan (target mapping):

    • catalog: Menerjemahkan stok ke format basis data produk di platform dengan dukungan atribut terstruktur.
    • knowledge_only: Membuang pengaturan kolom dan mengirim keterangan barang pada pencarian teks mesin vektor guna mendukung fitur menjawab percakapan asisten AI.
    • both: Menciptakan baris secara bersamaan pada katalog admin dan pada mesin kognitif AI dalam satu aliran proses latar belakang (background job pipeline).
  5. 5

    Langkah 5: Inisiasi Uji Jaringan & Pemantauan Log Sinkronisasi

    Tahapan terakhir mewajibkan penekanan tombol Uji Koneksi (/api/integration/test). Gateway DagangBot melaksanakan handshake diagnostik. Setelah berhasil mendapatkan HTTP 200 OK, sistem otomatis merekam jadwal pelacakan (cron polling). Fluktuasi produk, jumlah ditarik, kegagalan (failover), hingga proses Staging RAG tercatat permanen pada tabel audit internal di integration_records.

5. Parameter & Spesifikasi Teknis Integrasi

Tabel berikut meringkas konfigurasi pengaturan teknis sinkronisasi sistem di belakang konektor:

Jenis Konektor Integrasi Arah Aliran Keamanan & Verifikasi Mekanisme Sinkronisasi Batasan (Limit) Khusus
Google Sheets Masuk (Inbound) Kredensial Akun Google Service / Tautan URL Publik Terbuka Terstruktur (Polling) setiap 15 Menit Sistem hanya membaca lembar pertama tunggal (single worksheet) per integrasi.
Database SQL (PostgreSQL & MySQL) Masuk (Inbound) Enkripsi AES-256 (Read-Only Control) Terpusat 1 Jam, mendukung On-Demand Trigger Memotong otomatis skema information_schema dan melompati tabel sistem.
REST API Kustom Keluar & Masuk API Key Header / Bearer Token Eksekusi spontan real-time (JIT) dikomando oleh AI Format JSON berstruktur datar. Batasan tunggu waktu (timeout) 10 detik.
Outbound Webhook Keluar (Outbound) Validasi rahasia HMAC-SHA256 Signature Berbasis reaksi kejadian (Event-driven) instan Menggunakan Asynchronous Dispatch Pipeline agar tidak menyumbat antrean peladen.
E-commerce (WooCommerce/Shopify) Masuk (Inbound) Consumer Key beserta pengamanan Consumer Secret Jadwal interval otomatis via antarmuka UI Mendukung rekonsiliasi rekaman sisa (orphan records) otomatis menyeluruh.
Payment Gateway (Midtrans & Xendit) Keluar & Masuk Penyisipan Server Key atau Registrasi Parameter Rahasia Klien Verifikasi real-time lewat Webhook Callback Server Kecocokan validasi SHA-512 mutlak. Pertahanan anti-transaksi ulang Strict Idempotency Validation.
Redmine (Tracker) Masuk (Inbound) Registrasi Kunci Parameter API Access Key Rutinitas pelaksanaan On-Demand / siklus berkala Pemampatan muatan teks isu masif menjadi vektor embeddings pada sistem latar belakang (asynq).

6. Pemecahan Masalah Ekstensif (Troubleshooting)

Tabel diagnosis peringatan kegagalan status jaringan komunikasi backend:

Kode Kesalahan & Simtom Kegagalan Identifikasi Akar Penyebab Teknis Utama (Root Cause Diagnosis) Instruksi Penyelesaian Masalah & Aksi Solusi
ERR_CONN_REFUSED / Penutupan Status Sambungan Timeout Akses port database (3306 atau 5432) terblokir dari jaringan eksternal terbuka. IP Egress statis platform belum diregistrasi pada aturan izin firewall peladen. Masukkan barisan blok IP Egress Platform resmi ke tabel Inbound Rules Firewall konfigurasi lapisan penyedia pangkalan data (VPC). Pastikan parameter peladen (postgresql.conf atau my.cnf) mengizinkan rute dari 0.0.0.0.
403 Forbidden pada Siklus Sinkronisasi Google Sheets Mode visibilitas berkas URL Google Sheets dibekukan ke mode visibilitas terbatas, menutup otorisasi agen crawler platform mengekstrak isi kolom. Akses lembaran URL Google Spreadsheet, operasikan tombol kontrol Share, dan seleksi pergantian otorisasi pembatasan menjadi status visibilitas publik universal ("Anyone on the internet with the link can view").
Kegagalan Validasi HMAC Webhook Keluar Susunan angka nilai hash Secret Key HMAC yang ditanam pada mesin penerima tidak setara dengan kata sandi rahasia cetak algoritma penerbitan payload signature platform. Bandingkan nilai absolut rahasia (Secret String) yang tersimpan kuat pada panel konfigurasi Integrasi Bisnis Dasbor dengan deklarasi parameter konfigurasi penerima (server endpoint internal institusi Anda).
401 Unauthorized API Midtrans pada Transaksi Pemrosesan Invoice Kelalaian penempatan urutan kolom formulir konfigurasi parameter. Masukan Server Key serta identitas Client Key tertukar silang. Sistem mendeteksi Mid-client- di kolom target Server Key. Tukar posisi konfigurasi pada antarmuka. Pastikan Server Key orisinal dimasukkan pada ruas yang tepat. Sistem proteksi mendeteksi pola kunci peladen palsu (swapped identity credential structural format validation).
Keterlambatan Sinkronisasi Penarikan Pembaruan Stok E-commerce (WooCommerce) Tuas aliran modul sakelar dasbor berada dalam mode konfigurasi nonaktif (is_active: false), atau lisensi kredensial Consumer API telah dicabut aksesnya pada pengaturan WooCommerce pihak ketiga. Inspeksi teliti rute aktivasi fungsi di panel dasbor Integrasi Bisnis DagangBot, hidupkan tuas. Bila gagal, regenerasi pendaftaran kunci kredensial baru pada menu REST API platform WooCommerce Anda, dan salin ulang.

7. Referensi Terkait Arsitektur

content/docs/features/business-integrations.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot