Ongkir Kode Pos vs Kecamatan: Mana Lebih Akurat untuk API?

Developer API · Edukasi

Kalkulasi ongkir berbasis kode pos umumnya lebih akurat daripada berbasis kecamatan, karena kode pos memetakan area pengiriman lebih granular dan menjadi acuan asli sistem tarif kurir modern. Satu kecamatan bisa mencakup beberapa kode pos dengan zona tarif berbeda, sehingga memilih di level kecamatan berisiko menghasilkan tarif yang kurang presisi. AgenWebsite Rate API mendukung keduanya: kirim postal_code untuk akurasi maksimal, atau subdistrict_id bila UI Anda memakai dropdown kecamatan — di balik layar, ID kecamatan tetap di-resolve ke kode pos.

Jawaban singkat

Gunakan kode pos jika tersedia. Kode pos adalah unit terkecil yang dipakai sistem tarif kurir untuk menentukan zona pengiriman, jadi hasilnya paling presisi. Kecamatan tetap valid dan nyaman untuk UI, tetapi karena satu kecamatan dapat memuat beberapa kode pos, pemetaan ke tarif bisa kurang tajam. AgenWebsite Rate API bersifat postal-code driven: bila Anda mengirim subdistrict_id, server otomatis me-resolve-nya ke kode pos sebelum menghitung tarif.

Kenapa kode pos lebih akurat

• Granularitas. Kode pos memecah wilayah lebih halus daripada kecamatan. Satu kecamatan besar dapat memiliki beberapa kode pos yang jatuh di zona tarif berbeda.
• Sesuai sumber tarif. Sistem agregator kurir yang menjadi sumber tarif menghitung berdasarkan kode pos asal dan tujuan, bukan nama kecamatan.
• Minim ambiguitas nama. Nama kecamatan bisa mirip atau berulang antar kota/kabupaten; kode pos numerik menghilangkan kebingungan itu.
• Konsisten lintas kurir. Karena semua kurir memakai kode pos sebagai basis, tarif antar kurir jadi lebih sebanding.

Karena itu AgenWebsite Rate API tidak bergantung pada field wilayah kosong bawaan agregator, melainkan me-resolve setiap input ke kode pos yang benar.

Kode pos vs kecamatan: perbandingan

Cara pakai keduanya di API

Tiap pihak (shipper & destination) diidentifikasi dengan salah satu: postal_code atau subdistrict_id.

Berbasis kode pos (paling akurat)

curl -X POST https://api.agenwebsite.com/v1/rates \
  -H "x-api-key: awk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "shipper":     { "postal_code": "40135" },
    "destination": { "postal_code": "10110" },
    "weight": 1000
  }'

Berbasis kecamatan (subdistrict_id)

Ambil subdistrict_id lebih dulu dari /v1/locations/search (lihat bagian berikut), lalu kirim:

curl -X POST https://api.agenwebsite.com/v1/rates \
  -H "x-api-key: awk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "shipper":     { "subdistrict_id": "3273140" },
    "destination": { "subdistrict_id": "3171010" },
    "weight": 1000
  }'

Resolve kecamatan → kode pos

Endpoint GET /v1/locations/search mencari data wilayah dan mengembalikan subdistrict_id beserta postal_code-nya — ideal untuk autocomplete di form checkout. Anda bisa memakai hasilnya untuk menampilkan pilihan kecamatan ke user namun tetap mengirim kode pos ke /v1/rates.

curl "https://api.agenwebsite.com/v1/locations/search?q=Dago&limit=5" \
  -H "x-api-key: awk_live_xxxxxxxx"

Contoh alur autocomplete di front-end (memanggil backend Anda, bukan API langsung dari browser):

async function cariLokasi(q) {
  const res = await fetch(`/api/locations?q=${encodeURIComponent(q)}`);
  const { data } = await res.json();
  // Tampilkan nama kecamatan ke user, simpan postal_code untuk request tarif.
  return data.map((loc) => ({
    label: `${loc.subdistrict_name}, ${loc.city} (${loc.postal_code})`,
    postal_code: loc.postal_code,
    subdistrict_id: loc.subdistrict_id,
  }));
}

Rekomendasi UX checkout

• Tampilkan kecamatan, kirim kode pos. Beri user dropdown/autocomplete kecamatan yang ramah, tetapi teruskan postal_code hasil resolve ke /v1/rates demi akurasi.
• Validasi kode pos manual. Bila user mengetik kode pos sendiri, konfirmasikan kecamatan yang cocok agar tidak salah zona.
• Debounce pencarian. Tunda pemanggilan /locations/search saat user mengetik untuk menghemat kuota.
• Cache pemetaan. Simpan hasil resolve kecamatan→kode pos di sisi Anda agar tidak berulang.

Detail parameter tiap endpoint tersedia di dokumentasi, dan ikhtisar produk di /products/developer-api/.

FAQ

Apakah ongkir berbasis kode pos selalu lebih akurat?

Pada umumnya ya, karena kode pos adalah unit terkecil yang dipakai sistem tarif kurir. Kecamatan bisa mencakup beberapa kode pos dengan zona berbeda, sehingga level kecamatan berpotensi kurang presisi.

Kalau saya hanya punya nama kecamatan, bagaimana?

Gunakan GET /v1/locations/search untuk mendapatkan subdistrict_id dan postal_code-nya, lalu kirim salah satunya ke /v1/rates. AgenWebsite Rate API akan me-resolve subdistrict_id ke kode pos secara otomatis.

Bolehkah mengirim postal_code dan subdistrict_id bersamaan?

Tidak. Tiap pihak harus diidentifikasi dengan tepat satu field. Mengirim keduanya (atau mengosongkan keduanya) menghasilkan error 400 validation_error.

Kenapa API tidak memakai field wilayah bawaan agregator?

Karena sistem tarif bersifat postal-code driven. AgenWebsite Rate API sengaja me-resolve setiap input ke kode pos yang benar demi konsistensi dan akurasi lintas kurir.

Apa yang terjadi jika kode pos tidak ditemukan?

Anda menerima 404 shipper_not_found atau 404 destination_not_found dengan amplop error yang menjelaskan field bermasalah, bukan response 200 kosong.