Developer API · Tutorial

AgenWebsite Rate API v1 adalah API cek ongkir reguler dan non-COD. Untuk asuransi, kirim item_value (nilai barang) di request dan baca objek insurance pada setiap tarif di response — setiap item rates menyertakan insurance.available dan insurance.fee, sehingga Anda tahu apakah asuransi tersedia dan berapa biayanya dalam satu request. COD belum tersedia melalui API pada v1 dan masih dalam roadmap.

Cakupan v1: reguler & non-COD

AgenWebsite Rate API v1 mengembalikan tarif untuk pengiriman reguler (non-COD). Request tidak memerlukan — dan tidak memproses — field cod maupun package_type. Yang tersedia di v1 untuk kebutuhan proteksi pengiriman adalah asuransi, yang dihitung dari item_value yang Anda kirim. Cash on Delivery (COD) sedang kami siapkan dan akan diumumkan lewat dokumentasi saat tersedia.

Asuransi: item_value & objek insurance

Asuransi dihitung dari item_value (nilai barang dalam IDR) yang Anda kirim di request. Berdasarkan nilai ini, tiap tarif di response menyertakan objek insurance dengan available (apakah asuransi tersedia) dan fee (biaya asuransi dalam IDR). Untuk barang bernilai tinggi, biaya asuransi umumnya proporsional terhadap item_value.

Field Arah Keterangan
item_value Request Nilai barang; dasar perhitungan asuransi
insurance.available Response (per tarif) Apakah asuransi tersedia untuk layanan ini
insurance.fee Response (per tarif) Biaya asuransi dalam IDR (0 bila gratis/tidak dikenakan)

Kirim item_value yang akurat agar biaya asuransi dan (jika relevan) proteksi klaim sesuai. Menghilangkan item_value berarti asuransi mungkin tidak dihitung.

Request dengan item_value

Contoh: paket 1,2 kg (1200 gram) senilai Rp 250.000, dengan dimensi untuk berat volumetrik:

cURL · POST /rates
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": 1200,
    "dimensions": { "length": 20, "width": 15, "height": 10 },
    "item_value": 250000,
    "couriers": ["jnt","lion","sap","spx","jtc"]
  }'
Tidak ada field cod atau package_type di v1 — kirim item_value saja untuk mengaktifkan perhitungan asuransi. Berat (gram), dimensi, dan filter kurir bersifat seperti biasa.

Membaca objek insurance

Response menyertakan detail asuransi per tarif:

JSON · Response 200
{
  "success": true,
  "currency": "IDR",
  "data": {
    "rates": [
      {
        "courier_code": "jnt", "service_code": "jnt_ez", "service_name": "EZ Reguler",
        "cost": 14000, "cost_formatted": "Rp 14.000",
        "etd_text": "2-3 hari",
        "insurance": { "available": true, "fee": 1250 },
        "discount": 1000, "discounted_cost": 13000, "cashback": 500,
        "source": "live"
      },
      {
        "courier_code": "spx", "service_code": "spx_std", "service_name": "Standard",
        "cost": 15000, "cost_formatted": "Rp 15.000",
        "etd_text": "2-4 hari",
        "insurance": { "available": true, "fee": 1250 },
        "source": "live"
      }
    ]
  }
}

Di contoh ini, kedua layanan menawarkan asuransi dengan fee Rp 1.250. Baca insurance.available per tarif sebelum menambahkan biaya asuransi ke ongkir yang Anda tampilkan.

Terapkan di checkout

Tambahkan biaya asuransi ke ongkir jika toko Anda mewajibkannya:

PHP · add_rate() + asuransi
<?php
$wajib_asuransi = true; // kebijakan toko

foreach ( $body['data']['rates'] as $rate ) {
    $cost = $rate['discounted_cost'];
    if ( $wajib_asuransi && ! empty( $rate['insurance']['available'] ) ) {
        $cost += (int) $rate['insurance']['fee'];
    }

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

Untuk transparansi, tampilkan rincian “Ongkir + Asuransi Rp x” agar pelanggan paham komposisi biaya.

COD: status & roadmap

Cash on Delivery (COD) belum tersedia melalui AgenWebsite Rate API v1. API versi ini fokus pada tarif pengiriman reguler (non-COD), sehingga request tidak menerima field cod maupun package_type, dan response tidak mengembalikan flag cod_available. Dukungan COD berada di roadmap kami; ikuti pengumuman di dokumentasi untuk mengetahui kapan field dan flag COD mulai tersedia.

Tips & catatan penting

Aspek Rekomendasi
Cek per item Selalu baca insurance.available per tarif — dukungan asuransi bisa berbeda antar kurir dan rute.
Nilai barang akurat Kirim item_value sesuai nilai riil agar asuransi dihitung benar; tanpa itu asuransi bisa tidak muncul.
Non-COD di v1 Rate API v1 hanya menghitung tarif reguler/non-COD; jangan kirim field cod atau package_type.
Kuota Menyertakan item_value tidak menambah biaya kuota — tetap 1 per request.

FAQ

Bagaimana biaya asuransi dihitung?

Asuransi dihitung dari item_value yang Anda kirim. Tiap tarif di response menyertakan insurance.available dan insurance.fee dalam IDR. Nilai fee 0 berarti tidak ada biaya asuransi.

Apakah wajib mengirim item_value?

Tidak wajib, tetapi disarankan. Tanpa item_value, biaya asuransi mungkin tidak dihitung. Kirim nilai barang yang akurat agar asuransi dan proteksi sesuai.

Apakah semua kurir menyediakan asuransi?

Tidak selalu. Ketersediaan asuransi bisa berbeda antar kurir dan rute, jadi selalu cek flag insurance.available pada masing-masing tarif sebelum menambahkan biaya asuransi.

Apakah API mendukung COD?

Belum. AgenWebsite Rate API v1 khusus pengiriman reguler dan non-COD, sehingga tidak ada field cod atau package_type di request dan tidak ada flag cod_available di response. Dukungan COD ada di roadmap dan akan diumumkan lewat dokumentasi.

Apakah menyertakan item_value menambah biaya kuota?

Tidak. Kuota tetap dihitung satu per request, apa pun field yang Anda sertakan termasuk item_value dan dimensions.

Dukung asuransi pengiriman di toko Anda. Dapatkan API key gratis dan cek field selengkapnya di dokumentasi.