API untuk ongkir, resi, dan pelacakan
REST API v1 dan webhook bertanda tangan. Uji dengan kunci test, lalu pindah ke kunci live saat siap.
Satu integrasi untuk banyak kurir
Base URL https://api.ongkirhub.com/v1, autentikasi dengan
header Authorization Bearer, respons JSON, dan spesifikasi OpenAPI 3.1.
- Kunci test dan live, dikelola di menu Developer
- Header Idempotency-Key untuk permintaan POST
- Batas permintaan per kunci dan log permintaan di aplikasi
- Error dalam format JSON yang sama, lengkap dengan request id
-
/v1/locationsCari lokasi asal dan tujuan -
/v1/ratesCek tarif untuk rute dan berat -
/v1/shipmentsBuat pengiriman dan resi -
/v1/shipmentsDaftar pengiriman -
/v1/shipments/{id}Detail pengiriman -
/v1/shipments/{id}/cancelAjukan pembatalan -
/v1/tracking/{awb}Lacak resi -
/v1/walletSaldo -
/v1/wallet/transactionsMutasi saldo -
/v1/couriersDaftar kurir dan layanan
Mulai dalam lima langkah
Tonton video integrasinya-
Daftar akun OngkirHub, lalu buka menu Developer di OngkirHub App.
-
Buat kunci test untuk uji coba tanpa pengiriman sungguhan.
-
Panggil cek tarif, lalu buat pengiriman dengan header Idempotency-Key.
-
Daftarkan URL webhook dan verifikasi header OngkirHub-Signature di servermu.
-
Ganti ke kunci live saat integrasi siap dipakai di produksi.
Permintaan pertama
curl "https://api.ongkirhub.com/v1/couriers" \
-H "Authorization: Bearer ohk_test_xxx"Kunci test dan kunci live
Untuk uji coba integrasi tanpa membuat pengiriman sungguhan.
Untuk produksi. Pengiriman sungguhan dibuat dan dibayar dari saldo.
Webhook untuk setiap perubahan
Setiap event ditandatangani dengan header OngkirHub-Signature. Bila servermu tidak membalas sukses, pengiriman dicoba ulang otomatis setelah 1 menit, 5 menit, 30 menit, 2 jam, 6 jam, dan 24 jam.
-
shipment.bookedPengiriman berhasil dipesan ke kurir.
-
shipment.awb_readyNomor resi sudah terbit dan label bisa dicetak.
-
shipment.status_updatedStatus pelacakan paket berubah.
-
shipment.deliveredPaket sudah diterima.
-
shipment.failedPemesanan ditolak kurir; dana yang ditahan kembali ke saldo.
-
shipment.cancelledPembatalan sudah dikonfirmasi.
-
topup.paidTop-up saldo sudah dibayar.
Verifikasi tanda tangan (Node.js)
Format header: t=<unix>,v1=<hex>. Nilai v1 adalah HMAC SHA-256 dari secret webhook atas teks
t + "." + body.
import { createHmac, timingSafeEqual } from "node:crypto";
// header: nilai OngkirHub-Signature, contoh "t=1759720000,v1=5f2c..."
export function verifySignature(header: string, rawBody: string, secret: string): boolean {
const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest();
const received = Buffer.from(parts.v1 ?? "", "hex");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && received.length === expected.length && timingSafeEqual(received, expected);
}Baca referensi lengkapnya
Endpoint, skema permintaan dan respons, contoh, serta panduan webhook ada di dokumentasi.