Tài liệu phát triển API phí vận chuyển

những gì có thể được thực hiện

• Tính toán vận chuyển hàng hóa - Nhập trọng lượng của gói hàng (hoặc chiều dài, chiều rộng và thể tích) và trả lại phí vận chuyển đường biển (RMB) của gói hàng.
• Nhận tỷ lệ - Truy vấn tỷ lệ hiện tại trên mỗi kg, ngưỡng phụ phí và hệ số chuyển đổi khối lượng, thuận tiện cho bạn tính toán hoặc lưu vào bộ nhớ đệm ở giao diện người dùng.

Tất cả các phản hồi đều ở dạng JSON, ở định dạng phong bì thống nhất: khi thành công, success: true với data; khi không thành công, thành công: false với mã error và message.

Base URL

Tiêu đề xác thực (chọn một)

Phương pháp A - Mã thông báo mang (được khuyến nghị)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Phương pháp B - Khóa X-API

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Khóa API bắt đầu bằng lk_live_. Vui lòng giữ an toàn và không bao giờ đặt vào kho lưu trữ JavaScript ngoại vi hoặc Git công khai; tất cả các cuộc gọi phải được thực hiện từ phía máy chủ của bạn.

Giới hạn tỷ lệ

Mỗi khóa có giới hạn yêu cầu mỗi phút và tiêu đề phản hồi sẽ báo cáo giới hạn còn lại:

tiêu đề	minh họa
X-RateLimit-Limit	Số lượng yêu cầu được phép mỗi phút
X-RateLimit-Remaining	Số lượng yêu cầu còn lại trong phút này
Retry-After	Số giây chờ vượt quá giới hạn thời gian (HTTP 429)

Để có trải nghiệm giao diện người dùng tốt nhất, bạn nên lưu kết quả /rates vào bộ nhớ đệm trong vài phút và tính toán chúng theo cùng một công thức trên máy chủ của riêng bạn. Chỉ gọi /quote để xác minh trong các bước quan trọng của việc đặt hàng.

GET /api/v1/freight/rates

Liệt kê tất cả các phương thức và mức giá vận chuyển hiện được kích hoạt. Không có tham số được yêu cầu.

hỏi

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

Phản hồi 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

Phí vận chuyển đường biển được tính dựa trên trọng lượng/kích thước khối lượng của gói hàng. Cả GET (chuỗi truy vấn) và POST (JSON hoặc biểu mẫu) đều được chấp nhận.

Thông số yêu cầu

tham số	Kiểu	Yêu cầu	minh họa
weight	number	Không bắt buộc*	Trọng lượng thực tế tính bằng kilôgam (kg).
length	number	Không bắt buộc*	Chiều dài, đơn vị là cm (cm).
width	number	Không bắt buộc*	Chiều rộng tính bằng cm (cm).
height	number	Không bắt buộc*	Chiều cao, đơn vị là cm (cm).
method	string	Không bắt buộc	Phương thức vận chuyển hiện tại là sea (đường biển). Khi bị bỏ qua, sea được giả định.

Ví dụ yêu cầu (GET)

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

Ví dụ về yêu cầu (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}'

Phản hồi 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
  }
}

Mô tả trường phản hồi

cánh đồng	minh họa
actual_weight	Trọng lượng thực tế (kg). 0 nếu không được cung cấp.
volume_weight	Khối lượng (khối lượng) trọng lượng (kg) = chiều dài × chiều rộng × chiều cao 10000. 0 nếu không cung cấp kích thước.
billable_weight	Trọng lượng tính cước (kg) = max (trọng lượng thực tế, trọng lượng thể tích).
billable_basis	Việc thanh toán dựa trên :actual (dựa trên trọng lượng thực tế) hoặc volumetric (dựa trên khối lượng).
freight	Cước phí cơ bản = trọng lượng thanh toán × giá cước mỗi kg (không bao gồm phụ phí).
surcharge	Phụ phí thực tế cho giao dịch này (0 nếu không được kích hoạt).
surcharge_applied	Có kích hoạt phụ phí hay không (trọng lượng thanh toán < ngưỡng).
total_fee	Số tiền vận chuyển cuối cùng phải thu là (RMB, làm tròn đến số nguyên gần nhất).

HTTP	error	minh họa
401	missing_api_key	Không có khóa API nào được cung cấp. Vui lòng thêm tiêu đề Ủy quyền hoặc X-API-Key.
401	invalid_api_key	Khóa API không hợp lệ.
403	key_suspended / key_revoked / key_expired	Khóa đã bị vô hiệu hóa/thu hồi/hết hạn.
403	insufficient_scope	Khóa không có quyền freight:read.
422	validation_failed	Lỗi định dạng tham số (loại, phạm vi).
422	missing_parameters	Không có trọng lượng hoặc chiều dài/chiều rộng/chiều cao đầy đủ được cung cấp.
422	unsupported_method	phương pháp không có trong danh sách có sẵn.
429	rate_limit_exceeded	Vượt quá giới hạn yêu cầu mỗi phút, hãy xem Thử lại sau.

0337.tw là trung tâm mua sắm Laravel. Bạn nên đóng gói API phí vận chuyển vào Dịch vụ phụ trợ và gọi: trong quá trình thanh toán:

• Sau khi nhận được tổng trọng lượng (kg)/khối lượng của giỏ hàng khi thanh toán, hãy gọi /api/v1/freight/quote trên phần phụ trợ và đặt total_fee được trả lại làm phí vận chuyển.
• Khóa được đặt trong .env (ví dụ: LUCKY_FREIGHT_KEY) và đọc bằng config(). Không được viết cứng khóa trong mã chương trình hoặc giao diện người dùng.
• Khi cuộc gọi không thành công (hết thời gian / 429), tốc độ được lưu trong bộ nhớ đệm trong /rates được tính toán cục bộ bằng cách sử dụng cùng một công thức như một bản sao lưu để đảm bảo quá trình thanh toán không bị gián đoạn.
• Số tiền tính bằng Nhân dân tệ; nếu trung tâm mua sắm thanh toán hóa đơn bằng Đô la Đài Loan mới, vui lòng tự mình áp dụng quy đổi tỷ giá hối đoái.

Ví dụ về Laravel (mặt tiền 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);
    }
}

Thêm 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] trong config/services.php, sau đó đưa LuckyFreightService vào Bộ điều khiển thanh toán để nhận cước vận chuyển.

hỗ trợ kỹ thuật: howyunqisoftware@gmail.com

Phiên bản API: v1 (ổn định). Mọi thay đổi đột phá sẽ được phát hành với số phiên bản mới (v2), v1 sẽ vẫn tương thích.

Lịch sử thay đổi: 01-06-2026 — Freight API v1 có sẵn trực tuyến (Hai Express, giá bằng RMB).