Integrasi API Sistem Bisnis: Kontrak Data, Retry, dan Transaksi Ganda

Dalam contoh penjualan dan gudang, sistem penjualan dapat menjadi sumber pesanan, sedangkan gudang menjadi sumber status pemenuhan. Jelaskan siapa yang berhak mengubah alamat, jumlah barang, dan pembatalan setelah pesanan dikirim. Dua sistem yang sama-sama bebas mengubah data tanpa aturan dapat terus menimpa pembaruan satu sama lain.

Petakan identitas yang dipakai bersama. Nomor pelanggan internal belum tentu sama pada kedua aplikasi. Gunakan pemetaan yang terdokumentasi dan perlakukan perubahan identitas dengan hati-hati. Tentukan pula apakah integrasi membutuhkan data lengkap atau hanya bagian tertentu agar pertukaran data tidak melebihi tujuan proses.

Kontrak API perlu menjelaskan struktur data, kolom wajib, format waktu, satuan, serta hasil sukses dan gagal. Sebagai contoh, jumlah barang harus memiliki satuan yang dipahami sistem gudang. Status dibatalkan juga harus menjelaskan apakah pembatalan masih dapat diterima setelah proses picking dimulai.

Dokumentasikan batas ukuran, autentikasi, pembatasan permintaan, serta kebijakan perubahan versi. Uji dengan contoh data yang valid dan tidak valid. Jika penyedia API mengubah kolom atau menghentikan versi, tim membutuhkan cara mengetahui dampaknya sebelum proses utama gagal. Kontrak sebaiknya menjadi bahan pemeriksaan bersama, bukan sekadar dokumen awal.

Timeout berarti pemanggil tidak menerima jawaban dalam batas waktu; layanan tujuan mungkin sudah menyimpan transaksi. Mengirim ulang tanpa pemeriksaan dapat membuat pesanan ganda. Gunakan identitas permintaan yang konsisten dan dukungan idempotensi sesuai kontrak agar pengulangan transaksi yang sama tidak menimbulkan efek bisnis tambahan.

Atur percobaan ulang secara terbatas dengan jeda yang meningkat dan variasi waktu jika sesuai sistem. Tidak semua kegagalan layak dicoba ulang. Data tidak valid perlu diperbaiki, sedangkan pembatasan permintaan perlu mengikuti petunjuk penyedia. Setelah batas tercapai, pindahkan transaksi ke daftar penanganan yang dapat ditinjau.

Jika perubahan dikirim melalui webhook atau antrean, jangan mengasumsikan pesan selalu datang sekali dan berurutan. Simpan identitas kejadian untuk mendeteksi duplikasi sesuai jangka waktu yang dibutuhkan. Periksa versi atau status transaksi sebelum menerapkan perubahan yang mungkin sudah tertinggal.

Panduan keamanan REST OWASP menekankan penggunaan HTTPS dan kontrol akses pada endpoint yang tidak bersifat publik. Berikan akun layanan izin sesuai tugas integrasi. Kunci yang hanya diperlukan pada server tidak boleh dimasukkan ke antarmuka yang dikirim ke browser atau aplikasi pengguna.

Kelola rahasia melalui mekanisme penyimpanan yang sesuai, dengan prosedur penggantian dan pencabutan akses. Hindari menaruh token atau data sensitif pada log diagnosis. Validasi masukan tetap diperlukan meskipun data berasal dari mitra yang dipercaya. Kesalahan format dari layanan lain tetap dapat mengganggu proses bisnis.

Setiap transaksi perlu dapat ditelusuri melewati sistem yang terlibat menggunakan identitas korelasi atau referensi yang disepakati. Tampilkan keadaan menunggu, berhasil, atau membutuhkan tindakan tanpa menyamakan terkirim dengan selesai. Petugas operasional perlu tahu masalah mana yang dapat diperbaiki sendiri dan mana yang harus dieskalasikan.

Lakukan rekonsiliasi berdasarkan kebutuhan proses untuk menemukan pesanan yang ada pada satu sistem tetapi belum tercatat pada sistem lain. Tentukan prosedur pengiriman ulang yang aman dan siapa yang menyetujuinya. Sebelum integrasi diluncurkan, uji layanan terputus, duplikasi, pesan terlambat, perubahan versi, dan pemulihan setelah gangguan.