Arsitektur Integrasi ERP ke Portal Web B2B: Pola Event-Driven Webhook, Buffer Queue, dan Rekonsiliasi Stok

Integrasi antara portal web B2B (baik berupa katalog interaktif, platform pesanan grosir, maupun e-commerce distributor) dengan sistem ERP (Enterprise Resource Planning) internal seperti SAP, Microsoft Dynamics, Odoo, atau Accurate merupakan tulang punggung efisiensi operasional korporat. Tanpa sinkronisasi otomatis, tim penjualan dan pergudangan terpaksa melakukan entri data ganda secara manual, memicu kesalahan penetapan harga pesanan, keterlambatan pemenuhan barang, dan ketidakakuratan status stok yang dapat merusak kepercayaan pelanggan institusi.

Akan tetapi, menghubungkan portal web publik yang menghadapi lalu lintas internet terbuka langsung ke basis data ERP internal adalah risiko rekayasa yang berbahaya. Lonjakan kunjungan web, serangan penolakan layanan (Denial of Service), atau kueri agregasi yang berat di sisi front-end dapat membuat server ERP sentral lumpuh, melumpuhkan seluruh lini logistik dan akuntansi fisik perusahaan.

Artikel ini menyajikan panduan arsitektural lengkap untuk merancang antarmuka integrasi yang aman, andal, dan tahan banting menggunakan pola event-driven architecture, antrean penyangga (buffer queue), verifikasi webhook berkunci idempoten, dan algoritma rekonsiliasi stok berkala.

1. Mengapa Integrasi Sinkron Langsung (Direct Coupling) Harus Dihindari #

Banyak tim pengembang pemula tergoda untuk menyambungkan portal web langsung ke database ERP internal via koneksi JDBC/ODBC langsung atau panggilan API sinkron pada setiap permintaan HTTP pengguna. Pendekatan ini memiliki empat celah fatal:

[ POLA ANTI-PATTERN: DIRECT COUPLING (BERBAHAYA) ]

Browser Pembeli ---> Portal Web B2B ---> API ERP Sentral ---> Basis Data ERP
                     (Jika ERP lambat,   (Beban berat bikin   (Terkunci akibat
                      koneksi timeout)    sistem fisik mati)   transaksi paralel)

1. Kegagalan Berantai (Cascading Failures): Waktu respons ERP umumnya bervariasi dari 500 milidetik hingga beberapa detik untuk menghitung struktur diskon bertingkat (tiered pricing) atau ketersediaan multi-gudang. Jika puluhan pembeli B2B melakukan pencarian secara bersamaan, proses web server akan tertahan menunggu respons ERP hingga kapasitas worker pool habis (exhaustion), membuat portal web tidak dapat diakses.
2. Ketiadaan Toleransi Gangguan (Zero Fault Tolerance): Ketika server ERP menjalani perawatan berkala, migrasi malam hari, atau mengalami gangguan jaringan internal, portal web akan langsung memunculkan pesan galat HTTP 500 kepada pelanggan.
3. Eksposur Keamanan Internal: Membuka port database atau API ERP langsung ke jaringan publik memperbesar bidang serangan (attack surface) terhadap infrastruktur paling rahasia milik perusahaan.

Oleh karena itu, standar rekayasa enterprise memisahkan portal web dan ERP melalui perantara asinkron (decoupled event-driven architecture).

2. Diagram Arsitektur Decoupled dengan Message Queue #

Dalam arsitektur decoupled, portal web dan ERP tidak pernah berkomunikasi secara pemblokiran (blocking). Keduanya bertukar pesan melalui antrean data yang tangguh:

+---------------------------------------------------------------------------------------------------+
|                        ARSITEKTUR DECOUPLED INTEGRASI ERP - WEB B2B                               |
+---------------------------------------------------------------------------------------------------+
|                                                                                                   |
|  [ LAPISAN FRONT-FACING ]                                                                         |
|  Pembeli B2B ---> Next.js / Edge App ---> Redis Cache (Data Produk & Stok Snapshot)              |
|                                                   |                                               |
|                                       (Saat Checkout / RFQ)                                       |
|                                                   v                                               |
|  [ LAPISAN INGESTION & BUFFER ]                                                                   |
|  Web API Gateway ---> RabbitMQ / Redis Streams / Kafka Queue (Topic: `orders.incoming`)           |
|                                                   |                                               |
|                                         (Asynchronous Workers)                                    |
|                                                   v                                               |
|  [ LAPISAN INTEGRASI (INTEGRATION WORKER) ]                                                       |
|  Worker Process (Idempotency Check, Format Mapper, Retry Handler with Exponential Backoff)        |
|                                                   |                                               |
|                                       (Koneksi VPN / mTLS Aman)                                   |
|                                                   v                                               |
|  [ LAPISAN ERP PERUSAHAAN ]                                                                       |
|  Enterprise ERP (SAP / Odoo / Accurate) <---> Basis Data Utama ERP (Posting Pesanan & Jurnal)    |
|                                                                                                   |
+---------------------------------------------------------------------------------------------------+

Dengan desain ini, portal web dapat memproses pesanan dan menampilkan katalog dalam hitungan milidetik dari local datastore dan cache Redis berkecepatan tinggi. Beban pengiriman pesanan ke ERP disimpan dengan aman di dalam antrean antipesan (message queue), yang membatasi laju pemrosesan agar tidak melebihi kapasitas kemampuan penerimaan ERP.

3. Penanganan Webhook dan Kunci Idempotensi #

Ketika status pesanan berubah di ERP (misalnya status pesanan berubah dari Draft ke Approved, atau pembayaran faktur telah terverifikasi di bank), ERP mengirimkan sinyal pembaruan kembali ke portal web melalui webhook HTTP POST.

Tantangan utama webhook di dunia nyata adalah duplikasi pengiriman (network retry) dan urutan paket yang tidak teratur (out-of-order delivery). Untuk mencegah pesanan terproses dua kali atau status mundur ke kondisi sebelumnya, portal web harus menerapkan kunci idempotensi (idempotency key).

Implementasi Middleware Idempotensi di Layer API #

Berikut adalah pola implementasi verifikasi idempotensi menggunakan Redis pada middleware aplikasi:

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Redis;

class EnsureWebhookIdempotency
{
    public function handle(Request $request, Closure $next)
    {
        $eventId = $request->header('X-ERP-Event-ID');
        if (!$eventId) {
            return response()->json(['error' => 'Header X-ERP-Event-ID wajib disertakan'], 400);
        }

        $lockKey = "webhook:lock:{$eventId}";
        $processedKey = "webhook:processed:{$eventId}";

        // Periksa apakah event ini sudah selesai diproses sebelumnya
        if (Redis::exists($processedKey)) {
            return response()->json([
                'success' => true,
                'message' => 'Event sudah pernah diproses (Idempotent replay)',
            ], 200);
        }

        // Dapatkan distributed lock selama 60 detik untuk mencegah balapan konkurensi (race condition)
        $acquired = Redis::set($lockKey, '1', 'EX', 60, 'NX');
        if (!$acquired) {
            return response()->json([
                'error' => 'Event sedang dalam proses oleh thread lain. Silakan coba kembali nanti.',
            ], 429);
        }

        try {
            $response = $next($request);

            // Simpan status sukses selama 7 hari agar pengiriman ulang dari ERP langsung dijawab 200 OK
            if ($response->getStatusCode() >= 200 && $response->getStatusCode() < 300) {
                Redis::set($processedKey, 'COMPLETED', 'EX', 86400 * 7);
            }

            return $response;
        } finally {
            Redis::del($lockKey);
        }
    }
}

Pola di atas menjamin bahwa meskipun sistem ERP mengirimkan ulang panggilan webhook yang sama sebanyak 5 kali karena fluktuasi koneksi jaringan, sistem portal web hanya akan mengeksekusi mutasi basis data satu kali saja.

4. Strategi Sinkronisasi Stok Dua Arah (Two-Way Stock Sync) #

Masalah paling umum pada bisnis distribusi adalah overselling (menjual barang yang stok fisiknya sudah habis di gudang) atau phantom inventory (menampilkan barang kosong padahal stok sebenarnya tersedia).

Untuk menyeimbangkan kecepatan respons situs dengan akurasi fisik, terapkan strategi sinkronisasi dua jalur:

Jalur A: Event-Driven Delta Update (Perubahan Seketika) #

Setiap kali terjadi transaksi mutasi barang di ERP (surat jalan diterbitkan, barang masuk dari pabrik), ERP memicu pesan delta ke message queue portal web:

• Payload berisi: {"sku": "VALVE-DN50-SS316", "warehouse_id": "GDG-CKR-01", "qty_delta": -5}.
• Worker web menerapkan atomik decrement pada basis data dan cache Redis secara instan.

Jalur B: Bulk Nightly Reconciliation (Rekonsiliasi Total Berkala) #

Sistem otomatis menjalankan audit komprehensif setiap tengah malam pada pukul 02.00 WIB ketika transaksi perdagangan sedang rendah:

1. Skrip cron mengekspor seluruh inventaris dari ERP dalam format berkas terkompresi (CSV atau Parquet).
2. Worker membandingkan snapshot ERP dengan snapshot portal web baris demi baris menggunakan algoritma hashing.
3. Jika ditemukan anomali selisih jumlah stok, sistem otomatis memperbarui nilai di portal web dan mengirimkan catatan peringatan ke kanal monitoring tim operasional logistik.

Tabel Matriks Perbandingan Pola Sinkronisasi:

+----------------------+--------------------------+---------------------------+
| Parameter            | Pola Event-Driven Delta  | Pola Bulk Reconciliation  |
+----------------------+--------------------------+---------------------------+
| Frekuensi            | Real-time (sub-detik)    | Terjadwal (Harian / 02.00)|
| Ukuran Beban Jaringan| Sangat kecil (per-item)  | Besar (Full dump SKU)     |
| Toleransi Drift      | Rentan akumulasi drift   | Menghapus seluruh drift   |
| Tujuan Rekayasa      | Pembaruan cepat front-end| Koreksi total kepatuhan   |
+----------------------+--------------------------+---------------------------+

5. Protokol Keamanan Jaringan dan Autentikasi mTLS #

Mengingat transaksi pesanan B2B menyangkut nilai kontrak ratusan juta hingga miliaran rupiah, kanal pertukaran data antara server web publik dan server ERP harus diperkuat dengan protokol keamanan berlapis:

1. Mutual TLS (mTLS): Tidak hanya klien yang memverifikasi sertifikat SSL server, tetapi server ERP juga memverifikasi sertifikat digital yang dipasang pada server web. Ini mencegah serangan Man-in-the-Middle (MitM) bahkan jika URL endpoint publik diketahui peretas.
2. IP Whitelisting & VPN Gateway: Endpoint API ERP hanya boleh menerima paket TCP dari alamat IP statis gateway portal web melalui tunnel WireGuard atau IPsec pribadi.
3. HMAC Signature Payload: Setiap pengiriman webhook dilengkapi header X-Signature-SHA256 yang dihitung dari shared secret key dan isi body mentah request. Server penerima wajib menghitung ulang hash sebelum memproses isi request.

6. Rangkuman Langkah Implementasi untuk Tim IT Perusahaan #

Mengintegrasikan portal web modern dengan sistem ERP lawas bukanlah pekerjaan sekali jalan, melainkan perancangan pipeline data yang berkelanjutan. Sebelum memulai proyek integrasi, pastikan tim rekayasa Anda menyusun dokumen Kerangka Kerja Integrasi yang mencakup:

1. Pemetaan kamus data (data dictionary mapping) antara skema web dan skema ERP.
2. Standar kode error dan batas maksimal pengulangan transaksi gagal (retry backoff policy).
3. Kebijakan antrean Dead Letter Queue (DLQ) untuk menampung pesan yang gagal diproses agar tidak hilang begitu saja.
4. Dashboard telemetri pemantau kesehatan antrean data secara real-time berbasis Prometheus dan Grafana.

Dengan menerapkan arsitektur decoupled yang didukung message queue dan validasi idempotensi yang ketat, perusahaan distributor dan manufaktur dapat membuka potensi penjualan digital secara masif tanpa pernah khawatir sistem ERP internal mengalami kelebihan beban atau gangguan operasional.