FAQ Developer API dan webhook

Panduan lengkapnya ada di Referensi API dan Webhook.

Kunci dan akses

Bagaimana cara mendapatkan kunci API?

Masuk ke OngkirHub App sebagai pemilik atau admin, buka menu Developer, lalu tekan Buat kunci di tab Kunci API. Kunci lengkap hanya ditampilkan sekali, jadi simpan langsung di servermu. Langkahnya ada di Autentikasi dan kunci API.

Apa beda kunci test dan kunci live?

Kunci test (ohk_test_) memakai simulasi: tidak ada kurir yang datang dan saldo sungguhan tidak tersentuh. Kunci live (ohk_live_) membuat pesanan sungguhan ke kurir dan memotong saldo OngkirHub. Detailnya ada di Mode test.

Kunci API saya hilang, bisakah ditampilkan lagi?

Tidak. Buat kunci baru, pasang di servermu, lalu cabut kunci lama di menu Developer.

Bisakah API dipanggil dari browser atau aplikasi mobile?

Tidak disarankan dan tidak didukung. API tidak mengirim header CORS, dan kunci API tidak boleh berada di perangkat pengguna. Panggil API dari servermu.

Biaya dan pembayaran

Apakah ada biaya untuk memakai API?

Tidak ada biaya tambahan untuk API. Saat peluncuran, OngkirHub tidak memungut biaya layanan, jadi pengiriman lewat API dibayar sesuai ongkir kurir dan asuransi bila dipilih.

Bagaimana pengiriman lewat API dibayar?

Selalu dari saldo OngkirHub. Total harga ditahan saat POST /v1/shipments diterima, lalu terpakai setelah kurir menerima pesanan.

Bagaimana membaca saldo dari sistemku?

Pakai GET /v1/wallet untuk saldo tersedia dan saldo ditahan, dan GET /v1/wallet/transactions untuk mutasinya. Isi saldo tetap dilakukan dari menu Saldo di aplikasi. Event webhook topup.paid memberi tahu saat isi saldo masuk.

Pengiriman dan pelacakan

Kenapa POST /v1/shipments mengembalikan status submitting?

Pesanan diteruskan ke kurir beberapa detik setelah respons. Status lalu berubah menjadi booked, kemudian awb_ready saat resi terbit, atau failed bila kurir menolak. Pantau lewat webhook atau GET /v1/shipments/{id}.

Bagaimana mencegah pengiriman ganda?

Kirim header Idempotency-Key yang unik per pesanan di setiap POST /v1/shipments. Permintaan ulang dengan kunci dan isi yang sama mendapat respons yang sama tanpa diproses dua kali. Lihat Idempotency-Key.

Bisakah melacak resi yang tidak dibuat lewat OngkirHub?

Bisa untuk JNE, J&T Express, dan AnterAja. Kirim parameter courier di GET /v1/tracking/{awb}, dan untuk JNE tambahkan verification berisi 5 digit terakhir nomor HP penerima. Resi kurir lain hanya bisa dilacak bila dibuat lewat OngkirHub.

Bisakah membatalkan pengiriman lewat API?

Bisa diajukan dengan POST /v1/shipments/{id}/cancel untuk pengiriman berstatus booked, awb_ready, atau problem. Pengajuan ditinjau tim OngkirHub bersama kurir. Bila disetujui, status menjadi cancelled, saldo dikembalikan, dan event shipment.cancelled dikirim. Dengan kunci test, pembatalan langsung disetujui supaya alurnya mudah diuji.

Berapa batas permintaan API?

120 permintaan per 60 detik per kunci, dan 30 per 60 detik untuk membuat pengiriman dan pembatalan. Detailnya ada di Batas permintaan.

Webhook

Bagaimana memastikan webhook benar dari OngkirHub?

Verifikasi header OngkirHub-Signature: hitung HMAC SHA-256 dengan secret endpoint atas t, titik, dan body mentah, lalu bandingkan dengan v1. Contoh kode Node.js, PHP, dan Python ada di Verifikasi tanda tangan.

Webhook tidak masuk ke serverku, apa yang perlu dicek?

1. Endpoint berstatus Aktif di tab Webhook dan event yang kamu tunggu sudah dipilih.
2. URL memakai HTTPS, bisa diakses dari internet, dan tidak mengarahkan ke URL lain.
3. Servermu menjawab 2xx dalam 10 detik.
4. Tab Log webhook menunjukkan status dan respons setiap kiriman. Tekan Kirim tes untuk mencoba ulang dari awal.

Endpoint yang gagal 20 kali berturut-turut dinonaktifkan otomatis. Perbaiki servermu, lalu pilih Aktifkan lagi.

Kenapa event yang sama masuk dua kali?

Webhook dikirim setidaknya sekali, jadi satu event bisa tiba lebih dari sekali. Simpan id event yang sudah diproses dan abaikan event dengan id yang sama.

Apakah ada spesifikasi OpenAPI?

Ada. Dokumen OpenAPI 3.1 tersedia di https://api.ongkirhub.com/v1/openapi.json tanpa kunci, dan bisa diunduh dari Referensi API.