Merancang Spesifikasi API Host-to-Host untuk Panel Asuransi

28 Juni 2026  ▪  Kategori: Analisis Sistem  ▪  Perkiraan baca: 9 menit

Integrasi Host-to-Host di lini bancassurance punya satu ciri yang membedakannya dari integrasi biasa: yang dijembatani bukan dua sistem, melainkan tiga pihak. Ada bank sebagai titik masuk nasabah, ada pialang asuransi sebagai perantara, dan ada sejumlah perusahaan asuransi — yang lazim disebut panel — sebagai penerima akhir permintaan.

Peran perantara inilah yang membuat pekerjaan spesifikasinya menarik sekaligus rumit. Perantara harus menyodorkan satu kontrak yang seragam ke bank, sementara di belakang ia berbicara dengan banyak perusahaan asuransi yang masing-masing punya aturan produk, batas usia, dan ketentuan dokumen sendiri.

   ┌──────────────┐      ┌─────────────────┐      ┌──────────────────┐
   │ Portal Bank  │─────►│  API Pialang    │─────►│  API Perusahaan  │
   │  (nasabah)   │◄─────│  (perantara)    │◄─────│    Asuransi      │
   └──────────────┘      └─────────────────┘      └──────────────────┘
                          satu kontrak              banyak panel,
                          untuk bank                aturan berbeda-beda

Empat modul, empat siklus hidup

Godaan pertama saat menyusun daftar layanan adalah mengurutkannya begitu saja dari yang paling awal dipakai. Hasilnya biasanya daftar panjang yang sulit dibaca. Yang lebih membantu adalah mengelompokkannya berdasarkan siklus hidup transaksi:

• Produk — layanan kalkulator premi. Bank mengirim profil calon tertanggung, perantara mengembalikan nilai premi beserta status akseptasinya.
• Akseptasi — pengajuan penutupan, kelengkapan dokumen, persetujuan, dan konfirmasi persetujuan.
• Pembatalan — pengajuan pembatalan, pembatalan atas pengajuan yang belum disetujui, persetujuan pembatalan, dan pembayaran pengembaliannya.
• Klaim — pengajuan klaim, kelengkapan dokumen klaim, konfirmasi persetujuan, dan pembayaran klaim.

Pengelompokan ini bukan sekadar rapi di daftar isi. Ia memaksa kita memeriksa tiap kelompok punya titik akhir yang jelas: transaksi berakhir disetujui, ditolak, atau dibatalkan. Kalau ada kelompok yang tidak punya jalan keluar, di situlah biasanya spesifikasi masih bolong.

Percabangan yang menentukan segalanya: otomatis atau ditinjau

Satu keputusan desain berdampak paling besar ke seluruh dokumen, yaitu pemisahan dua jalur akseptasi:

• Jalur otomatis — profil calon tertanggung memenuhi seluruh kriteria, sehingga penutupan bisa langsung disetujui tanpa campur tangan manusia. Bank menerima jawaban dalam satu panggilan.
• Jalur peninjauan — profilnya di luar kriteria otomatis (misalnya nilai pertanggungan atau usia melewati ambang tertentu), sehingga perlu dokumen tambahan dan penilaian underwriter. Jawabannya tidak datang seketika.

Konsekuensinya besar: jalur kedua tidak bisa dilayani dengan pola tanya-jawab biasa. Ia butuh layanan untuk mengunggah kelengkapan dokumen, layanan untuk menyampaikan keputusan, dan layanan konfirmasi dari sisi bank bahwa keputusan itu sudah diterima. Satu percabangan bisnis melahirkan empat layanan teknis.

Respons berlapis dua

Kesalahan yang mudah dilakukan adalah mencampur "panggilan API-nya berhasil" dengan "pengajuannya diterima". Keduanya harus dipisah dan berada di lapisan berbeda:

Lapis 1 — Status teknis (apakah permintaan berhasil diproses)
  00  Berhasil ....... payload valid dan sudah terverifikasi
  01  Gagal .......... payload tidak lolos validasi / terjadi galat

Lapis 2 — Status bisnis (apa keputusan atas pengajuannya)
  Otomatis ........... memenuhi kriteria, bisa langsung ditutup
  Perlu peninjauan ... perlu dokumen tambahan dan penilaian manual

Pemisahan ini membuat penanganan di sisi bank jadi sederhana: lapis pertama menentukan apakah permintaan boleh dikirim ulang, lapis kedua menentukan layar apa yang ditampilkan ke petugas cabang. Bila keduanya dicampur, sisi pemanggil terpaksa menebak-nebak — dan tebakan itu selalu salah pada kasus paling langka.

Setiap kode punya instruksi tindakan

Daftar kode tanpa kolom "apa yang harus dilakukan" hanya jadi hiasan. Kolom terakhir inilah yang membedakan spesifikasi yang bisa langsung dikerjakan dari spesifikasi yang masih perlu ditanyakan:

Kelompok galat            Boleh kirim ulang?  Tindakan di sisi pemanggil
------------------------  ------------------  -----------------------------
Data tidak lengkap        Ya                  Perbaiki payload, kirim ulang
Nomor referensi duplikat  Tidak               Panggil layanan cek status
Produk tidak tersedia     Tidak               Hentikan, sampaikan ke petugas
Di luar kriteria produk   Tidak               Hentikan, tolak pengajuan
Sistem tujuan sibuk       Ya, berjeda         Ulangi bertingkat, maksimal 3x
Galat tak terduga         Tidak               Catat, eskalasi ke tim teknis

Nomor referensi sebagai tulang punggung

Kalau hanya satu hal yang boleh saya bawa dari pekerjaan ini, itu adalah: tentukan nomor referensi unik sejak layanan pertama, dan pakai nomor yang sama sampai transaksi selesai.

Nomor itu mengerjakan tiga tugas sekaligus:

1. Kunci idempotensi. Pengiriman kedua dengan nomor yang sama tidak membuat pengajuan baru, melainkan mengembalikan hasil pengajuan pertama. Ini menjawab pertanyaan yang pasti muncul di hari pertama pengujian: apa yang terjadi kalau permintaan terkirim dua kali?
2. Benang penelusuran. Pengajuan, kelengkapan dokumen, persetujuan, klaim, sampai pembatalan seluruhnya memakai nomor yang sama. Ketika terjadi selisih, satu nomor cukup untuk menarik seluruh riwayatnya di tiga sistem.
3. Kunci rekonsiliasi. Pencocokan berkala antara catatan bank dan catatan asuransi bertumpu pada nomor ini, bukan pada nama atau tanggal yang formatnya bisa berbeda-beda.

Spesifikasi medan data yang tidak menyisakan tafsir

Ini bagian paling panjang dan paling sering menyelamatkan proyek. Untuk tiap medan: nama, tipe, panjang maksimum, wajib atau tidak, format, dan contoh nilainya. Untuk medan bernilai terbatas, daftar nilainya ditulis lengkap — jangan pernah menulis “dan lain-lain”.

{
  // contoh ilustratif, bukan payload sebenarnya
  "nomorReferensi"  : "REF20260628000117",  // String(20), wajib, unik
  "kodeProduk"      : "01",                 // String(2), wajib, lihat lampiran
  "tanggalLahir"    : "1985-04-17",         // Date, wajib, format yyyy-MM-dd
  "tanggalAkad"     : "2026-06-28",         // Date, wajib, format yyyy-MM-dd
  "tenor"           : 120,                  // Integer, wajib, dalam satuan bulan
  "nilaiPertanggungan": 150000000,          // Decimal(18,2), tanpa pemisah ribuan
  "diajukanPada"    : "2026-06-28T09:14:22+07:00" // ISO 8601 + zona waktu
}

Tiga detail kecil di atas semuanya berasal dari pengalaman pahit:

• Zona waktu ditulis eksplisit. Tanpa itu, selisih tujuh jam akan ditemukan belakangan — biasanya pada transaksi lewat tengah malam yang tanggalnya jadi mundur sehari.
• Nilai uang tanpa pemisah ribuan. Satu sistem membaca titik sebagai desimal, sistem lain membacanya sebagai pemisah ribuan. Selisihnya bisa seribu kali lipat.
• Satuan ditulis di nama atau keterangan medan. tenor saja ambigu; “dalam satuan bulan” menghapus seluruh perdebatan.

Kodifikasi yang disepakati di muka

Karena perantara melayani banyak perusahaan asuransi, tiap panel dan tiap produk butuh kode yang disepakati dan didaftarkan di ketiga sistem sebelum integrasi dimulai. Terdengar sepele, tapi kode inilah yang menentukan permintaan diteruskan ke mana.

Dua aturan yang saya pegang: kode tidak pernah dipakai ulang untuk arti berbeda meski panelnya sudah tidak aktif, dan penambahan kode baru selalu jadi revisi dokumen dengan nomor versi — bukan kesepakatan lisan di grup percakapan.

Tiga kebiasaan yang paling membantu

• Beri nomor pada setiap ketentuan. Saat rapat, “butir 4.2.7” jauh lebih cepat disepakati daripada “yang soal format tanggal itu, lho”.
• Sertakan contoh nyata untuk setiap kasus. Satu contoh payload yang benar menyelesaikan lebih banyak pertanyaan daripada satu halaman penjelasan — termasuk contoh untuk kasus gagal, bukan hanya kasus berhasil.
• Catat riwayat revisi di halaman depan. Ketika tiga pihak memegang berkas dengan versi berbeda, halaman itu yang menyelamatkan. Nomor versi bukan formalitas; ia menjawab “kita sedang membahas dokumen yang sama atau tidak?”

Catatan penutup

Dokumen spesifikasi yang baik tidak membuat integrasi berjalan mulus dengan sendirinya. Yang ia lakukan adalah memindahkan pertanyaan-pertanyaan sulit ke depan, saat menjawabnya masih murah. Pada integrasi internal, asumsi yang salah bisa diperbaiki sore itu juga; pada integrasi lintas organisasi, satu asumsi yang salah berarti permintaan perubahan, rapat penyelarasan, penjadwalan ulang rilis di tiga sisi, lalu pengujian ulang dari awal.

Jadi kalau Anda ragu perlu mendokumentasikan sesuatu atau tidak, tanyakan ini: kalau developer di sisi seberang salah menebak bagian ini, berapa lama waktu yang terbuang? Bila jawabannya lebih dari sehari, tulis.