API Cek Ongkir Indonesia: Cara Hitung Ongkir JNE, POS, TIKI

API cek ongkir adalah layanan HTTP yang mengembalikan estimasi ongkos kirim antarwilayah di Indonesia berdasarkan kota asal, kota tujuan, berat, dan kurir. Di APIPedia, alurnya terdiri dari tiga endpoint: /ongkir/couriers untuk daftar kurir, /ongkir/search untuk mencari id wilayah, dan /ongkir/cek untuk menghitung estimasi ongkir per kurir.

Artikel ini membahas cara memakai ketiga endpoint itu dari nol, isi respons tiap endpoint, dan cara memasangnya di halaman checkout toko online. Semua contoh memakai base URL https://api.apipedia.id/v1 dan bisa dicoba dengan paket Free.

Apa yang perlu disiapkan sebelum memakai API ongkir Indonesia?

Anda hanya butuh satu API key. Buat akun di konsol APIPedia, buka menu Token API, lalu buat kunci baru. Kunci berawalan apk_ dan dikirim di setiap request lewat header Authorization: Bearer apk_xxx.

Paket Free gratis selamanya, dengan kuota 500 request per hari dan rate limit 10 request per detik. Untuk prototipe atau toko kecil, kuota ini biasanya cukup asalkan Anda menyimpan hasil yang sering dipakai di sisi server (dibahas di bagian caching di bawah).

Semua endpoint APIPedia memakai amplop respons yang sama: { is_success, message, data }. Jadi cukup cek is_success sebelum membaca data.

Bagaimana alur cek ongkir lewat API dari awal sampai akhir?

Alurnya selalu sama, apa pun bahasa pemrograman yang Anda pakai:

1. Ambil daftar kurir yang didukung lewat GET /ongkir/couriers. Cukup sekali, lalu simpan.
2. Cari id wilayah asal (gudang Anda) dengan GET /ongkir/search?q=.... Ini juga cukup sekali.
3. Saat pembeli mengisi alamat, cari id wilayah tujuan dengan GET /ongkir/search?q=....
4. Panggil GET /ongkir/cek dengan origin, destination, weight (gram), dan opsional courier.
5. Tampilkan daftar tarif sebagai pilihan pengiriman, lalu simpan pilihan pembeli bersama pesanannya.

Id wilayah bisa berupa id kabupaten/kota atau id kecamatan. Keduanya diterima oleh origin dan destination. Kalau id yang dikirim tidak dikenal, API membalas status 400 dengan pesan yang menyuruh Anda mencari id lewat /ongkir/search.

Bagaimana cara melihat daftar kurir yang didukung?

Endpoint GET /ongkir/couriers tidak butuh parameter. Ia mengembalikan jumlah dan array kurir berisi pasangan kode dan nama.

curl -s https://api.apipedia.id/v1/ongkir/couriers \
  -H "Authorization: Bearer apk_xxx"

Saat ini ada enam kode kurir yang bisa Anda pakai sebagai nilai parameter courier:

Kode	Nama layanan
jne_yes	JNE YES
jne_reg	JNE Reguler
pos_express	POS Express
pos_kilat	POS Kilat Khusus
tiki_express	TIKI Express
tiki_reguler	TIKI Reguler

Daftar ini jarang berubah, jadi ambil sekali saat aplikasi start atau saat build, lalu simpan. Jangan memanggilnya setiap kali pembeli membuka halaman checkout.

Bagaimana cara mencari id kota atau kecamatan asal dan tujuan?

Endpoint GET /ongkir/search menerima satu parameter wajib, q, berisi nama kabupaten atau kecamatan minimal 2 karakter. Hasilnya maksimal 20 wilayah, dengan kabupaten/kota ditampilkan lebih dulu, lalu kecamatan.

curl -s "https://api.apipedia.id/v1/ongkir/search?q=bandung" \
  -H "Authorization: Bearer apk_xxx"

Contoh potongan respons:

{
  "is_success": true,
  "message": "Ditemukan 2 wilayah yang cocok",
  "data": {
    "q": "bandung",
    "jumlah": 2,
    "hasil": [
      { "tipe": "kabupaten", "id": "3273", "nama": "KOTA BANDUNG", "provinsi": "Jawa Barat" },
      { "tipe": "kabupaten", "id": "3204", "nama": "KAB. BANDUNG", "provinsi": "Jawa Barat" }
    ]
  }
}

Tips memakai hasil pencarian

Perhatikan field tipe. Nilainya kabupaten atau kecamatan. Hasil bertipe kecamatan juga membawa field kabupaten, sehingga Anda bisa menampilkan label berisi nama kecamatan, kota, dan provinsi agar pembeli tidak salah pilih.

Nama yang mirip sering muncul berdua, seperti "KOTA BANDUNG" dan "KAB. BANDUNG". Karena itu, jangan otomatis mengambil hasil pertama. Tampilkan pilihan sebagai dropdown atau autocomplete, lalu simpan id-nya.

Bagaimana cara menghitung ongkir dengan endpoint /ongkir/cek?

Endpoint GET /ongkir/cek adalah inti dari API cek ongkir. Ia menerima id asal, id tujuan, berat dalam gram, dan opsional satu kode kurir, lalu mengembalikan daftar tarif per kurir beserta total estimasinya.

Parameter	Wajib	Keterangan
origin	Ya	Id kabupaten atau kecamatan asal, dari /ongkir/search.
destination	Ya	Id kabupaten atau kecamatan tujuan, dari /ongkir/search.
weight	Tidak	Berat kiriman dalam gram. Default 1000. Harus lebih besar dari 0.
courier	Tidak	Satu kode kurir, mis. jne_reg. Kosongkan untuk semua kurir.

curl -s "https://api.apipedia.id/v1/ongkir/cek?origin=3273&destination=3578&weight=1500" \
  -H "Authorization: Bearer apk_xxx"

Membaca respons /ongkir/cek

Respons berisi objek origin dan destination (tipe, id, nama, kabupaten, provinsi), berat_gram, berat_tagih_kg, dan array tarif. Setiap elemen tarif punya field berikut:

Field	Tipe	Arti
kurir	string	Kode kurir, mis. jne_reg.
nama	string	Nama layanan untuk ditampilkan, mis. "JNE Reguler".
per_kg	number	Estimasi tarif per kilogram ke wilayah tujuan, dalam rupiah.
total	number	per_kg dikali berat_tagih_kg.

Bagaimana berat dihitung?

Berat ditagihkan per kilogram, dibulatkan ke atas, minimal 1 kg. Kiriman 1500 gram menjadi berat_tagih_kg: 2, sedangkan 300 gram tetap dihitung 1 kg. Kurir yang tidak punya data tarif untuk tujuan tertentu tidak ikut dikeluarkan, bukan ditampilkan dengan nilai nol. Jadi jumlah elemen tarif bisa kurang dari enam.

Seberapa akurat hasil API cek ongkir ini?

Ini bagian yang perlu Anda pahami sebelum memakainya di produksi. Angka dari /ongkir/cek adalah estimasi yang dihitung dari dataset tarif statis, bukan hasil panggilan langsung ke sistem kurir dan bukan tarif resmi kurir. Pesan respons pun menyatakannya: "estimasi berdasarkan data statis, bukan tarif resmi kurir".

Dataset itu menyimpan tarif per kilogram untuk setiap wilayah tujuan. Artinya, wilayah asal saat ini dipakai sebagai keterangan pada respons, sedangkan besar tarif ditentukan oleh tujuan. Kiriman dari Bandung dan dari Medan ke Surabaya akan mendapat estimasi per kilogram yang sama.

Konsekuensinya praktis: gunakan API ini untuk menampilkan perkiraan biaya kirim, membandingkan kurir, atau menghitung subsidi ongkir secara kasar. Jangan menagihkan angka ini apa adanya kepada pembeli tanpa margin, dan cocokkan dengan tarif kurir saat pembuatan resi.

Bagaimana mengintegrasikan cek ongkir ke checkout toko online?

Pola paling aman adalah memanggil APIPedia dari backend Anda, bukan langsung dari browser. API key tetap tersimpan di server, dan Anda bisa menambahkan cache serta margin ongkir di satu tempat.

1. Simpan id wilayah gudang Anda di konfigurasi, misalnya ORIGIN_ID=3273.
2. Buat endpoint backend /api/wilayah?q= yang meneruskan ke /ongkir/search, untuk autocomplete alamat di form checkout.
3. Saat pembeli memilih wilayah, frontend mengirim destination dan isi keranjang ke backend.
4. Backend menjumlahkan berat produk (gram), memanggil /ongkir/cek, menambahkan margin, lalu mengembalikan pilihan kurir.
5. Saat pesanan dibuat, hitung ulang ongkir di server dan simpan kode kurir beserta nilainya, agar angka yang dikirim browser tidak bisa dimanipulasi.

Contoh kode backend dengan JavaScript (fetch)

Contoh berikut berjalan di Node.js 18 ke atas, yang sudah punya fetch bawaan. Kunci dibaca dari variabel lingkungan.

const BASE = "https://api.apipedia.id/v1";
const headers = { Authorization: `Bearer ${process.env.APIPEDIA_KEY}` }; // apk_xxx

async function panggil(path, params) {
  const url = `${BASE}${path}?${new URLSearchParams(params)}`;
  const res = await fetch(url, { headers });
  const body = await res.json();
  if (!body.is_success) throw new Error(body.message);
  return body.data;
}

export async function cariWilayah(q) {
  if (q.trim().length < 2) return [];
  const data = await panggil("/ongkir/search", { q });
  return data.hasil.map((w) => ({
    id: w.id,
    label: [w.nama, w.kabupaten, w.provinsi].filter(Boolean).join(", "),
  }));
}

export async function opsiPengiriman(destination, keranjang) {
  const weight = keranjang.reduce((n, item) => n + item.beratGram * item.qty, 0);
  const data = await panggil("/ongkir/cek", {
    origin: process.env.ORIGIN_ID,
    destination,
    weight: Math.max(weight, 1),
  });
  return data.tarif
    .map((t) => ({ kurir: t.kurir, nama: t.nama, ongkir: Math.ceil(t.total * 1.1) }))
    .sort((a, b) => a.ongkir - b.ongkir);
}

Margin 10% di contoh hanyalah ilustrasi. Sesuaikan dengan kebijakan toko Anda, misalnya membulatkan ke ribuan terdekat atau memberi gratis ongkir di atas nilai belanja tertentu.

Menghemat kuota dengan caching

Hasil /ongkir/couriers dan /ongkir/search hampir tidak pernah berubah, jadi aman disimpan berjam-jam. Untuk /ongkir/cek, gunakan kunci cache gabungan destination dan berat_tagih_kg, karena tarif hanya bergantung pada tujuan dan berat yang sudah dibulatkan. Dengan cara ini, kuota 500 request per hari pada paket Free bisa melayani jauh lebih banyak sesi checkout.

Bagaimana menangani error dari API ongkir?

Parameter yang salah dijawab dengan status 400 dan is_success: false, beserta pesan yang jelas. Kasus yang paling sering:

• q kosong atau kurang dari 2 karakter pada /ongkir/search.
• Id origin atau destination tidak ditemukan.
• weight bukan angka atau bernilai 0 atau negatif.
• courier berisi kode yang tidak dikenal. Pesan error menyebutkan daftar kode yang valid.

Tampilkan pesan yang ramah ke pembeli, misalnya "Ongkir belum bisa dihitung, coba pilih kecamatan lain", dan catat pesan aslinya di log server. Jika API mengembalikan tarif kosong, sediakan opsi cadangan seperti tarif flat atau konfirmasi manual oleh admin.

Pertanyaan yang sering diajukan

Apakah API cek ongkir APIPedia gratis?

Ya, endpoint ongkir bisa dipakai dengan paket Free yang gratis selamanya. Kuotanya 500 request per hari dengan rate limit 10 request per detik. Anda cukup membuat API key di menu Token API pada konsol.

Apakah tarif yang keluar sama dengan tarif resmi JNE, POS, atau TIKI?

Tidak. Angkanya adalah estimasi dari dataset tarif statis per wilayah tujuan, bukan hasil panggilan ke API kurir. Gunakan sebagai perkiraan di checkout dan cocokkan dengan tarif kurir saat membuat resi.

Bisakah saya memakai id kecamatan, bukan hanya kota?

Bisa. Parameter origin dan destination menerima id kabupaten/kota maupun id kecamatan dari /ongkir/search. Id kecamatan memberi label alamat yang lebih spesifik di respons.

Bagaimana kalau saya butuh data wilayah atau kode pos yang lebih lengkap?

Untuk form alamat yang lengkap sampai kelurahan dan kode pos, gabungkan dengan API wilayah. Penjelasannya ada di artikel API data wilayah dan kode pos Indonesia. Jika pembeli mengunggah KTP saat verifikasi, lihat juga API OCR KTP Indonesia.

Bisakah asisten AI memanggil API ongkir ini?

Bisa, lewat server MCP APIPedia. Langkah-langkahnya dibahas di cara menghubungkan APIPedia ke Claude lewat MCP.

Mulai cek ongkir sekarang

Tiga endpoint, satu API key, dan Anda sudah punya estimasi ongkir untuk enam layanan kurir di halaman checkout. Daftar di console.apipedia.id, buat kunci di menu Token API, lalu coba perintah curl di atas. Setelah hasilnya keluar, pindahkan logikanya ke backend toko Anda dan tambahkan cache.