Mode test

Kunci test (ohk_test_...) memakai simulator OngkirHub. Kamu bisa menjalankan alur lengkap, dari cek tarif sampai pelacakan dan webhook, tanpa kurir yang datang dan tanpa memotong saldo sungguhan. Mulai integrasi dengan kunci test, lalu ganti ke kunci live saat siap.

Yang sama dan yang berbeda

	Kunci test	Kunci live
Endpoint, format permintaan, dan respons	Sama	Sama
Tarif dan layanan	Dari simulator, untuk uji coba	Dari kurir, harga sungguhan
Pesanan ke kurir	Tidak ada. Resi dan pelacakan disimulasikan.	Pesanan sungguhan, kurir menjemput atau menerima paket
Saldo	Saldo uji Rp10.000.000	Saldo OngkirHub kamu
Pembatalan	Langsung disetujui	Ditinjau tim OngkirHub bersama kurir
Batas pengiriman harian dan batas per pengiriman	Tidak berlaku	Berlaku
Batas permintaan	120 per 60 detik per kunci, 30 untuk tulis	Sama
Field livemode	false	true

Harga dari simulator tidak mencerminkan tarif kurir yang sebenarnya. Untuk melihat harga sungguhan, pakai kunci live untuk cek tarif atau buka cek ongkir.

Saldo uji

Kunci test membaca dan memakai saldo uji, bukan saldo sungguhan.

• Saldo uji dimulai dari Rp10.000.000 dan berkurang oleh pengiriman uji 30 hari terakhir. Pengiriman uji yang lebih lama tidak dihitung lagi, jadi saldo uji pulih dengan sendirinya.
• GET /v1/wallet dan GET /v1/wallet/transactions dengan kunci test menampilkan saldo uji dan mutasinya: hold saat pengiriman dibuat, capture saat kurir menerima pesanan, release bila gagal, dan refund bila pembatalan disetujui. Jenis mutasinya sama dengan mode live.
• Kalau saldo uji tidak cukup, POST /v1/shipments dijawab 402 wallet_insufficient_funds, sama seperti di mode live.
• Saldo uji tidak bisa diisi dan tidak pernah menjadi uang sungguhan.

Data test dan live terpisah

• Kunci test hanya melihat pengiriman test, kunci live hanya melihat pengiriman live. GET /v1/shipments/{id} untuk pengiriman dari mode lain dijawab 404 not_found.
• Penawaran dari POST /v1/rates dengan kunci test tidak bisa dipakai untuk membuat pengiriman dengan kunci live, dan sebaliknya.
• Idempotency-Key disimpan per mode. Untuk POST /v1/shipments, satu kunci tidak bisa dipakai di kedua mode.
• Setiap objek dan setiap event webhook punya field livemode. Simpan nilainya bersama data di sistemmu agar data uji tidak tercampur dengan data produksi.

Alur pengiriman uji

Pengiriman uji melewati status yang sama dengan pengiriman sungguhan: submitting, lalu booked beberapa detik setelah respons, lalu awb_ready dengan nomor resi simulasi, lalu status perjalanan sampai delivered.

• Resi simulasi terbit sekitar 20 detik sampai beberapa menit setelah pesanan diterima.
• Riwayat pelacakan bergerak selama sekitar 1 jam sampai paket terkirim, dan diperbarui berkala.
• Setiap perubahan status mengirim event webhook dengan livemode: false.

Resi simulasi bisa dilacak dengan GET /v1/tracking/{awb} memakai kunci test. Resi ini tidak dikenal kurir mana pun.

Mencoba skenario lain

Tanpa penanda, pengiriman uji berakhir dengan status delivered. Untuk menguji alur lain, tulis salah satu penanda ini di nama atau alamat penerima. Penanda hanya berlaku untuk kunci test.

Penanda	Hasil
[mock:courier_rejected]	Kurir menolak pesanan. Status failed, error.code bernilai courier_rejected, dan saldo uji dikembalikan.
[mock:problem], [mock:lost], [mock:failed_pickup], [mock:cancelled]	Pelacakan berakhir dengan kendala, status problem. Penanda [mock:cancelled] berarti kurir membatalkan di data pelacakan, jadi statusnya problem, bukan cancelled.
[mock:returned]	Paket diretur ke pengirim, status returned.
[mock:delivered] atau tanpa penanda	Paket terkirim, status delivered.

Pembatalan di mode test

Pembatalan dengan kunci test langsung disetujui, supaya alur pembatalan bisa diuji tanpa menunggu.

• POST /v1/shipments/{id}/cancel untuk pengiriman berstatus booked, awb_ready, atau problem dijawab 201 dengan status bernilai refunded, refundAmount sebesar total harga, dan reviewNote “Disetujui otomatis di mode test”.
• Pengiriman berpindah ke cancel_requested lalu cancelled, dan event shipment.status_updated serta shipment.cancelled dikirim dengan livemode: false.
• Saldo uji mendapat catatan refund.
• Pengiriman di status lain ditolak dengan 409 cancellation_not_allowed, sama seperti di mode live.

Di mode live, pembatalan tidak instan: responsnya berstatus requested, pengiriman menjadi cancel_requested, lalu tim OngkirHub meninjau bersama kurir sebelum saldo dikembalikan. Pastikan integrasimu menangani kedua alur ini.

Webhook di mode test

Satu endpoint webhook menerima event dari pengiriman test maupun live. Bedakan dengan field livemode di body event.

• Pengiriman yang dibuat dengan kunci test memicu event sungguhan dengan livemode: false.
• Tombol Kirim tes di menu Developer mengirim event webhook.test dengan livemode: false.
• Event topup.paid hanya berasal dari isi saldo sungguhan, jadi selalu livemode: true.

Panduan lengkapnya ada di Webhook.

Pindah ke live

Sebelum memakai kunci live, pastikan:

1. Integrasimu menangani 402 wallet_insufficient_funds, 409 quote_expired, pengiriman berstatus failed, dan pembatalan yang masih menunggu tinjauan (cancel_requested).
2. Setiap POST /v1/shipments memakai Idempotency-Key yang berasal dari pesananmu.
3. Endpoint webhook memverifikasi OngkirHub-Signature dan membuang event duplikat berdasarkan id.
4. Saldo OngkirHub cukup untuk pengiriman yang akan dibuat.
5. Kunci live disimpan di server produksi saja, terpisah dari kunci test.

Lalu buat kunci live di menu Developer dan ganti kunci di konfigurasi servermu. Endpoint dan kodenya tidak perlu diubah.