# Desain Middleware dan Integrasi ERP: Menghubungkan Sistem Anda > Cara merancang lapisan integrasi middleware yang kuat untuk ERP kustom Anda — mencakup pola API, arsitektur event-driven, pemrosesan async berbasis antrian, dan kesalahan integrasi yang menyebabkan korupsi data. URL: https://www.matthewswong.com/id/blog/erp-middleware-integration-design/ - Author: Matthews Wong (https://www.matthewswong.com/id/about/) - Published: 2025-06-10 - Updated: 2025-06-10 - Category: ERP Tidak ada ERP yang berdiri sendiri. Setiap bisnis memiliki ekosistem sistem yang harus bertukar data dengan ERP: payment gateway untuk penagihan AR, penyedia email untuk notifikasi otomatis, portal pajak pemerintah untuk pengiriman e-faktur, API perbankan untuk pemrosesan pembayaran, API logistik untuk pelacakan pengiriman. Mendapatkan integrasi yang salah menyebabkan korupsi data, transaksi duplikat, dan acara yang terlewat — masalah yang mahal untuk didiagnosis dan bahkan lebih mahal untuk diperbaiki dalam sistem produksi. ## Pola Integrasi: Memilih Pendekatan yang Tepat Untuk ERP kustom yang melayani UKM Indonesia, tiga pola mencakup sebagian besar kebutuhan integrasi. Integrasi API langsung: ERP memanggil API eksternal secara sinkron dan menunggu respons. Cocok untuk: kueri real-time, tindakan di mana pengguna mengharapkan respons segera. Integrasi event-driven: ERP menerbitkan acara dan satu atau lebih sistem hilir mengonsumsinya. Integrasi berbasis antrian: ERP menempatkan pekerjaan dalam antrian, pekerja memprosesnya dan menangani percobaan ulang pada kegagalan. ### Masalah Keandalan Integrasi Integrasi API langsung adalah pola yang paling umum dan paling rapuh. Jika API eksternal mati, permintaan ERP Anda gagal. Desain integrasi yang andal memecahkan masalah ini dengan tiga teknik: kunci idempotency (setiap permintaan API menyertakan ID unik yang mencegah pemrosesan duplikat), circuit breakers (hentikan percobaan ulang API yang gagal setelah N kegagalan berturut-turut), dan async fallback (konversi panggilan sinkron ke pekerjaan antrian async). ### Arsitektur Berbasis Antrian dengan BullMQ Untuk ERP yang dibangun di NestJS, BullMQ (antrian pekerjaan yang didukung Redis) adalah pilihan standar untuk pemrosesan integrasi async. Polanya: ketika ERP perlu memanggil API eksternal (kirim email, hasilkan PDF, kirimkan e-faktur), alih-alih memanggil API secara langsung, ERP membuat pekerjaan dalam antrian BullMQ dan segera kembali ke pengguna. Proses pekerja mengambil pekerjaan, mengeksekusi panggilan API, menangani kegagalan dengan logika percobaan ulang yang dapat dikonfigurasi. > Dari pengalaman saya sebagai konsultan ERP lepas: saya selalu mengimplementasikan dead letter queue (DLQ) untuk pekerjaan integrasi yang gagal. Pekerjaan yang menghabiskan percobaan ulang mereka harus masuk ke DLQ dengan konteks penuh — payload pekerjaan, pesan kesalahan dari setiap percobaan, dan timestamp. Saya meninjau DLQ setiap hari. Pola kegagalan dalam DLQ sering mengungkapkan perubahan kontrak API, kedaluwarsa autentikasi, atau masalah kualitas data. ## Merancang API Integrasi: Apa yang Diekspos ERP API integrasi ERP Anda mendefinisikan cara sistem eksternal dapat membaca dan menulis data ke ERP. Rancang dengan prinsip-prinsip ini: versioning (awali semua endpoint API dengan /api/v1/), idempotency (endpoint POST menerima kunci idempotency yang disediakan klien), pagination (tidak pernah mengembalikan daftar tak terbatas), dan autentikasi (integrasi mesin-ke-mesin menggunakan kunci API atau JWT akun layanan). > **Keamanan webhook: lubang integrasi yang dilewatkan kebanyakan tim** > Webhook — callback HTTP dari sistem eksternal ke ERP Anda — adalah pola integrasi umum untuk konfirmasi pembayaran, pembaruan status pengiriman, dan hasil persetujuan. Tetapi webhook juga merupakan risiko keamanan: sistem mana pun yang mengetahui URL webhook Anda dapat mengirimkan payload arbitrer kepada Anda. Selalu validasi tanda tangan webhook. Payment gateway (Midtrans, Xendit) menyertakan tanda tangan di header webhook yang dihitung dari payload dan kunci rahasia Anda. Verifikasi tanda tangan ini sebelum memproses webhook. ## Integrasi Spesifik Indonesia Implementasi ERP Indonesia biasanya memerlukan integrasi yang bukan bagian dari perpustakaan konektor bawaan platform standar mana pun. E-Faktur (DJP): sistem faktur elektronik otoritas pajak memerlukan pengiriman data faktur dalam format CSV tertentu. BPJS Kesehatan dan BPJS Ketenagakerjaan: pelaporan bulanan kontribusi asuransi kesehatan dan ketenagakerjaan karyawan memerlukan pengiriman file dalam format tertentu ke portal pemerintah. Midtrans atau Xendit: integrasi payment gateway untuk penagihan AR. ## Memantau Kesehatan Integrasi Kegagalan integrasi tidak terlihat kecuali Anda secara aktif memantaunya. Bangun dashboard kesehatan integrasi yang menampilkan: kedalaman antrian pekerjaan, tingkat kegagalan pekerjaan berdasarkan jenis integrasi, jumlah item dead letter queue, tingkat kesalahan dan latensi API eksternal, dan tingkat keberhasilan pengiriman webhook. ## Kontrak Integrasi: Dokumentasi yang Menyelamatkan Anda Setiap integrasi harus didokumentasikan dalam kontrak integrasi: nama dan versi sistem eksternal, pola integrasi, data yang dipertukarkan, metode autentikasi, perilaku penanganan kesalahan, throughput dan latensi yang diharapkan, dan pemilik yang bertanggung jawab memelihara integrasi. Ketika penyedia API eksternal mengubah API mereka, kontrak integrasi memberi tahu Anda persis kode mana yang perlu diperbarui. ## Sumber & Bacaan Lanjutan - MuleSoft — Top 10 Integration Patterns for Enterprise Use Cases — https://blogs.mulesoft.com/api-integration/patterns/top-10-integration-patterns/ - AppSeConnect — ERP Integration Guide: Methods, Tools, Use Cases and Best Practices — https://www.appseconnect.com/erp-integration-guide-best-practices/ - Enterprise Integration Patterns — Messaging Patterns Reference — https://www.enterpriseintegrationpatterns.com/ > **Key takeaway:** Tidak ada ERP yang berdiri sendiri: payment gateway, penyedia email, portal pajak untuk e-Faktur, API perbankan dan API logistik semuanya perlu bertukar data dengannya. Lapisan middleware memberi integrasi itu satu tempat untuk retry, logging dan translasi, alih-alih menyebarkan logika tersebut ke seluruh kode bisnis. ## Source links - https://blogs.mulesoft.com/api-integration/patterns/top-10-integration-patterns/ - https://www.appseconnect.com/erp-integration-guide-best-practices/ - https://www.enterpriseintegrationpatterns.com/ ## FAQ ### Apa tiga pola integrasi utama untuk ERP kustom, dan kapan masing-masing digunakan? Tiga pola tersebut adalah integrasi API langsung, integrasi event-driven, dan pemrosesan async berbasis antrian. Integrasi API langsung cocok untuk kueri real-time dan tindakan yang membutuhkan respons segera, seperti pengecekan status pembayaran. Integrasi event-driven paling tepat untuk notifikasi, logging, dan analitik di mana sistem hilir tidak perlu merespons ke ERP. Pemrosesan berbasis antrian adalah pilihan yang tepat untuk operasi seperti pengiriman email, pembuatan PDF, dan panggilan API eksternal yang mungkin gagal dan perlu percobaan ulang. ### Mengapa Dead Letter Queue (DLQ) penting dalam arsitektur integrasi ERP? Dead Letter Queue menampung pekerjaan yang telah menghabiskan semua percobaan ulang, menyimpan konteks lengkap — payload pekerjaan, pesan kesalahan dari setiap percobaan, dan timestamp. Meninjau DLQ setiap hari memungkinkan tim mendeteksi pola yang mengindikasikan perubahan kontrak API, kedaluwarsa autentikasi, atau masalah kualitas data sebelum masalah tersebut muncul di log aplikasi. Tanpa DLQ, pekerjaan integrasi yang gagal hilang begitu saja dan penyebab akar masalah menjadi sangat sulit didiagnosis. ### Bagaimana kunci idempotency dan circuit breaker meningkatkan keandalan integrasi? Kunci idempotency adalah ID unik yang disertakan dalam setiap permintaan API sehingga jika timeout memaksa percobaan ulang, sistem penerima mengenali duplikat dan tidak membuat transaksi kedua. Circuit breaker menghentikan percobaan ulang ke API eksternal yang gagal setelah sejumlah kegagalan berturut-turut yang dikonfigurasi, membuat sistem gagal cepat dan memicu peringatan daripada terus menghantam layanan yang tidak tersedia. Keduanya bersama mencegah transaksi duplikat dan mengurangi kegagalan beruntun akibat API eksternal yang lambat atau mati. ### Praktik keamanan webhook apa yang disorot dalam artikel ini, dan mengapa mudah diabaikan? Artikel ini menekankan pentingnya selalu memvalidasi tanda tangan webhook. Payment gateway seperti Midtrans dan Xendit menyertakan tanda tangan di header webhook yang dihitung dari payload dan kunci rahasia bersama; ERP harus memverifikasi tanda tangan ini sebelum memproses permintaan. Langkah ini sering dilewati karena URL webhook tampak sudah cukup sebagai rahasia, padahal sistem mana pun yang mengetahui URL tersebut dapat mengirimkan payload sembarang — sehingga validasi tanda tangan menjadi satu-satunya pertahanan yang andal. ### Integrasi spesifik Indonesia apa saja yang biasanya harus didukung oleh ERP kustom? Tiga integrasi disorot sebagai wajib atau hampir wajib untuk bisnis Indonesia. E-Faktur (DJP) mengharuskan pengiriman data faktur dalam format CSV tertentu dan menerima NSFP sebagai balasannya, dan wajib bagi bisnis berstatus PKP. BPJS Kesehatan dan BPJS Ketenagakerjaan memerlukan pengiriman file kontribusi asuransi karyawan bulanan ke portal pemerintah. Integrasi payment gateway Midtrans atau Xendit menangani penagihan AR melalui pembuatan virtual account, webhook pembayaran real-time, dan rekonsiliasi dengan faktur AR. --- - HTML version: https://www.matthewswong.com/id/blog/erp-middleware-integration-design/ - English: https://www.matthewswong.com/en/blog/erp-middleware-integration-design/ - Site index for agents: https://www.matthewswong.com/llms.txt - Sitemap: https://www.matthewswong.com/sitemap.xml - API description (OpenAPI): https://www.matthewswong.com/openapi.json