Tampilkan Tarif Termurah & Tercepat Otomatis di Checkout via API

Developer API · Tutorial

AgenWebsite Rate API mengembalikan pintasan data.cheapest dan data.fastest di setiap response, plus field sort (cheapest/fastest) untuk mengurutkan array tarif — jadi Anda bisa langsung menyorot opsi termurah atau tercepat tanpa logika tambahan. Setiap item rates juga menandai "cheapest": true / "fastest": true sehingga UI checkout tinggal membaca flag tersebut.

Konsep: sort, cheapest, fastest

API menyediakan tiga mekanisme yang saling melengkapi agar Anda tidak perlu menghitung sendiri opsi terbaik:

Termurah dihitung dari discounted_cost bila ada diskon, sehingga badge “Termurah” mencerminkan harga yang benar-benar dibayar pelanggan — bukan harga sebelum diskon. Rincian field ada di dokumentasi.

Request dengan sort

Minta beberapa kurir sekaligus dan urutkan termurah lebih dulu:

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,
    "couriers": ["jnt","lion","sap","spx","jtc"],
    "sort": "cheapest"
  }'

Ganti "sort": "cheapest" menjadi "fastest" untuk mengurutkan berdasarkan estimasi tiba tercepat.

Membaca cheapest & fastest dari response

Selain array rates yang sudah terurut, response memberi pintasan langsung dan flag per item:

{
  "success": true,
  "currency": "IDR",
  "data": {
    "rates": [
      {
        "courier_code": "jnt", "service_code": "jnt_ez", "service_name": "EZ Reguler",
        "cost": 14000, "discounted_cost": 13000, "cost_formatted": "Rp 14.000",
        "etd_min_days": 2, "etd_max_days": 3, "etd_text": "2-3 hari",
        "cheapest": true, "fastest": false, "source": "live"
      },
      {
        "courier_code": "lion", "service_code": "lion_reg", "service_name": "Reguler",
        "cost": 16000, "discounted_cost": 16000, "cost_formatted": "Rp 16.000",
        "etd_min_days": 1, "etd_max_days": 2, "etd_text": "1-2 hari",
        "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 } }
  }
}

Untuk UI, Anda cukup membaca data.cheapest.service_code dan data.fastest.service_code untuk menentukan opsi mana yang diberi badge — tanpa perlu iterasi dan membandingkan sendiri.

Contoh: sorot otomatis di front-end

Node.js/JavaScript murni — panggil dari server, lalu kirim hasil ringkas ke browser (jangan taruh key di klien):

async function ambilOngkir(originPc, destPc, weight) {
  const res = await fetch("https://api.agenwebsite.com/v1/rates", {
    method: "POST",
    headers: {
      "x-api-key": process.env.AGENWEBSITE_RATE_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      shipper: { postal_code: originPc },
      destination: { postal_code: destPc },
      weight,
      couriers: ["jnt", "lion", "sap", "spx", "jtc"],
      sort: "cheapest",
    }),
  });

  const body = await res.json();
  if (!res.ok || !body.success) {
    throw new Error(body?.error?.message ?? "Gagal mengambil tarif.");
  }

  const { rates, cheapest, fastest } = body.data;

  // Tandai tiap opsi dengan badge berdasarkan pintasan response.
  return rates.map((r) => ({
    label: r.service_name,
    courier: r.courier_name,
    harga: r.cost_formatted,
    estimasi: r.etd_text,
    badge:
      r.service_code === cheapest.service_code
        ? "Termurah"
        : r.service_code === fastest.service_code
        ? "Tercepat"
        : null,
  }));
}

Di UI, render badge sebagai label kecil berwarna aksen (mis. oranye #ff6600 untuk “Termurah”, biru #015C80 untuk “Tercepat”). Satu layanan bisa saja sekaligus termurah dan tercepat.

Terapkan di checkout WooCommerce

Di dalam calculate_shipping() pada custom WC_Shipping_Method, daftarkan tiap tarif dengan $this->add_rate() dan sisipkan badge pada label. Pratinjau logika penyorotan:

<?php
$rates    = $body['data']['rates'];
$cheapest = $body['data']['cheapest']['service_code'];
$fastest  = $body['data']['fastest']['service_code'];

foreach ( $rates as $rate ) {
    $badge = '';
    if ( $rate['service_code'] === $cheapest ) {
        $badge = ' — ' . esc_html__( 'Termurah', 'agenwebsite-developer-api' );
    } elseif ( $rate['service_code'] === $fastest ) {
        $badge = ' — ' . esc_html__( 'Tercepat', 'agenwebsite-developer-api' );
    }

    $this->add_rate( array(
        'id'    => 'agenwebsite:' . $rate['service_code'],
        'label' => $rate['courier_name'] . ' ' . $rate['service_name'] . $badge,
        'cost'  => $rate['discounted_cost'],
        'meta_data' => array( 'etd' => $rate['etd_text'] ),
    ) );
}

Untuk memilih opsi termurah sebagai default terpilih di checkout, urutkan dengan sort: "cheapest" lalu jadikan elemen pertama sebagai pilihan terpilih. WooCommerce menampilkan opsi sesuai urutan pendaftaran add_rate().

Tips UX & kuota

FAQ

Apakah saya harus menghitung sendiri opsi termurah?

Tidak. API mengembalikan pintasan data.cheapest dan data.fastest, plus flag cheapest/fastest per item. Anda cukup membacanya untuk memberi badge di UI.

Apakah termurah dihitung dari harga sebelum atau sesudah diskon?

Sesudah diskon. Perbandingan termurah menggunakan discounted_cost bila ada diskon, sehingga badge mencerminkan harga yang benar-benar dibayar pelanggan.

Bisakah satu layanan menjadi termurah sekaligus tercepat?

Bisa. Jika layanan yang sama memiliki biaya terendah dan ETD tercepat, kedua flag cheapest dan fastest bernilai true untuk item tersebut.

Apa efek field sort ke response?

Field sort hanya mengubah urutan array data.rates: cheapest mengurutkan berdasarkan biaya naik, fastest berdasarkan ETD naik. Pintasan data.cheapest dan data.fastest tetap tersedia apa pun nilai sort.

Apakah minta 5 kurir untuk membandingkan boros kuota?

Tidak. Kuota dihitung satu per request berapa pun jumlah kurir. Meminta kelima kurir sekaligus untuk menemukan termurah dan tercepat tetap terhitung 1 request.