ตลาดบริการ / เอกสารการพัฒนา API ค่าธรรมเนียมการจัดส่ง

API การรวบรวมค่าขนส่ง ทางเรือด่วน · v1

เอกสารการพัฒนา API ค่าธรรมเนียมการจัดส่ง

จีน → API การคำนวณการขนส่งสินค้าทางทะเลแบบเรียลไทม์ของไต้หวัน ราคาอยู่ในสกุลเงินหยวน ซึ่งรองรับการเรียกเก็บเงินตามน้ำหนักและปริมาณจริง (น้ำหนักตามปริมาตร) โดยมีคำขอเดียวที่ส่งคืนรายละเอียดการเรียกเก็บเงินที่สมบูรณ์ ออกแบบมาเป็นพิเศษสำหรับการเสนอราคาขนส่งส่วนหน้าของแพลตฟอร์มอีคอมเมิร์ซข้ามพรมแดน เช่น 0337.tw

ทางเรือด่วน

วิธีจัดส่ง (Sea Express)

¥10/kg

อัตราต่อกิโลกรัม (หยวน)

+¥20

คิดค่าบริการเพิ่มเติมสำหรับน้ำหนักที่เรียกเก็บเงินได้น้อยกว่า 10 กก

<50ms

เวลาตอบสนองโดยเฉลี่ย

1 ภาพรวม

API การขนส่งช่วยให้แพลตฟอร์มของคุณสามารถแสดง "ค่าธรรมเนียมการเรียกเก็บเงินด่วนทางทะเลของจีน → ไต้หวัน" ที่แผนกต้อนรับได้ทันที ซึ่งช่วยลดภาระในการรักษาตารางอัตราของคุณเอง

สิ่งที่สามารถทำได้

การคำนวณค่าขนส่ง - ป้อนน้ำหนักของพัสดุ (หรือความยาว ความกว้าง และปริมาตร) และคืนค่าธรรมเนียมการจัดส่งทางทะเลด่วน (RMB) ของพัสดุ
รับอัตรา - ค้นหาอัตราปัจจุบันต่อกิโลกรัม เกณฑ์การเพิ่ม และค่าสัมประสิทธิ์การแปลงปริมาณ ซึ่งสะดวกสำหรับคุณในการคำนวณหรือแคชที่ส่วนหน้า

การตอบกลับทั้งหมดอยู่ใน JSON ในรูปแบบซองจดหมายรวม: เมื่อสำเร็จ success: true พร้อมด้วย data; เมื่อล้มเหลว success: false พร้อมรหัส error และ message

สกุลเงินการกำหนดราคา: RMB (CNY / ¥) อัตราของ API นี้คืออัตราโครงการความร่วมมืออีคอมเมิร์ซข้ามพรมแดน ซึ่งแยกจากการคำนวณการทดลองจัดส่งเว็บไซต์อย่างเป็นทางการ (NTD) ของ 0523.tw หากคุณต้องการใบเสนอราคาเป็นดอลลาร์ไต้หวันใหม่หรือวิธีจัดส่งอื่นๆ โปรดติดต่อเราเพื่อเปิดใช้งาน

2 การรับรองและข้อมูลพื้นฐาน

คำขอทั้งหมดจะต้องนำรหัส API มาด้วย สามารถวางในส่วนหัว Authorization (แนะนำ) หรือส่วนหัว X-API-Key

Base URL

https://howbridge.cn/api/v1/freight

ส่วนหัวการตรวจสอบสิทธิ์ (เลือกอย่างใดอย่างหนึ่ง)

วิธี A — Bearer Token (แนะนำ)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

วิธี B — X-API-Key

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

คีย์ API เริ่มต้นด้วย lk_live_ โปรดรักษา ให้ปลอดภัย และอย่าใส่ ลงใน JavaScript ส่วนหน้าหรือที่เก็บ Git สาธารณะ การโทรทั้งหมดควรทำจากฝั่งเซิร์ฟเวอร์ของคุณ

ขีดจำกัดอัตรา

แต่ละคีย์มีขีดจำกัดคำขอต่อนาที และส่วนหัวการตอบกลับจะรายงานขีดจำกัดที่เหลือ:

ส่วนหัว	แสดงให้เห็น
`X-RateLimit-Limit`	จำนวนคำขอที่อนุญาตต่อนาที
`X-RateLimit-Remaining`	จำนวนคำขอที่เหลืออยู่ในนาทีนี้
`Retry-After`	จำนวนวินาทีที่รอเกินขีดจำกัดเวลา (HTTP 429)

เพื่อประสบการณ์ส่วนหน้าที่ดีที่สุด ขอแนะนำให้แคชผลลัพธ์ /rates สักครู่แล้วคำนวณด้วยสูตรเดียวกันบนเซิร์ฟเวอร์ของคุณเอง โทรไปที่ /quote เท่านั้น เพื่อตรวจสอบยืนยันระหว่างขั้นตอนสำคัญในการสั่งซื้อ

3 จุดสิ้นสุด: รับอัตรา

GET /api/v1/freight/rates

แสดงรายการวิธีการและอัตราค่าจัดส่งที่เปิดใช้งานในปัจจุบันทั้งหมด ไม่จำเป็นต้องมีพารามิเตอร์

ถาม

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

ตอบกลับ 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"
    }
  ]
}

4 จุดสิ้นสุด: การคำนวณค่าขนส่ง

GETPOST /api/v1/freight/quote

ค่าธรรมเนียมการขนส่งทางทะเลด่วนจะคำนวณตามน้ำหนัก/ขนาดบรรจุภัณฑ์ ยอมรับทั้ง GET (สตริงการสืบค้น) และ POST (JSON หรือแบบฟอร์ม)

ขอพารามิเตอร์

พารามิเตอร์	พิมพ์	ที่จำเป็น	แสดงให้เห็น
`weight`	number	ไม่จำเป็น*	น้ำหนักจริงเป็นกิโลกรัม (กก.)
`length`	number	ไม่จำเป็น*	ความยาวมีหน่วยเป็นเซนติเมตร (ซม.)
`width`	number	ไม่จำเป็น*	ความกว้างเป็นเซนติเมตร (ซม.)
`height`	number	ไม่จำเป็น*	ส่วนสูงมีหน่วยเป็นเซนติเมตร (ซม.)
`method`	string	ไม่จำเป็น	วิธีจัดส่งปัจจุบันคือ `sea` (sea express) เมื่อละเว้น `sea` จะถูกถือว่า

* weight และ "กรอก length/width/height" เลือก อย่างน้อยหนึ่งรายการ เมื่อระบุทั้งสองอย่างแล้ว ระบบจะใช้ "น้ำหนักจริง" และ "น้ำหนักปริมาตร" ที่มากกว่าเป็นน้ำหนักในการเรียกเก็บเงิน

ตัวอย่างคำขอ (GET)

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

ตัวอย่างคำขอ (POST JSON)

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

ตอบกลับ 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
  }
}

คำอธิบายฟิลด์การตอบกลับ

สนาม	แสดงให้เห็น
`actual_weight`	น้ำหนักจริง (กก.) 0 ถ้าไม่ได้ระบุไว้
`volume_weight`	ปริมาตร (ปริมาตร) น้ำหนัก (กก.) = ยาว × กว้าง × สูง ۞ 10,000 0 หากไม่มีการระบุขนาด
`billable_weight`	น้ำหนักที่เรียกเก็บเงินได้ (กก.) = สูงสุด (น้ำหนักจริง น้ำหนักปริมาตร)
`billable_basis`	การเรียกเก็บเงินจะขึ้นอยู่กับ :`actual` (ตามน้ำหนักจริง) หรือ `volumetric` (ขึ้นอยู่กับปริมาณ)
`freight`	ค่าขนส่งพื้นฐาน = น้ำหนักที่เรียกเก็บ × อัตราต่อกิโลกรัม (ไม่รวมค่าธรรมเนียมเพิ่มเติม)
`surcharge`	ค่าธรรมเนียมเพิ่มเติมจริงสำหรับธุรกรรมนี้ (0 หากไม่ถูกทริกเกอร์)
`surcharge_applied`	ว่าจะเรียกค่าธรรมเนียมเพิ่มหรือไม่ (น้ำหนักการเรียกเก็บเงิน < เกณฑ์)
`total_fee`	ลูกหนี้ค่าขนส่งสุดท้ายคือ (RMB ปัดเศษเป็นจำนวนเต็มที่ใกล้ที่สุด)

5 สูตรการเรียกเก็บเงินและตัวอย่าง

ตรรกะการคำนวณของ API นี้สอดคล้องกับเครื่องคิดเลข ทางเรือด่วน ของเว็บไซต์อย่างเป็นทางการของ 0523.tw เฉพาะอัตราเท่านั้นที่เปลี่ยนเป็นอัตราโครงการความร่วมมือ คุณสามารถคำนวณล่วงหน้าได้โดยใช้สูตรเดียวกันในระบบของคุณเอง

① น้ำหนักปริมาตร = ยาว × กว้าง × สูง (ซม.) ۞ 10000
② น้ำหนักการเรียกเก็บเงิน = สูงสุด (น้ำหนักจริง น้ำหนักปริมาตร)
3 ค่าขนส่งพื้นฐาน = น้ำหนักการเรียกเก็บเงิน × ¥10/กก.
④ ค่าบริการเพิ่มเติม = น้ำหนักการเรียกเก็บเงิน < 10kg ? +¥20 : ¥0
⑤ ลูกหนี้ค่าขนส่ง = รอบ(3 + ④)

ตัวอย่างการปฏิบัติ

¥1008 กก. แพ็คเกจ → น้ำหนักการเรียกเก็บเงิน 8กก. < 10กก. → 8×10 + 20 = 100

¥20020 กก. แพ็คเกจ → น้ำหนักการเรียกเก็บเงิน 20กก. ≥ 10กก. → 20×10 = 200 (ไม่มีค่าบริการเพิ่มเติม)

¥705 กก + กล่อง 40×30×30ซม. → น้ำหนักปริมาตร 3.6กก. น้ำหนักที่เรียกเก็บเงินได้ 5กก. → 5×10 + 20 = 70

¥1203 กก + กล่อง 60×50×40ซม. → น้ำหนักตามปริมาตร 12กก. > น้ำหนักจริง น้ำหนักที่เรียกเก็บเงินได้ 12กก. ≥ 10กก. → 12×10 = 120 (ไม่มีค่าใช้จ่าย)

¥150 กล่อง 50×50×60ซม. (ขนาดเท่านั้น) → น้ำหนักปริมาตร 15กก. น้ำหนักการเรียกเก็บเงิน 15กก. ≥ 10กก. → 15×10 = 150

6 รหัสข้อผิดพลาด

การตอบสนองข้อผิดพลาดจะเป็น { "success": false, "error": "...", "message": "..." } เสมอ

HTTP	`error`	แสดงให้เห็น
401	`missing_api_key`	ไม่มีการระบุคีย์ API โปรดเพิ่มการอนุญาตหรือส่วนหัว X-API-Key
401	`invalid_api_key`	คีย์ API ไม่ถูกต้อง
403	`key_suspended` / `key_revoked` / `key_expired`	คีย์ถูกปิดใช้งาน/เพิกถอน/หมดอายุ
403	`insufficient_scope`	คีย์ไม่ได้รับอนุญาตจาก `freight:read`
422	`validation_failed`	ข้อผิดพลาดของรูปแบบพารามิเตอร์ (ประเภท ช่วง)
422	`missing_parameters`	ไม่มีน้ำหนักหรือความยาว/ความกว้าง/ความสูงที่ให้มา
422	`unsupported_method`	วิธีการไม่อยู่ในรายการที่มีอยู่
429	`rate_limit_exceeded`	เกินขีดจำกัดคำขอต่อนาที โปรดดูที่ ลองใหม่หลังจาก

7 ตัวอย่างโปรแกรม

ตัวอย่างการโทรฝั่งเซิร์ฟเวอร์ โปรดแทนที่ lk_live_... ด้วยคีย์ของคุณ และเก็บไว้ในตัวแปรสภาพแวดล้อม

// composer require guzzlehttp/guzzle
use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://howbridge.cn']);

$res = $client->post('/api/v1/freight/quote', [
    'headers' => [
        'Authorization' => 'Bearer ' . env('LUCKY_FREIGHT_KEY'),
        'Accept'        => 'application/json',
    ],
    'json' => [
        'weight' => 8,
        'method' => 'sea',
    ],
]);

$data = json_decode($res->getBody(), true);
echo '運費 ¥' . $data['data']['total_fee'];  // 運費 ¥100

// Node.js / 伺服器端 — 請勿在瀏覽器暴露金鑰
const res = await fetch('https://howbridge.cn/api/v1/freight/quote', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LUCKY_FREIGHT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ weight: 8, method: 'sea' }),
});
const { data } = await res.json();
console.log(`運費 ¥${data.total_fee}`);  // 運費 ¥100

curl -X POST https://howbridge.cn/api/v1/freight/quote \
  -H "Authorization: Bearer $LUCKY_FREIGHT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"weight": 8, "method": "sea"}'

8 คำแนะนำการรวมห้างสรรพสินค้า Laravel

0337.tw คือห้างสรรพสินค้า Laravel ขอแนะนำให้บรรจุ API ค่าธรรมเนียมการจัดส่งลงในบริการแบ็กเอนด์และโทรไปที่: ในระหว่างกระบวนการชำระเงิน:

หลังจากได้รับน้ำหนักรวม (กก.)/ปริมาตรของตะกร้าสินค้าเมื่อชำระเงิน ให้โทรไปที่ /api/v1/freight/quote บนแบ็กเอนด์ และตั้งค่า total_fee ที่ส่งคืนเป็นค่าธรรมเนียมการจัดส่ง
คีย์ถูกวางไว้ใน .env (เช่น LUCKY_FREIGHT_KEY) และอ่านด้วย config() ห้ามฮาร์ดโค้ดคีย์ไว้ในโค้ดโปรแกรมหรือฟรอนต์เอนด์
เมื่อการโทรล้มเหลว (หมดเวลา / 429) อัตราที่แคชไว้ใน /rates จะถูกคำนวณในเครื่องโดยใช้สูตรเดียวกันกับข้อมูลสำรองเพื่อให้แน่ใจว่าการชำระเงินจะไม่หยุดชะงัก
จำนวนเงินเป็น RMB; หากห้างสรรพสินค้าชำระบิลเป็นดอลลาร์ไต้หวันใหม่ โปรดใช้การแปลงอัตราแลกเปลี่ยนด้วยตนเอง

ตัวอย่าง Laravel (ส่วนหน้า 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://howbridge.cn/api/v1/freight/quote', [
                'weight' => $weight,
                'method' => 'sea',
            ]);

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

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

เพิ่ม 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] ใน config/services.php จากนั้นฉีด LuckyFreightService ลงใน Checkout Controller เพื่อขอรับค่าขนส่ง

แหล่งเดียวของความจริง : การรวมศูนย์อัตราได้รับการดูแลโดย HowBridge หลังจากที่เราปรับอัตราแล้ว API จะแสดงทันที และห้างสรรพสินค้าของคุณจะได้รับการอัปเดตพร้อมกันโดยไม่มีการแก้ไขใดๆ

9 การสนับสนุนและเวอร์ชัน

การสนับสนุนทางเทคนิค: howyunqisoftware@gmail.com

เวอร์ชันเอพีไอ: v1 (เสถียร) การเปลี่ยนแปลงที่แตกหักใดๆ จะได้รับการเผยแพร่พร้อมกับหมายเลขเวอร์ชันใหม่ (v2) โดย v1 จะยังคงเข้ากันได้

ประวัติการเปลี่ยนแปลง: 01-06-2026 — Freight API v1 ออนไลน์อยู่ (Hai Express ราคาเป็น RMB)

สมัครคีย์ API