Integrasi API Ongkos Kirim di Checkout Toko Online

Untuk menampilkan ongkos kirim di checkout, toko online perlu mengirim empat data ke API tarif kurir: lokasi asal, lokasi tujuan, berat, dan dimensi paket. Bagian sulitnya jarang ada di pemanggilan API itu sendiri. Yang sering bermasalah justru sekelilingnya: menghitung berat yang benar dari isi keranjang, menyimpan tarif di cache agar checkout tetap cepat, dan tahu harus berbuat apa ketika API lambat atau mati saat pembeli sedang menunggu.

Prinsip yang layak dipegang: halaman checkout tidak boleh gagal total hanya karena satu API tarif bermasalah. Pembeli yang melihat pemutar loading selama sepuluh detik di langkah terakhir sering memilih menutup tab.

Data yang dibutuhkan API tarif

Nama field berbeda di setiap penyedia, tetapi isinya hampir selalu sama:

  • Asal: kode area gudang atau titik jemput, sesuai master data lokasi milik kurir.
  • Tujuan: kode area, kecamatan, atau kode pos penerima, juga sesuai master data kurir.
  • Berat aktual: biasanya dalam gram, termasuk berat kemasan.
  • Dimensi: panjang, lebar, dan tinggi kemasan dalam sentimeter.
  • Nilai barang: dipakai untuk asuransi atau layanan bayar di tempat.
  • Jenis layanan bila ingin membatasi hasil, misalnya hanya layanan reguler dan ekspres.

Sumber kerepotan terbesar biasanya master data lokasi. Setiap API punya daftar area dan ID-nya sendiri, dan alamat pembeli berupa teks bebas tidak bisa langsung dipakai. Simpan tabel pemetaan dari wilayah di sistem Anda ke ID area tiap kurir, dan pastikan pembeli memilih kecamatan atau kota dari daftar, bukan mengetik bebas. Topik ini dibahas lebih jauh di artikel validasi alamat penerima sebelum kirim.

Berat aktual dan berat volumetrik

Kurir menagih berdasarkan yang lebih besar antara berat aktual dan berat volumetrik. Berat volumetrik adalah berat “semu” yang dihitung dari ukuran kotak, karena paket besar tetapi ringan tetap memakan ruang di kendaraan. Rumus umumnya:

berat volumetrik (kg) = panjang × lebar × tinggi (cm) ÷ pembagi

Angka pembagi tidak seragam. Nilai seperti 5.000 atau 6.000 sering dipakai, tetapi bisa berbeda per kurir dan per layanan, jadi jadikan pembagi itu konfigurasi per layanan dan ambil angkanya dari dokumentasi masing-masing. Contoh: kotak 40 × 30 × 20 cm berisi bantal seberat 1,2 kg. Dengan pembagi 6.000, berat volumetriknya 24.000 ÷ 6.000 = 4 kg, sehingga yang ditagih 4 kg.

public final class ChargeableWeight {
    private ChargeableWeight() {}

    /** Berat yang ditagih dalam gram, dibulatkan ke atas. */
    public static long grams(long actualGrams, int lengthCm, int widthCm,
                             int heightCm, int divisor) {
        long volumeCm3 = (long) lengthCm * widthCm * heightCm;
        long volumetricGrams = (volumeCm3 * 1000 + divisor - 1) / divisor;
        return Math.max(actualGrams, volumetricGrams);
    }

    /** Contoh aturan pembulatan: naik ke kilogram berikutnya. */
    public static long roundUpToKg(long grams) {
        return ((grams + 999) / 1000) * 1000;
    }
}

Aturan pembulatan juga berbeda: ada yang membulatkan ke atas per kilogram, ada yang memberi toleransi beberapa ratus gram. Simpan aturan ini sebagai strategi per layanan, bukan satu fungsi global.

Dimensi untuk keranjang berisi banyak barang

Menjumlahkan dimensi tiap produk tidak menghasilkan ukuran kotak yang nyata. Pendekatan yang lebih masuk akal untuk kebanyakan toko adalah menyimpan daftar kardus standar yang benar-benar dipakai gudang, menjumlahkan volume dan berat barang, lalu memilih kardus terkecil yang muat. Hasilnya tidak sempurna, tetapi jauh lebih dekat ke tagihan kurir daripada menebak.

Cache tarif agar checkout tetap cepat

Tarif untuk rute dan berat yang sama jarang berubah dalam hitungan menit, jadi hasil API bisa disimpan sementara. Kunci cache yang baik memuat semua hal yang memengaruhi harga, dengan berat dibulatkan ke satuan yang dipakai kurir agar cache sering kena.

import com.github.benmanes.caffeine.cache.Cache;
import com.github.benmanes.caffeine.cache.Caffeine;
import java.time.Duration;
import java.util.List;

record RateKey(String courier, String originArea, String destinationArea, long weightKg) {}

Cache<RateKey, List<Rate>> rateCache = Caffeine.newBuilder()
        .expireAfterWrite(Duration.ofHours(6))
        .maximumSize(100_000)
        .build();

Cache di memori cukup untuk satu instans. Bila aplikasi berjalan di beberapa server, cache bersama seperti Redis mencegah tiap server memanggil API untuk rute yang sama. Simpan juga salinan “tarif terakhir yang diketahui” dengan umur lebih panjang di tempat terpisah. Salinan ini bukan untuk ditampilkan sebagai harga pasti, tetapi untuk cadangan saat API tidak bisa dihubungi.

Timeout dan fallback saat API lambat

Tentukan batas waktu yang tegas untuk koneksi dan respons, lalu jalankan panggilan ke beberapa kurir secara paralel. Tampilkan kurir yang menjawab tepat waktu, dan siapkan cadangan untuk yang tidak.

HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(2))
        .build();

HttpRequest request = HttpRequest.newBuilder(URI.create(rateUrl))
        .timeout(Duration.ofSeconds(3))
        .header("Authorization", "Bearer " + apiKey)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(requestJson))
        .build();

List<Rate> rates = client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenApply(response -> parseRates(response))   // lempar exception bila status bukan 2xx
        .completeOnTimeout(null, 3, TimeUnit.SECONDS)
        .exceptionally(error -> null)
        .join();

if (rates == null) {
    rates = fallbackRates(key);   // tarif terakhir yang diketahui, lalu tabel zona
}

Urutan cadangan yang umum dipakai:

  1. Tarif dari cache yang sudah lewat masa berlaku tetapi masih wajar, ditandai sebagai estimasi.
  2. Tabel tarif sederhana per zona yang Anda kelola sendiri dan diperbarui berkala.
  3. Menyembunyikan kurir yang bermasalah sambil tetap menampilkan kurir lain.
  4. Pilihan terakhir: pesanan tetap bisa dibuat, ongkir dikonfirmasi admin. Ini keputusan bisnis, jadi sepakati dulu dengan tim.

Jangan mengulang panggilan berkali-kali saat pembeli sedang menunggu. Satu kali percobaan ulang yang cepat masih wajar; selebihnya lebih baik pindah ke cadangan. Strategi retry yang lebih panjang cocok untuk proses di belakang layar, seperti yang dibahas di artikel retry dan exponential backoff.

Kunci tarif saat pesanan dibuat

Harga yang tampil di browser tidak boleh dipercaya begitu saja saat pesanan disimpan. Simpan hasil kutipan tarif di server dengan ID, waktu kutipan, kurir, layanan, dan harga. Saat pembeli menekan tombol bayar, server mencocokkan ID kutipan itu, memastikan isi keranjang dan alamat tidak berubah, dan memeriksa bahwa kutipan belum kedaluwarsa. Bila sudah kedaluwarsa, hitung ulang dan beri tahu pembeli bila harganya berubah.

Simpan juga berat dan dimensi yang dipakai saat kutipan. Ketika tagihan kurir nanti berbeda, data ini membantu menemukan apakah selisihnya berasal dari dimensi produk yang salah atau aturan pembulatan yang keliru.

FAQ

Perlukah memanggil API tarif setiap kali isi keranjang berubah?

Tidak perlu. Hitung tarif ketika alamat tujuan sudah dipilih dan pembeli masuk ke langkah pengiriman. Di halaman keranjang, perkiraan dari cache atau tabel zona sudah cukup.

Bagaimana bila produk belum punya data dimensi?

Pakai nilai bawaan per kategori produk, lalu buat laporan rutin berisi produk tanpa dimensi agar tim katalog melengkapinya. Selisih ongkir dari data kosong cenderung menumpuk tanpa terlihat.

Bolehkah tarif disimpan permanen di database?

Boleh sebagai riwayat dan bahan cadangan, asalkan selalu disertai waktu pengambilan. Tarif tanpa tanggal mudah dianggap masih berlaku padahal sudah usang.

Hendra Kurniawan

Oleh Hendra Kurniawan

Pengembang backend Java yang lama menangani integrasi sistem dan message broker. Menulis catatan praktis tentang JMS, API, dan arsitektur aplikasi.