Referensi API

REST API OngkirHub untuk cek tarif, membuat resi, melacak paket, dan membaca saldo dari sistem kamu sendiri.

Base URL

https://api.ongkirhub.com/v1. Semua permintaan dan respons memakai JSON (UTF-8). Uang selalu dalam rupiah bilangan bulat, berat dalam kg, waktu dalam ISO 8601 (UTC, kecuali jadwal jemput yang memakai +07:00).

Autentikasi

Buat kunci API di menu Developer aplikasi OngkirHub, lalu kirim di setiap permintaan:

Authorization: Bearer ohk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Kunci hanya ditampilkan sekali saat dibuat. Simpan di server kamu, jangan di aplikasi browser atau aplikasi mobile: API ini tidak mengirim header CORS, jadi panggil dari backend kamu.

Setiap kunci punya akses (scope). Endpoint menolak kunci tanpa akses yang dibutuhkan dengan 403 forbidden:

• locations:read: Cari lokasi
• couriers:read: Daftar kurir
• rates:read: Cek ongkir
• shipments:read: Lihat pengiriman
• shipments:write: Buat dan batalkan pengiriman
• tracking:read: Lacak resi
• wallet:read: Lihat saldo dan mutasi

Mode test dan live

• Kunci ohk_test_... memakai simulasi: tarif, resi, dan pelacakan dibuat oleh simulator OngkirHub, tidak ada kurir yang datang dan saldo sungguhan tidak tersentuh. Mode test memakai saldo uji Rp10.000.000 yang berkurang oleh pengiriman uji 30 hari terakhir.
• Kunci ohk_live_... membuat pesanan sungguhan ke kurir dan memotong saldo OngkirHub kamu.

Data kedua mode terpisah: kunci test hanya melihat pengiriman test, kunci live hanya melihat pengiriman live, dan penawaran dari satu mode tidak bisa dipakai di mode lain. Setiap objek punya field livemode.

Di mode test, resi simulasi terbit sekitar 20 detik sampai beberapa menit setelah pesanan diterima, lalu riwayat pelacakan bergerak selama sekitar 1 jam sampai terkirim. Untuk mencoba skenario lain, tulis salah satu penanda ini di nama atau alamat penerima (hanya berlaku untuk kunci test):

• [mock:courier_rejected]: kurir menolak pesanan, status failed dan saldo uji dikembalikan.
• [mock:problem], [mock:lost], [mock:failed_pickup], [mock:cancelled]: pelacakan berakhir dengan kendala (status problem).
• [mock:returned]: paket diretur ke pengirim (status returned).

Pembatalan dari kunci test langsung disetujui: pengiriman berpindah ke cancel_requested lalu cancelled, event shipment.status_updated dan shipment.cancelled terkirim, dan saldo uji kembali. Di mode live, pembatalan tetap ditinjau tim OngkirHub.

Alur membuat resi

1. Cari wilayah asal dan tujuan dengan GET /v1/locations.
2. Cek tarif dengan POST /v1/rates. Respons berisi id penawaran (berlaku 30 menit) dan daftar layanan.
3. Buat pengiriman dengan POST /v1/shipments: kirim isi yang sama dengan langkah 2, ditambah quoteId, rateCode, dan pickupTime untuk PICKUP. Total harga ditahan dari saldo dan pengiriman berstatus submitting.
4. Pesanan diteruskan ke kurir beberapa detik setelah respons. Status berubah menjadi booked, lalu awb_ready saat resi terbit, atau failed jika kurir menolak (saldo yang ditahan dikembalikan). Pantau lewat webhook atau GET /v1/shipments/{id}.

Idempotency-Key

Semua POST menerima header Idempotency-Key (1 sampai 100 karakter: huruf, angka, ., _, :, -). Permintaan ulang dengan kunci dan isi yang sama dalam 24 jam mendapat respons yang tersimpan, dengan header Idempotent-Replayed: true, tanpa diproses dua kali. Kunci yang sama dengan isi berbeda ditolak dengan idempotency_key_reused; selama permintaan pertama masih diproses, ulangan mendapat 409 idempotency_conflict. Respons error 5xx dan 429 tidak disimpan, jadi aman diulang. Kirim header ini di setiap POST /v1/shipments: di sana kunci juga tersimpan di pengiriman tanpa batas waktu, jadi setelah 24 jam kunci dan isi yang sama mengembalikan pengiriman yang sudah ada, sedangkan isi berbeda atau mode lain mendapat 409 idempotency_conflict. Satu penawaran hanya untuk satu pengiriman; memakainya lagi dengan kunci baru juga mendapat 409 idempotency_conflict dengan details.shipmentId.

Paginasi

Daftar memakai cursor: { "data": [...], "hasMore": true, "nextCursor": "..." }. Kirim nextCursor sebagai parameter cursor untuk halaman berikutnya, dengan filter yang sama. limit 1 sampai 100, default 20. Daftar tidak menyertakan jumlah total: lanjutkan selama hasMore bernilai true.

Batas permintaan

120 permintaan per 60 detik per kunci, dan 30 per 60 detik untuk membuat pengiriman dan pembatalan. Setiap respons membawa RateLimit-Limit, RateLimit-Remaining, dan RateLimit-Reset (detik). Saat terlampaui, API menjawab 429 rate_limited dengan Retry-After. Body maksimal 64 KB.

Log API di menu Developer (disimpan 30 hari) mencatat paling banyak 60 permintaan per kunci per 60 detik, ditambah penolakan 429 pertama di jendela itu. Permintaan lain tetap diproses seperti biasa, hanya tidak muncul di log.

Error

{ "error": { "code": "validation_error", "message": "...", "request_id": "req_...", "details": { "fields": [{ "path": "receiver.phone", "message": "..." }] } } }

code stabil dan aman dipakai di logika integrasi; message berbahasa Indonesia dan aman ditampilkan ke pengguna. Setiap respons membawa header X-Request-Id; sertakan nilainya saat menghubungi tim OngkirHub.

Webhook

Daftarkan URL HTTPS di menu Developer dan pilih event yang ingin diterima. OngkirHub mengirim POST JSON dengan header OngkirHub-Signature: t=<unix>,v1=<hex>, di mana v1 adalah HMAC-SHA256 dengan secret endpoint (whsec_...) atas teks <t>.<body mentah>. Verifikasi tanda tangan, tolak t yang lebih dari 5 menit, lalu jawab 2xx dalam 10 detik. Pengiriman yang gagal dicoba ulang setelah 1 menit, 5 menit, 30 menit, 2 jam, 6 jam, 24 jam. Event bisa terkirim lebih dari sekali dan tidak selalu berurutan: pakai id event untuk mengabaikan duplikat dan data.shipment.updatedAt untuk urutan. Panduan lengkap: https://www.ongkirhub.com/docs/webhooks