API Cek Ongkir Indonesia: Panduan Lengkap untuk Developer (J&T, Lion, SAP, SPX)

Developer API · Rate API v1

AgenWebsite Rate API adalah REST API cek ongkir untuk lima kurir Indonesia — J&T Express, Lion Parcel, SAP Express, SPX Express, dan J&T Cargo — yang mengembalikan tarif reguler, estimasi tiba (ETD), diskon, dan cashback nyata dalam satu request JSON. Cukup kirim POST ke https://api.agenwebsite.com/v1/rates dengan header x-api-key, asal & tujuan (kode pos atau kecamatan), dan berat paket dalam gram. API key gratis tersedia untuk setiap pengguna WooCommerce dengan kuota 150 request/hari, tanpa checkout.

Apa itu API cek ongkir?

API cek ongkir adalah antarmuka HTTP yang mengembalikan biaya dan estimasi pengiriman antar dua lokasi di Indonesia secara real-time. Alih-alih membuka situs tiap kurir satu per satu, aplikasi Anda mengirim satu request berisi asal, tujuan, dan berat paket, lalu menerima daftar tarif dari beberapa kurir sekaligus dalam format JSON yang siap ditampilkan di halaman checkout, keranjang, atau kalkulator ongkir.

AgenWebsite Rate API menormalkan data dari agregator logistik menjadi satu skema respons yang konsisten (branded response), lengkap dengan logo kurir, kode layanan, estimasi hari, asuransi, serta diskon dan cashback yang benar-benar berlaku — bukan angka simulasi. Baca ikhtisar produk di /products/developer-api/ dan referensi teknis di /documentation/.

Kurir yang didukung (v1)

Versi 1 mendukung lima kurir berikut. Gunakan courier_code pada field couriers di request Anda.

Jika Anda mengirim kode kurir di luar lima ini, API mengembalikan 422 unsupported_courier. Untuk daftar layanan terkini secara programatis, panggil GET /v1/couriers.

Quickstart: cek ongkir dalam 3 langkah

Langkah 1 — Dapatkan API key gratis

Masuk ke akun WooCommerce Anda, buka tab API di halaman My Account, verifikasi email satu kali, lalu klik Generate Key. Anda akan menerima kunci berformat awk_live_<32 hex> yang hanya ditampilkan sekali — simpan di tempat aman. Untuk pengujian gunakan kunci awk_test_... pada base URL sandbox https://api-sandbox.agenwebsite.com/v1.

Langkah 2 — Kirim request pertama Anda

Contoh paling sederhana: cek ongkir dari kode pos Bandung (40135) ke Jakarta Pusat (10110) untuk paket 1 kg (1000 gram).

curl -X POST https://api.agenwebsite.com/v1/rates \
  -H "x-api-key: awk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "shipper":     { "postal_code": "40135" },
    "destination": { "postal_code": "10110" },
    "weight": 1000
  }'

Langkah 3 — Cek ongkir dengan kurir & opsi spesifik

Batasi ke kurir tertentu, sertakan dimensi & nilai barang (untuk asuransi), dan urutkan termurah:

curl -X POST https://api.agenwebsite.com/v1/rates \
  -H "x-api-key: awk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "shipper":     { "postal_code": "40135", "subdistrict_name": "Dago" },
    "destination": { "postal_code": "10110", "subdistrict_name": "Gambir" },
    "weight": 1200,
    "dimensions": { "length": 20, "width": 15, "height": 10 },
    "item_value": 250000,
    "couriers": ["jnt","lion","spx"],
    "sort": "cheapest"
  }'

Struktur request & parameter

Endpoint: POST /v1/rates. Setiap pihak (shipper dan destination) wajib diidentifikasi dengan salah satu: postal_code (kode pos) atau subdistrict_id (ID kecamatan dari /v1/locations/search) — tidak boleh keduanya kosong, dan tidak boleh keduanya diisi bersamaan.

Struktur response JSON

Response mengembalikan array rates yang sudah dinormalkan, ditambah pintasan cheapest/fastest, summary, dan rate_limit. Tarif tidak berupa data mentah kurir — sudah dibranding dan konsisten antar kurir.

{
  "success": true,
  "currency": "IDR",
  "data": {
    "rates": [{
      "courier_code": "jnt",
      "courier_name": "J&T Express",
      "courier_logo_url": "https://...",
      "service_code": "jnt_ez",
      "service_name": "EZ Reguler",
      "service_type": "regular",
      "cost": 14000,
      "cost_formatted": "Rp 14.000",
      "etd_min_days": 2,
      "etd_max_days": 3,
      "etd_text": "2-3 hari",
      "estimated_delivery": { "from": "2026-07-03", "to": "2026-07-04" },
      "insurance": { "available": true, "fee": 0 },
      "discount": 1000,
      "discounted_cost": 13000,
      "cashback": 500,
      "cheapest": true,
      "fastest": false,
      "source": "live"
    }],
    "cheapest": { "service_code": "jnt_ez", "cost": 14000 },
    "fastest":  { "service_code": "lion_reg", "etd_max_days": 2 },
    "summary":  { "count": 2, "cost_range": { "min": 14000, "max": 16000 } }
  },
  "rate_limit": { "limit": 30000, "remaining": 29998, "reset_at": "2026-07-02T00:00:00+07:00" }
}

Field yang membedakan: discount, discounted_cost, dan cashback berisi nilai nyata yang berlaku — dapat langsung Anda tampilkan sebagai harga coret di checkout. Field source bernilai live atau cache sehingga Anda tahu apakah tarif berasal dari panggilan langsung atau cache 30 menit.

Penanganan error & kode status

API tidak pernah mengembalikan 200 kosong secara diam-diam. Setiap kegagalan memakai amplop error yang konsisten:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Field 'weight' wajib diisi.",
    "field": "weight",
    "request_id": "req_..."
  }
}

Setiap response menyertakan header X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Response 429 menambahkan Retry-After.

Kuota & rate limit

Kuota dihitung per request (bukan per baris kurir) dan berlaku per pengguna — dibagi bersama untuk semua key milik akun tersebut. Kuota direset harian pukul 00:00 WIB (Asia/Jakarta).

Pantau sisa kuota kapan saja lewat GET /v1/usage:

curl https://api.agenwebsite.com/v1/usage \
  -H "x-api-key: awk_live_xxxxxxxx"

FAQ

Apakah API cek ongkir AgenWebsite gratis?

Ya. Setiap pengguna WooCommerce otomatis mendapat tier Free dengan 150 request/hari tanpa perlu checkout. Anda cukup verifikasi email satu kali lalu generate API key.

Kurir apa saja yang didukung?

Versi 1 mendukung J&T Express (jnt), Lion Parcel (lion), SAP Express (sap), SPX Express (spx), dan J&T Cargo (jtc) untuk pengiriman reguler.

Apakah harus pakai kode pos atau boleh kecamatan?

Boleh keduanya. Kirim postal_code untuk hasil paling akurat, atau subdistrict_id dari endpoint /v1/locations/search. Yang penting, tiap pihak diidentifikasi dengan salah satu — tidak boleh kosong dan tidak boleh keduanya sekaligus.

Bagaimana cara menangani rate limit?

Cek header X-RateLimit-Remaining pada setiap response. Jika menerima 429, hormati header Retry-After sebelum mencoba lagi, dan pertimbangkan caching di sisi Anda untuk pasangan asal-tujuan yang sama.

Apakah diskon dan cashback yang ditampilkan nyata?

Ya. Field discount, discounted_cost, dan cashback menampilkan nilai yang benar-benar berlaku, bahkan di tier Free — sehingga bisa langsung dipakai di checkout.