Dokumentasi pengembangan API biaya pengiriman

apa yang bisa dilakukan

• Perhitungan Pengangkutan - Masukkan berat paket (atau panjang, lebar dan volume), dan kembalikan biaya pengiriman ekspres laut (RMB) paket.
• Dapatkan tarif - Kueri tarif per kilogram saat ini, ambang batas biaya tambahan, dan koefisien konversi volume, yang memudahkan Anda menghitung atau menyimpan cache di ujung depan.

Semua tanggapan dalam JSON, dalam format amplop terpadu: bila berhasil, success: true dengan data; ketika gagal, success: false dengan kode error dan message.

Base URL

Header otentikasi (pilih salah satu)

Metode A — Token Pembawa (disarankan)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Metode B — Kunci X-API

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Kunci API dimulai dengan lk_live_. Harap simpan dengan aman dan jangan pernah memasukkan ke dalam JavaScript front-end atau repositori Git publik; semua panggilan harus dilakukan dari sisi server Anda.

Batas Nilai

Setiap kunci memiliki batas permintaan per menit, dan header respons akan melaporkan batas yang tersisa:

tajuk	menjelaskan
X-RateLimit-Limit	Jumlah permintaan yang diizinkan per menit
X-RateLimit-Remaining	Jumlah permintaan yang tersisa saat ini
Retry-After	Jumlah detik menunggu hingga batas waktu terlampaui (HTTP 429)

Untuk pengalaman front-end terbaik, disarankan untuk menyimpan hasil /rates selama beberapa menit dan menghitungnya dengan rumus yang sama di server Anda sendiri. Hanya hubungi /quote untuk verifikasi selama langkah penting dalam melakukan pemesanan.

GET /api/v1/freight/rates

Mencantumkan semua metode dan tarif pengiriman yang saat ini diaktifkan. Tidak diperlukan parameter.

bertanya

curl https://0523.tw/api/v1/freight/rates \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Tanggapan 200

{
  "success": true,
  "currency": "CNY",
  "data": [
    {
      "method": "sea",
      "name_zh": "海快",
      "name_en": "Sea Express",
      "rate_per_kg": 10,
      "surcharge": 20,
      "min_threshold": 15,
      "volume_divisor": 10000,
      "currency": "CNY"
    }
  ]
}

GETPOST /api/v1/freight/quote

Biaya pengiriman sea express dihitung berdasarkan berat/ukuran volume paket. GET (string kueri) dan POST (JSON atau formulir) keduanya dapat diterima.

Parameter permintaan

parameter	Jenis	Diperlukan	menjelaskan
weight	number	Opsional*	Berat sebenarnya dalam kilogram (kg).
length	number	Opsional*	Panjang, satuannya sentimeter (cm).
width	number	Opsional*	Lebar dalam sentimeter (cm).
height	number	Opsional*	Tinggi, satuannya sentimeter (cm).
method	string	Opsional	Metode pengiriman saat ini adalah sea (sea express). Jika dihilangkan, sea diasumsikan.

Contoh permintaan (GET)

curl "https://0523.tw/api/v1/freight/quote?weight=8&method=sea" \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Contoh permintaan (POST JSON)

curl -X POST https://0523.tw/api/v1/freight/quote \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"weight": 5, "length": 40, "width": 30, "height": 30}'

Tanggapan 200

{
  "success": true,
  "data": {
    "method": "sea",
    "method_name_zh": "海快",
    "method_name_en": "Sea Express",
    "currency": "CNY",
    "currency_symbol": "¥",
    "actual_weight": 5,
    "volume_weight": 3.6,
    "volume_divisor": 10000,
    "billable_weight": 5,
    "billable_basis": "actual",
    "rate_per_kg": 10,
    "freight": 50,
    "surcharge": 20,
    "surcharge_applied": true,
    "min_threshold": 15,
    "total_fee": 70
  }
}

Deskripsi bidang respons

bidang	menjelaskan
actual_weight	Berat sebenarnya (kg). 0 jika tidak disediakan.
volume_weight	Volume (volume) berat (kg) = panjang × lebar × tinggi 10000,0 jika tidak disediakan ukuran.
billable_weight	Berat yang dapat ditagih (kg) = maks (berat aktual, berat volumetrik).
billable_basis	Penagihan didasarkan pada :actual (berdasarkan berat sebenarnya) atau volumetrik (berdasarkan volume).
freight	Pengangkutan dasar = berat tagihan × tarif per kilogram (tidak termasuk biaya tambahan).
surcharge	Biaya tambahan sebenarnya untuk transaksi ini (0 jika tidak dipicu).
surcharge_applied	Apakah akan memicu biaya tambahan (bobot penagihan < ambang batas).
total_fee	Piutang pengangkutan akhir adalah (RMB, dibulatkan ke bilangan bulat terdekat).

HTTP	error	menjelaskan
401	missing_api_key	Tidak ada Kunci API yang disediakan. Silakan tambahkan Otorisasi atau header X-API-Key.
401	invalid_api_key	Kunci API tidak valid.
403	key_suspended / key_revoked / key_expired	Kunci telah dinonaktifkan/dicabut/kedaluwarsa.
403	insufficient_scope	Kuncinya tidak memiliki izin freight:read.
422	validation_failed	Kesalahan format parameter (jenis, rentang).
422	missing_parameters	Tidak ada berat atau panjang/lebar/tinggi penuh yang disediakan.
422	unsupported_method	metode tidak ada dalam daftar yang tersedia.
429	rate_limit_exceeded	Melebihi batas permintaan per menit, lihat Coba Lagi Setelahnya.

0337.tw adalah mal Laravel. Disarankan untuk mengemas API biaya pengiriman ke dalam Layanan backend dan menghubungi: selama proses checkout:

• Setelah mendapatkan total berat (kg)/volume keranjang belanja saat checkout, hubungi /api/v1/freight/quote di backend , dan tetapkan total_fee yang dikembalikan sebagai biaya pengiriman.
• Kuncinya ditempatkan di .env (misalnya, LUCKY_FREIGHT_KEY) dan dibaca dengan config(). Kunci tidak boleh ditulis langsung (hard-code) di kode program atau front-end.
• Ketika panggilan gagal (batas waktu / 429), tarif yang di-cache di /rates dihitung secara lokal menggunakan rumus yang sama dengan cadangan untuk memastikan pembayaran tidak terganggu.
• Jumlahnya dalam RMB; jika mal melunasi tagihan dalam Dolar Taiwan Baru, harap terapkan sendiri konversi nilai tukarnya.

Contoh Laravel (fasad Http)

// app/Services/LuckyFreightService.php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Cache;

class LuckyFreightService
{
    public function quote(float $weight): int
    {
        $res = Http::withToken(config('services.lucky.freight_key'))  // 讀 .env
            ->acceptJson()
            ->timeout(8)
            ->get('https://0523.tw/api/v1/freight/quote', [
                'weight' => $weight,
                'method' => 'sea',
            ]);

        if ($res->successful()) {
            return (int) $res->json('data.total_fee');  // 人民幣
        }

        // 後備:用快取費率本地計算,結帳不中斷
        return $this->fallbackQuote($weight);
    }
}

Tambahkan 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] di config/services.php, lalu masukkan LuckyFreightService ke dalam Kontroler checkout untuk mendapatkan barang tersebut.

dukungan teknis: howyunqisoftware@gmail.com

Versi API: v1 (stabil). Perubahan apa pun yang dapat menyebabkan gangguan akan dirilis dengan nomor versi baru (v2), v1 akan tetap kompatibel.

Ubah riwayat: 01-06-2026 — Freight API v1 sedang online (Hai Express, harga dalam RMB).