Mulai cepat API

Panduan ini membawamu dari kunci API sampai resi uji yang bisa dilacak, memakai kunci test sehingga tidak ada kurir yang datang dan saldo sungguhan tidak tersentuh. Contohnya memakai curl. Setiap langkah butuh beberapa menit. Ringkasan alurnya juga ada di video Cara integrasi Developer API.

Yang kamu butuhkan:

• Akun OngkirHub App dengan peran pemilik atau admin.
• Terminal dengan curl, atau klien HTTP lain.

Base URL untuk semua permintaan adalah https://api.ongkirhub.com/v1.

1. Buat kunci test

1. Buka menu Developer di OngkirHub App, tab Kunci API.
2. Tekan Buat kunci, isi nama misalnya “Uji coba”, pilih mode Test, biarkan semua akses tercentang, lalu tekan Buat kunci.
3. Salin kunci yang tampil. Kunci lengkap hanya ditampilkan sekali.

Simpan kunci di variabel lingkungan supaya contoh di bawah bisa langsung dipakai:

export ONGKIRHUB_API_KEY="ohk_test_xxx"

2. Cek koneksi

Panggil daftar kurir untuk memastikan kuncimu bekerja.

curl https://api.ongkirhub.com/v1/couriers \
  -H "Authorization: Bearer $ONGKIRHUB_API_KEY"

Respons 200 berisi kurir, layanan yang bisa dipesan, dan dukungan pelacakan. Kalau mendapat 401 unauthenticated, periksa lagi kuncimu.

3. Cari wilayah asal dan tujuan

Lokasi pengirim dan penerima harus cocok dengan data kurir. Cari dengan nama kelurahan, kecamatan, kota, atau kode pos, minimal 3 karakter.

curl "https://api.ongkirhub.com/v1/locations?q=lebak%20gede" \
  -H "Authorization: Bearer $ONGKIRHUB_API_KEY"

{
  "data": [
    {
      "province": "Jawa Barat",
      "city": "Bandung",
      "district": "Coblong",
      "subdistrict": "Lebak Gede",
      "zipcode": "40132"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Pakai satu objek dari data apa adanya sebagai location pengirim atau penerima. Lakukan hal yang sama untuk alamat pengirimmu.

4. Cek tarif

Simpan data paket di file paket.json. Isi ini juga dipakai lagi persis sama saat membuat pengiriman.

{
  "sender": {
    "name": "Toko Contoh Jaya",
    "phone": "081200000001",
    "email": "gudang@contoh.test",
    "address": "Jl. Contoh Raya No. 1, RT 01/RW 02, Setiabudi",
    "location": {
      "province": "DKI Jakarta",
      "city": "Jakarta Selatan",
      "district": "Setia Budi",
      "subdistrict": "Setiabudi",
      "zipcode": "12910"
    }
  },
  "receiver": {
    "name": "Dimas Pratama",
    "phone": "081300000102",
    "address": "Jl. Penerima No. 2, dekat masjid, Lebak Gede",
    "location": {
      "province": "Jawa Barat",
      "city": "Bandung",
      "district": "Coblong",
      "subdistrict": "Lebak Gede",
      "zipcode": "40132"
    }
  },
  "items": [
    {
      "name": "Kaos katun",
      "sku": "KAOS-HITAM-L",
      "qty": 2,
      "weightKg": 0.5,
      "value": 85000,
      "dimensions": { "lengthCm": 25, "widthCm": 20, "heightCm": 5 }
    }
  ],
  "pickupType": "DROP",
  "insured": false
}

curl -X POST https://api.ongkirhub.com/v1/rates \
  -H "Authorization: Bearer $ONGKIRHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d @paket.json

Respons berisi id penawaran yang berlaku 30 menit dan daftar layanan, termurah dulu. Contoh ini dipangkas menjadi dua layanan. Harga di mode test berasal dari simulator, bukan tarif kurir.

{
  "id": "6acc296112883ee399513186",
  "livemode": false,
  "pickupType": "DROP",
  "insured": false,
  "expiresAt": "2026-10-11T03:30:00.000Z",
  "rates": [
    {
      "rateCode": "JAGOPACK",
      "courierCode": "lion",
      "courierName": "Lion Parcel",
      "serviceName": "JAGOPACK",
      "etd": { "min": 2, "max": 5, "unit": "DAY" },
      "price": { "courierPrice": 9500, "insurancePrice": 0, "serviceFee": 0, "total": 9500 },
      "chargeableWeightKg": 1,
      "pickupToday": false,
      "pickupSlots": null
    },
    {
      "rateCode": "REG23",
      "courierCode": "jne",
      "courierName": "JNE",
      "serviceName": "Regular",
      "etd": { "min": 1, "max": 2, "unit": "DAY" },
      "price": { "courierPrice": 12000, "insurancePrice": 0, "serviceFee": 0, "total": 12000 },
      "chargeableWeightKg": 1,
      "pickupToday": false,
      "pickupSlots": null
    }
  ]
}

Catat id penawaran dan rateCode layanan yang kamu pilih.

5. Buat pengiriman

Kirim isi paket.json yang sama persis, ditambah quoteId, rateCode, dan referensimu sendiri di externalRef. Cara cepat membuat file pengiriman.json dengan jq:

jq '. + {"quoteId": "6acc296112883ee399513186", "rateCode": "REG23", "externalRef": "INV-2026-10-0412"}' paket.json > pengiriman.json

Tanpa jq, salin paket.json lalu tambahkan ketiga field itu di tingkat paling atas. Kirim dengan Idempotency-Key agar permintaan yang diulang tidak membuat pengiriman ganda:

curl -X POST https://api.ongkirhub.com/v1/shipments \
  -H "Authorization: Bearer $ONGKIRHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-INV-2026-10-0412" \
  -d @pengiriman.json

Respons 201 berisi pengiriman dengan status submitting. Total harga sudah ditahan dari saldo uji.

{
  "id": "OH0HZ3K7Q2M4XB",
  "livemode": false,
  "status": "submitting",
  "statusLabel": "Sedang diproses",
  "awb": null,
  "pricing": { "courierPrice": 12000, "insurancePrice": 0, "serviceFee": 0, "total": 12000 },
  "externalRef": "INV-2026-10-0412",
  "source": "api"
}

Contoh di atas dipangkas. Respons lengkap memuat data pengirim, penerima, barang, pelacakan, dan riwayat status.

Untuk pickup, kirim "pickupType": "PICKUP" saat cek tarif, lalu tambahkan pickupTime berisi startAt salah satu pickupSlots dari layanan yang dipilih.

6. Pantau status

Pesanan diteruskan ke kurir beberapa detik setelah respons. Ambil detailnya dengan ID pengiriman:

curl https://api.ongkirhub.com/v1/shipments/OH0HZ3K7Q2M4XB \
  -H "Authorization: Bearer $ONGKIRHUB_API_KEY"

Status berubah menjadi booked beberapa detik setelah respons, lalu awb_ready saat resi terbit. Di mode test, resi simulasi terbit sekitar 20 detik sampai beberapa menit setelah pesanan diterima. Kalau kurir menolak pesanan, status menjadi failed, saldo yang ditahan dikembalikan, dan alasannya ada di field error.

Daripada memanggil endpoint ini berulang kali, daftarkan webhook untuk menerima event shipment.awb_ready dan perubahan status berikutnya.

7. Lacak resi

Setelah awb terisi, lacak dengan nomor resinya:

curl https://api.ongkirhub.com/v1/tracking/NOMOR_RESI \
  -H "Authorization: Bearer $ONGKIRHUB_API_KEY"

Respons berisi tahap perjalanan (stage), status menurut kurir, dan riwayat pelacakan terbaru dulu. Resi yang dibuat lewat OngkirHub dilacak tanpa parameter tambahan. Di mode test, riwayat pelacakan bergerak selama sekitar 1 jam sampai paket berstatus delivered, dan diperbarui berkala.

Untuk mencoba skenario lain, misalnya kurir menolak pesanan atau paket diretur, tulis penanda seperti [mock:courier_rejected] di nama penerima. Daftarnya ada di Mode test.

Langkah berikutnya

• Pelajari Mode test untuk memahami saldo uji dan pemisahan data test dan live.
• Tangani error umum seperti 402 wallet_insufficient_funds dan 409 quote_expired dengan bantuan halaman Error.
• Pasang webhook dan verifikasi tanda tangannya.
• Saat siap, buat kunci live dan ganti kunci di servermu. Endpoint dan kodenya tidak perlu diubah.