Dokumentasi pembangunan API yuran penghantaran

apa yang boleh dilakukan

• Pengiraan Pengangkutan - Masukkan berat bungkusan (atau panjang, lebar dan isipadu), dan pulangkan yuran penghantaran ekspres laut (RMB) pakej.
• Dapatkan kadar - Tanya kadar semasa setiap kilogram, ambang surcaj dan pekali penukaran volum, yang mudah untuk anda mengira atau menyimpan cache pada bahagian hadapan.

Semua jawapan adalah dalam JSON, dalam format sampul surat bersatu: apabila berjaya, success: true dengan data; apabila gagal, success: false dengan kod error dan message.

Base URL

Pengepala pengesahan (pilih satu)

Kaedah A — Token Pembawa (disyorkan)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Kaedah B — X-API-Key

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Kunci API bermula dengan lk_live_. Sila pastikan selamat dan jangan sekali-kali meletakkan ke dalam JavaScript bahagian hadapan atau repositori Git awam; semua panggilan hendaklah dibuat dari sisi pelayan anda.

Had Kadar

Setiap kunci mempunyai had permintaan seminit, dan pengepala respons akan melaporkan baki had:

pengepala	menggambarkan
X-RateLimit-Limit	Bilangan permintaan yang dibenarkan setiap minit
X-RateLimit-Remaining	Bilangan permintaan yang tinggal pada minit ini
Retry-After	Bilangan saat untuk menunggu melebihi had masa (HTTP 429)

Untuk pengalaman bahagian hadapan yang terbaik, adalah disyorkan untuk cache hasil /rates selama beberapa minit dan mengiranya dengan formula yang sama pada pelayan anda sendiri. Hanya hubungi /quote untuk pengesahan semasa langkah kritikal membuat pesanan.

GET /api/v1/freight/rates

Menyenaraikan semua kaedah dan kadar penghantaran yang didayakan pada masa ini. Tiada parameter diperlukan.

bertanya

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

Maklum balas 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

Bayaran penghantaran ekspres laut dikira berdasarkan berat/saiz volum bungkusan. Kedua-dua GET (rentetan pertanyaan) dan POST (JSON atau borang) boleh diterima.

Permintaan parameter

parameter	taip	Diperlukan	menggambarkan
weight	number	Pilihan*	Berat sebenar dalam kilogram (kg).
length	number	Pilihan*	Panjang, unit ialah sentimeter (cm).
width	number	Pilihan*	Lebar dalam sentimeter (cm).
height	number	Pilihan*	Ketinggian, unit ialah sentimeter (cm).
method	string	Pilihan	Kaedah penghantaran pada masa ini ialah sea (sea express). Apabila diabaikan, sea diandaikan.

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}'

Maklum balas 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
  }
}

Penerangan medan respons

padang	menggambarkan
actual_weight	Berat sebenar (kg). 0 jika tidak disediakan.
volume_weight	Isipadu (isipadu) berat (kg) = panjang × lebar × tinggi ÷ 10000. 0 jika tiada saiz disediakan.
billable_weight	Berat boleh bil (kg) = maks (berat sebenar, berat isipadu).
billable_basis	Pengebilan adalah berdasarkan :actual (berdasarkan berat sebenar) atau volumetric (berdasarkan volum).
freight	Angkutan asas = berat pengebilan × kadar setiap kilogram (tidak termasuk surcaj).
surcharge	Surcaj sebenar untuk transaksi ini (0 jika tidak dicetuskan).
surcharge_applied	Sama ada untuk mencetuskan surcaj (berat pengebilan < ambang).
total_fee	Pengangkut barang akhir diterima ialah (RMB, dibundarkan kepada nombor bulat terdekat).

HTTP	error	menggambarkan
401	missing_api_key	Tiada Kunci API disediakan. Sila tambahkan pengepala Keizinan atau X-API-Key.
401	invalid_api_key	Kunci API tidak sah.
403	key_suspended / key_revoked / key_expired	Kunci telah dinyahaktifkan/dibatalkan/tamat tempoh.
403	insufficient_scope	Kunci tidak mempunyai kebenaran freight:read.
422	validation_failed	Ralat format parameter (jenis, julat).
422	missing_parameters	Tiada berat atau panjang/lebar/tinggi penuh disediakan.
422	unsupported_method	kaedah tiada dalam senarai yang tersedia.
429	rate_limit_exceeded	Melebihi had permintaan seminit, lihat Cuba Semula Selepas.

0337.tw ialah pusat membeli-belah Laravel. Adalah disyorkan untuk membungkus API yuran penghantaran ke dalam Perkhidmatan bahagian belakang dan hubungi: semasa proses pembayaran:

• Selepas mendapat jumlah berat (kg)/isipadu troli beli-belah semasa pembayaran, panggil /api/v1/freight/quote di bahagian belakang dan tetapkan total_fee yang dikembalikan sebagai kos penghantaran.
• Kunci diletakkan dalam .env (contohnya, LUCKY_FREIGHT_KEY) dan dibaca dengan config(). Jangan tulis kunci secara terus (hard-code) dalam kod program atau bahagian hadapan.
• Apabila panggilan gagal (tamat masa / 429), kadar yang dicache dalam /rates dikira secara setempat menggunakan formula yang sama sebagai sandaran untuk memastikan pembayaran tidak terganggu.
• Jumlahnya dalam RMB; jika pusat membeli-belah menyelesaikan bil dalam Dolar Taiwan Baru, sila gunakan sendiri penukaran kadar pertukaran.

Contoh Laravel (Http fasad)

// 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')] dalam config/services.php, kemudian suntik LuckyFreightService ke dalam Controller pembayaran untuk mendapatkan kos penghantaran.

sokongan teknikal: howyunqisoftware@gmail.com

Versi API: v1 (stabil). Sebarang perubahan pecah akan dikeluarkan dengan nombor versi baharu (v2), v1 akan kekal serasi.

Sejarah perubahan: 2026-06-01 — Freight API v1 adalah dalam talian (Hai Express, berharga RMB).