Cara Menambahkan RajaOngkir ke PrestaShop

Sistem kurir bawaan PrestaShop bekerja berdasarkan range berat atau harga per zona. Model tersebut tidak pas dengan kurir di Indonesia, dimana ongkos kirim dihitung berdasarakan kota/kecamatan. Modul rajaOngkir menangani isu tersebut dengan menghitung ongkos kirim berdasarkan kota asal dan tujuan, berat barang dan banyak fitur lainnya seperti volumetrik dan asuransi.

Yang perlu disiapkan

• Akun RajaOngkir/Komerce dengan API key domestic destination & cost yang aktif.
• PrestaShop 9.1.x dengan tema berbasis Hummingbird (bawaan PrestaShop 9), serta ekstensi PHP curl aktif — instalasi akan gagal tanpa ini.
• Negara Indonesia harus ada dan berstatus aktif di Lokalisasi → Negara, karena modul mencari id_country dengan kode ISO ID saat instalasi.
• Berat produk yang akurat. Ini bagian yang paling sering disepelekan toko, padahal menentukan benar atau tidaknya ongkos kirim yang tampil ke pembeli.

Pasang modulnya

Pasang lewat Modules → Module Manager → Upload a module, atau lewat command line:

unzip rajaongkir.zip -d modules/
php bin/console prestashop:module install rajaongkir
php bin/console cache:clear

Saat instalasi, modul otomatis membuat zona pengiriman untuk Indonesia, data provinsi, format alamat, serta seluruh kurir dan layanan yang didukung (JNE, SiCepat, IDExpress, SAP Express, Ninja, J&T Express, TIKI, Wahana, POS Indonesia, Sentral Cargo, Lion Parcel, Royal Express Asia). Semua kurir ini aktif tapi belum tentu dicentang untuk dipakai — pemilihannya dilakukan di halaman konfigurasi.

Setelah terpasang, periksa bahwa modul muncul aktif di Module Manager, beberapa carrier baru muncul di Shipping → Carriers, dan negara Indonesia berada dalam zona pengiriman rajaongkir.

Konfigurasi API key

Buka Modules → Module Manager → RajaOngkir → Configure, isi API Key, lalu Save. Key ini disimpan di konfigurasi PrestaShop dan tidak pernah dikirim ke browser — seluruh permintaan ke API RajaOngkir dilakukan dari sisi server.

Setelah API key tersimpan, kolom Origin City akan aktif.

Set kota asal dengan benar

Ketik nama kota/kecamatan pada kolom Origin City (autocomplete mencari ke API RajaOngkir setelah minimal 3 karakter), pilih hasil yang sesuai, lalu klik Set Origin City.

Semua tarif dihitung dari titik ini, jadi kota asal yang salah membuat seluruh hasil ongkir salah untuk setiap pesanan.

Pilih kurir dan layanan

Di bagian Active carrier, centang kombinasi kurir + layanan yang ingin ditawarkan ke pelanggan, lalu Save. Hanya kurir yang dicentang di sini yang muncul di checkout dan dihitung tarifnya lewat API.

Semakin banyak kurir aktif, semakin banyak variasi tarif yang dihitung/diminta ke API dalam satu kali checkout — sebaiknya batasi hanya kurir yang benar-benar dipakai.

Atur berat dan volumetrik

RajaOngkir menghitung tarif berdasarkan berat, jadi berat produk di PrestaShop (dalam kg) harus diisi dengan benar.

Aktifkan Activate volumetric di Pengaturan umum bila Anda mengirim barang besar tapi ringan. Untuk kurir/layanan yang mengaktifkan Volumetric enabled di tabel aturan, berat yang dipakai untuk kalkulasi adalah nilai yang lebih besar antara berat aktual dan berat volumetrik: (Panjang × Lebar × Tinggi) / pembagi (nilai pembagi umum: 6000, dapat diatur per kurir).

Setiap kurir/layanan juga punya Min weight — jika berat total di bawah nilai ini, layanan tersebut otomatis disembunyikan dari checkout, berguna untuk mencegah paket ringan memakai layanan yang tidak cocok (mis. trucking).

Aktifkan asuransi pengiriman (opsional)

Asuransi dikonfigurasi per kurir/layanan lewat kolom Insurance (Off atau Optional) di tabel Volumetric and Weight Rules. Premi dihitung sebagai:

Premi = (Nilai barang diasuransikan × Insurance rate%) + Insurance admin fee

Nilai barang yang diasuransikan hanya menghitung produk yang ditandai Eligible for shipping insurance di tab Shipping pada halaman edit produk (aktif secara default untuk produk baru). Saat mode Optional, pelanggan akan melihat kotak centang tambahan di checkout tepat di bawah kurir yang dipilih.

Manfaatkan cache

Tanpa cache, setiap perubahan alamat di checkout memicu panggilan API baru ke RajaOngkir untuk tiap kurir aktif — pada koneksi lambat ini terasa sebagai jeda beberapa detik di halaman checkout.

Atur Cache duration (default 3 Months) di Pengaturan umum, dan gunakan tombol Clear delivery fee cache setelah mengganti kota asal, mengubah aturan volumetrik/asuransi, atau saat menguji perubahan tarif agar hasil lama tidak terus terpakai.

Uji coba sebelum go-live

Buat beberapa pesanan ke setidaknya tiga tujuan berbeda: dalam satu kota dengan kota asal, provinsi lain, dan pulau lain. Pastikan:

• Ongkos kirim muncul untuk seluruh kurir yang diaktifkan sesuai layanan yang dipilih.
• Layanan dengan aturan Min weight disembunyikan saat keranjang di bawah ambang beratnya, dan muncul kembali saat di atasnya.
• Keranjang dengan produk besar tapi ringan menghasilkan tarif lebih tinggi saat volumetrik diaktifkan.
• Kotak centang asuransi tampil untuk kurir bermode Optional, menghitung premi dengan benar, dan tidak tampil untuk kurir Off.
• Menghapus cache benar-benar memaksa permintaan baru ke API pada percobaan berikutnya.

Masalah yang umum terjadi

Modul gagal diinstal. Urutan pemeriksaan: ekstensi curl di server, data negara Indonesia di Lokalisasi → Negara, lalu izin berkas (user instalasi berbeda dari pemilik berkas PrestaShop).

Ongkos kirim tidak muncul di checkout. Cek berurutan: kurir belum dicentang di Active carrier, Origin City belum diatur, API key kosong/tidak valid, produk tanpa berat, berat di bawah Min weight layanan, atau carrier tidak berada dalam zona yang mencakup alamat tujuan.

Ongkos kirim berbeda dari yang diharapkan. Periksa seting volumetrik (aktif/nonaktif, angka pembagi) dan berat produk, lalu coba Clear delivery fee cache dan tes ulang.

Kotak centang asuransi tidak muncul. Pastikan mode Insurance kurir tersebut Optional, Insurance rate lebih dari 0%, dan minimal satu produk di keranjang ditandai eligible untuk asuransi.

Dokumentasi lengkap modul, termasuk changelog dan roadmap, tersedia di halaman dokumentasi RajaOngkir.