POST /v1/rates — Cek Ongkir

Endpoint Utama

Ringkasan

POST /v1/rates adalah endpoint inti AgenWebsite Rate API. Kirim titik asal (shipper), titik tujuan (destination), dan berat paket — API mengembalikan daftar tarif kurir yang sudah ternormalisasi dan ter-branding: harga, estimasi waktu tiba (ETD), diskon, cashback, serta penanda termurah dan tercepat secara otomatis.

Base URL: https://api.agenwebsite.com/v1 · Autentikasi lewat header x-api-key · Content-Type application/json.

Request Body

Untuk setiap pihak (shipper & destination) kirim salah satu: postal_code (kode pos) atau subdistrict_id (dari /v1/locations/search). Jangan kirim keduanya sekaligus, jangan pula mengosongkan keduanya.

*Untuk tiap pihak kirim tepat satu dari postal_code atau subdistrict_id.

Contoh Request

Request · cURL (lengkap)

curl -X POST https://api.agenwebsite.com/v1/rates \
  -H "x-api-key: awk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -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"],
    "sort": "cheapest"
  }' 

Payload minimum hanya butuh asal, tujuan, dan berat:

Request · cURL (minimum)

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

Struktur Response

Response mengembalikan tarif ter-branding — bukan data mentah kurir. Perhatikan data.rates[] (daftar layanan), data.cheapest / data.fastest (helper), dan rate_limit (kuota harian tersisa).

Response · 200 OK

{
  "success": true,
  "currency": "IDR",
  "data": {
    "rates": [
      {
        "courier_code": "jnt",
        "courier_name": "J&T Express",
        "courier_logo_url": "https://cdn.agenwebsite.com/couriers/jnt.png",
        "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-04", "to": "2026-07-05" },
        "insurance": { "available": true, "fee": 0 },
        "discount": 1000,
        "discounted_cost": 13000,
        "cashback": 500,
        "cheapest": true,
        "fastest": false,
        "source": "live"
      },
      {
        "courier_code": "lion",
        "courier_name": "Lion Parcel",
        "courier_logo_url": "https://cdn.agenwebsite.com/couriers/lion.png",
        "service_code": "lion_reg",
        "service_name": "Regpack",
        "service_type": "regular",
        "cost": 16000,
        "cost_formatted": "Rp 16.000",
        "etd_min_days": 1,
        "etd_max_days": 2,
        "etd_text": "1-2 hari",
        "estimated_delivery": { "from": "2026-07-03", "to": "2026-07-04" },
        "insurance": { "available": true, "fee": 2500 },
        "discount": 0,
        "discounted_cost": 16000,
        "cashback": 0,
        "cheapest": false,
        "fastest": true,
        "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-03T00:00:00+07:00"
  }
}

Penjelasan Field Response

Helper Termurah & Tercepat

Tidak perlu menghitung sendiri. API sudah menandai layanan termurah dan tercepat di dua tempat, jadi Anda bisa langsung memakainya di UI checkout:

• Per-baris: flag cheapest dan fastest pada setiap objek rates[].
• Pintasan: objek data.cheapest dan data.fastest di level atas data.

Contoh mengambil rekomendasi termurah dengan JavaScript:

Helper · JavaScript

const res = await fetch("https://api.agenwebsite.com/v1/rates", {
  method: "POST",
  headers: {
    "x-api-key": "awk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    shipper:     { postal_code: "40135" },
    destination: { postal_code: "10110" },
    weight: 1000,
    sort: "cheapest",
  }),
});
const json = await res.json();

// Opsi 1 — pakai pintasan
const termurahCode = json.data.cheapest.service_code;   // "jnt_ez"

// Opsi 2 — cari lewat flag di tiap baris
const termurah = json.data.rates.find(r => r.cheapest);
const tercepat = json.data.rates.find(r => r.fastest);

console.log(termurah.courier_name, termurah.discounted_cost); // "J&T Express" 13000

Catatan Penting