Modul RajaOngkir untuk PrestaShop

Jika Anda ingin ongkos kirim segera tampil di toko Anda, langsung ke Ringkasan.

Requirement

Pastikan hal-hal dibawah sudah terpenuhi sebelum proses instalasi.

Ringkasan

1. Pasang modul (lihat Instalasi).
2. Buka Modules → Module Manager, cari RajaOngkir, lalu klik Configure.
3. Isi API Key RajaOngkir/Komerce dan klik Save.
4. Ketik nama kota asal pada kolom Origin City, pilih hasil autocomplete yang sesuai, lalu klik Set Origin City.
5. Pada bagian Active carrier, centang kurir/layanan yang ingin ditampilkan di checkout, lalu Save.
6. (Opsional) Atur volumetrik, berat minimum, dan asuransi pengiriman per layanan kurir pada tabel aturan di bagian bawah halaman konfigurasi.
7. (Opsional) Buka halaman edit produk → tab Shipping untuk menandai produk yang berhak diasuransikan.
8. Buat order baru, tes ke alamat Indonesia yang valid dan pastikan ongkos kirim serta (jika diaktifkan) opsi asuransi tampil dengan benar.

Instalasi

Dari Back Office

Buka Modules → Module Manager → Upload a module lalu pilih file rajaongkir.zip. PrestaShop akan memasang dan mengaktifkan modul secara otomatis.

Cara lain, gunakan cara CLI di bawah.

Dari command line

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

Apa yang terjadi saat instalasi

Proses instalasi modul, akan secara otomatis:

• Membuat zona pengiriman dan menautkannya ke negara serta seluruh provinsi (state) Indonesia untuk pengiriman domestik dan internasional.
• Membuat ulang data provinsi untuk Indonesia dari data internal modul.
• Menyesuaikan format alamat untuk Indonesia.
• Membuat kurir dan layanannya yang didukung (contoh: JNE REG, JNE YES, SiCepat BEST, TIKI ECO, dan seterusnya), lengkap dengan pengaturan dan logo kurir.
• Membuat tabel database.

Kurir yang akan dibuat cukup banyak (satu per layanan kurir) dan semuanya aktif tapi belum tentu dipilih untuk dipakai. Pemilihan kurir mana yang akan tampil di halaman checkout, diseting di halaman konfigurasi (lihat Kurir dan layanan).

Memverifikasi instalasi

Setelah terpasang, periksa:

• Modul RajaOngkir muncul di Modules → Module Manager dengan status aktif.
• Beberapa carrier baru (mis. JNE REG, TIKI ECO) muncul di Shipping → Carriers.
• Negara Indonesia berstatus aktif dan berada dalam zona pengiriman rajaongkir.
• Halaman Configure modul tidak kosong/blank.

Zona pengiriman yang tidak berisi negara Indonesia, atau carrier yang tidak dicentang di pengaturan modul, adalah penyebab paling umum ongkos kirim tidak muncul.

Konfigurasi

Semua pengaturan modul berada di satu halaman: Modules → Module Manager → RajaOngkir → Configure.

Koneksi API

Klik Save untuk menyimpan API key. Setelah API key terisi, kolom Origin City akan aktif.

Kota asal (origin)

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

1. Ketik nama kota/kecamatan pada kolom Origin City (autocomplete akan mencari ke API RajaOngkir setelah minimal 3 karakter).
2. Pilih salah satu hasil yang sesuai.
3. Klik Set Origin City.

Kurir dan layanan

Bagian Active carrier menampilkan seluruh kombinasi kurir + layanan yang didukung modul (JNE, SiCepat, IDExpress, SAP Express, Ninja, J&T Express, TIKI, Wahana, POS Indonesia, Sentral Cargo, Lion Parcel, Royal Express Asia beserta layanannya masing-masing seperti REG, YES, BEST, dll).

Centang kurir/layanan yang akan ditawarkan ke pelanggan, lalu klik Save. Hanya kurir yang dicentang di sini yang akan:

• Muncul sebagai opsi pengiriman di checkout.
• Dihitung tarifnya lewat API RajaOngkir.

Semakin banyak kurir yang aktif, semakin banyak pula variasi tarif yang mungkin dihitung/diminta ke API pada satu kali checkout. Sebaiknya batasi kurir yang benar-benar Anda pakai.

Pengaturan umum

Tombol Clear delivery fee cache di bagian atas halaman menghapus seluruh cache tarif secara manual. Gunakan setelah mengganti kota asal atau saat menguji perubahan tarif agar hasil lama tidak terus terpakai, atau saat menerima pemberitahuan jika tarif kurir naik.

Berat dan volumetrik

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

Seting Activate volumetric di bagian Pengaturan umum bersifat global. Bila nonaktif, seluruh perhitungan volumetrik diabaikan meskipun diaktifkan per layanan di tabel aturan.

Bila aktif, untuk setiap kurir/layanan yang mengaktifkan Volumetric enabled di tabel aturan (lihat Aturan per kurir), berat yang dipakai untuk kalkulasi tarif adalah nilai yang lebih besar antara:

• Berat aktual produk dalam keranjang, dan
• Berat volumetrik: (Panjang × Lebar × Tinggi) / pembagi.

Nilai pembagi dapat diatur per kurir/layanan, karena tiap kurir menerapkan nilai yang berbeda-beda. Nilai umum yang dipakai adalah 6000.

Aturan per kurir

Tabel Volumetric and Weight Rules di bagian bawah halaman konfigurasi berisi satu baris per kurir/layanan yang tersedia (bukan hanya yang sedang aktif), dengan kolom:

Klik Save rules untuk menyimpan seluruh baris sekaligus.

Asuransi pengiriman

Asuransi dikonfigurasi per kurir/layanan melalui kolom Insurance pada tabel aturan di atas:

• Off — tidak ada asuransi untuk layanan ini.
• Optional — pelanggan melihat kotak centang opsional di halaman checkout, tepat di bawah opsi kurir yang dipilih, dengan teks seperti “Add shipping protection for Rp X (Rp Y)” (nilai barang yang diasuransikan dan besaran premi).
• Required — (dipakai sebagai penanda; kotak centang opsional tetap muncul mengikuti alur optional pada versi saat ini).

Premi dihitung sebagai:

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

Nilai barang yang diasuransikan adalah total harga (termasuk pajak) dari item-item di keranjang yang produknya ditandai eligible untuk asuransi — lihat Pengaturan produk. Produk yang tidak ditandai eligible tidak ikut dihitung ke nilai asuransi walaupun ada di keranjang yang sama.

Pilihan asuransi pelanggan (kurir mana yang diasuransikan) disimpan per keranjang dan mengikuti kurir yang sedang dipilih pelanggan pada saat itu. Jika pelanggan berganti kurir sebelum menyelesaikan pesanan, status asuransi mengikuti kurir yang aktif saat form pengiriman dikirim.

Pengaturan produk

Buka Catalog → Products, pilih produk, lalu buka tab Shipping. Anda akan menemukan seting:

Eligible for shipping insurance When shipping insurance is offered at checkout, this product’s price is included in the insured value calculation.

• Aktif (default untuk produk baru): harga produk ikut dihitung ke dalam nilai barang yang diasuransikan saat pelanggan memilih kurir dengan asuransi Optional/Required.
• Nonaktif: produk tidak pernah ikut dihitung ke nilai asuransi, meskipun kurir yang dipilih mendukung asuransi.

Pengaturan ini tidak mempengaruhi berat/dimensi produk, hanya mempengaruhi kelayakan asuransi.

Cache

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

Gunakan Clear delivery fee cache setelah:

• Mengganti kota asal (origin).
• Mengubah aturan volumetrik/berat minimum/asuransi.
• Melakukan pengujian tarif dan ingin memastikan hasil terbaru yang tampil, bukan hasil lama yang tersimpan.
• Ada kenaikan tarif dari kurir.

Pengujian 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 di konfigurasi.
• Alamat baru maupun alamat yang sudah ada tersimpan dengan benar berikut data tujuan RajaOngkir-nya (provinsi/kota/kecamatan/kode pos).
• Layanan dengan aturan Min weight disembunyikan saat keranjang di bawah ambang beratnya, dan muncul kembali saat di atasnya.
• Keranjang dengan produk berdimensi besar tapi ringan menghasilkan tarif yang lebih tinggi saat volumetrik diaktifkan (dibandingkan saat dinonaktifkan).
• Kotak centang asuransi tampil untuk kurir dengan mode Optional, menghitung premi dengan benar, dan tidak tampil untuk kurir dengan mode Off.
• Produk yang ditandai tidak eligible asuransi benar-benar tidak menambah nilai barang yang diasuransikan.
• Menghapus cache (Clear delivery fee cache) benar-benar memaksa permintaan baru ke API pada percobaan berikutnya.

Uninstall

Dari Back Office

Buka Modules → Module Manager → RajaOngkir → Uninstall. Proses ini akan:

• Menonaktifkan (soft delete) seluruh carrier yang dibuat modul.
• Mengalihkan PS_CARRIER_DEFAULT toko ke carrier lain yang masih aktif, jika ada.
• Menghapus konfigurasi modul.
• Menghapus tabel database milik modul.

Dari command line

php bin/console prestashop:module uninstall rajaongkir
php bin/console cache:clear

Jika hanya ingin mengembalikan modul ke pengaturan awal tanpa mencopotnya, gunakan tombol Reset di Module Manager — ini menjalankan uninstall lalu install ulang secara berurutan, sehingga seluruh data di atas ikut terhapus dan dibuat ulang dari nol.

Troubleshooting

Modul gagal diinstal

Urutan kemungkinan penyebab:

1. Ekstensi PHP curl tidak aktif di server.
2. Data negara Indonesia tidak ada atau nonaktif di Lokalisasi → Negara.
3. Instalasi dijalankan sebagai user yang berbeda dari pemilik berkas PrestaShop (masalah izin berkas).

Ongkos kirim tidak muncul di checkout

Urutan kemungkinan penyebab:

1. Kurir/layanan yang bersangkutan belum dicentang di Active carrier.
2. Kota asal (Origin City) belum diatur.
3. API key belum diisi atau sudah tidak valid.
4. Produk di keranjang tidak memiliki berat, sehingga kalkulasi API gagal.
5. Berat keranjang berada di bawah Min weight layanan tersebut, sehingga layanan sengaja disembunyikan.
6. Carrier tidak berada dalam zona yang mencakup alamat tujuan pelanggan.

Ongkos kirim berbeda dari yang diharapkan

Periksa berurutan: pengaturan volumetrik (aktif/nonaktif, angka pembagi), berat produk, dan apakah cache masih menyimpan hasil lama — coba Clear delivery fee cache lalu tes ulang.

Kotak centang asuransi tidak muncul

Periksa: mode Insurance kurir tersebut harus Optional (bukan Off), Insurance rate (%) harus lebih dari 0, dan minimal ada satu produk di keranjang yang ditandai Eligible for shipping insurance.

Halaman konfigurasi kosong/blank

Biasanya karena masalah permission. Periksa log error server.

Changelog

Roadmap

Rencana pengembangan berikut bersifat indikatif — urutan dan waktu rilis dapat berubah mengikuti kebutuhan pengguna dan perubahan API RajaOngkir/Komerce.

Punya kebutuhan yang belum ada di daftar ini? Sampaikan ke kami, permintaan dari pengguna berlisensi akan menjadi pertimbangan utama.

Lisensi dan dukungan

Modul ini adalah perangkat lunak komersial berlisensi berbayar milik prestaidn. Anda tidak diperkenankan mendistribusikan ulang, menjual kembali, atau memasang modul ini di toko/domain lain di luar yang diizinkan oleh lisensi yang dibeli.

Modul ini tidak berafiliasi dan tidak bekerja sama secara resmi dengan RajaOngkir maupun PT Kurir Kirim Bersama (Komerce). “RajaOngkir” adalah merek dagang milik Komerce; modul ini hanya memanfaatkan layanan API publik yang disediakan secara independen.

Untuk kebutuhan kustomisasi (mis. penambahan gudang/origin lain atau integrasi tambahan), silahkan hubungi kami, jangan mengubah langsung modul agar pembaruan versi berikutnya tetap aman dipasang.