सेवा बाज़ार / शिपिंग शुल्क एपीआई विकास दस्तावेज़

हाइकुई माल संग्रहण एपीआई · v1

शिपिंग शुल्क एपीआई विकास दस्तावेज़

चीन → ताइवान समुद्री एक्सप्रेस माल ढुलाई वास्तविक समय गणना एपीआई। मूल्य निर्धारण आरएमबी में है, जो वास्तविक वजन और वॉल्यूम (वॉल्यूम वजन) बिलिंग का समर्थन करता है, एक ही अनुरोध पर संपूर्ण बिलिंग विवरण लौटाया जाता है। विशेष रूप से 0337.tw जैसे सीमा पार ई-कॉमर्स प्लेटफार्मों के फ्रंट-एंड फ्रेट कोटेशन के लिए डिज़ाइन किया गया है।

समुद्री एक्सप्रेस

शिपिंग विधि (सी एक्सप्रेस)

¥10/kg

दर प्रति किलोग्राम (आरएमबी)

+¥20

10 किलोग्राम से कम बिल योग्य वजन के लिए अधिभार

<50ms

औसत प्रतिक्रिया समय

1 सिंहावलोकन

फ्रेट एपीआई आपके प्लेटफ़ॉर्म को फ्रंट डेस्क पर "चीन → ताइवान सी एक्सप्रेस कलेक्शन शुल्क" तुरंत प्रदर्शित करने की अनुमति देता है, जिससे आपकी अपनी दर तालिका बनाए रखने का बोझ समाप्त हो जाता है।

क्या किया जा सकता है

माल ढुलाई गणना - पैकेज का वजन (या लंबाई, चौड़ाई और मात्रा) दर्ज करें, और पैकेज का समुद्री एक्सप्रेस शिपिंग शुल्क (आरएमबी) लौटाएं।
दर प्राप्त करें - वर्तमान प्रति किलोग्राम दर, अधिभार सीमा और वॉल्यूम रूपांतरण गुणांक को क्वेरी करें, जो आपके लिए फ्रंट एंड पर गणना या कैश करने के लिए सुविधाजनक है।

सभी प्रतिक्रियाएँ JSON में, एक एकीकृत लिफाफे प्रारूप में हैं: सफल होने पर, success: true data के साथ; असफल होने पर, success: false error कोड और message के साथ।

मूल्य निर्धारण मुद्रा: RMB (CNY / ¥)। इस एपीआई की दर सीमा पार ई-कॉमर्स सहयोग परियोजना दर है, जिसे 0523.tw आधिकारिक वेबसाइट (NTD) शिपिंग परीक्षण गणना से अलग बनाए रखा जाता है। यदि आपको न्यू ताइवान डॉलर या अन्य शिपिंग विधियों में कोटेशन की आवश्यकता है, तो सक्रिय करने के लिए कृपया हमसे संपर्क करें।

2 प्रमाणीकरण और बुनियादी जानकारी

सभी अनुरोधों को एपीआई कुंजी लानी होगी। Authorization हेडर (अनुशंसित) या X-API-Key हेडर में रखा जा सकता है।

Base URL

https://0523.tw/api/v1/freight

प्रमाणीकरण शीर्षलेख (एक चुनें)

विधि ए - बियरर टोकन (अनुशंसित)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

विधि बी - X-API-कुंजी

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

एपीआई कुंजी lk_live_ से शुरू होती है। कृपया को सुरक्षित रखें और को कभी भी फ्रंट-एंड जावास्क्रिप्ट या सार्वजनिक Git रिपॉजिटरी में न डालें; सभी कॉल आपके सर्वर साइड से की जानी चाहिए।

दर सीमा

प्रत्येक कुंजी में प्रति मिनट एक अनुरोध सीमा होती है, और प्रतिक्रिया शीर्षलेख शेष सीमा की रिपोर्ट करेगा:

हैडर	उदाहरण देकर स्पष्ट करना
`X-RateLimit-Limit`	प्रति मिनट अनुमत अनुरोधों की संख्या
`X-RateLimit-Remaining`	इस मिनट शेष अनुरोधों की संख्या
`Retry-After`	समय सीमा पार होने तक प्रतीक्षा करने के लिए सेकंड की संख्या (HTTP 429)

सर्वोत्तम फ्रंट-एंड अनुभव के लिए, /rats परिणामों को कुछ मिनटों के लिए कैश करने और उन्हें अपने सर्वर पर उसी सूत्र के साथ गणना करने की अनुशंसा की जाती है। ऑर्डर देने के महत्वपूर्ण चरणों के दौरान सत्यापन के लिए केवल /quote पर कॉल करें।

3 समापन बिंदु: दर प्राप्त करें

GET /api/v1/freight/rates

वर्तमान में सक्षम सभी शिपिंग विधियों और दरों को सूचीबद्ध करता है। किसी पैरामीटर की आवश्यकता नहीं है.

पूछना

curl https://0523.tw/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` मान लिया जाता है।

* weight और "पूर्ण लंबाई/चौड़ाई/ऊंचाई" कम से कम एक चुनें। जब दोनों प्रदान किए जाते हैं, तो सिस्टम "वास्तविक वजन" और "वॉल्यूमेट्रिक वजन" में से बड़े को बिलिंग वजन के रूप में लेता है।

उदाहरण का अनुरोध करें (प्राप्त करें)

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

उदाहरण का अनुरोध करें (पोस्ट 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}'

प्रतिक्रिया 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`	आयतन (आयतन) वजन (किलो) = लंबाई × चौड़ाई × ऊंचाई ÷ 10000. 0 यदि कोई आकार प्रदान नहीं किया गया है।
`billable_weight`	बिल करने योग्य वजन (किलो) = अधिकतम (वास्तविक वजन, बड़ा वजन)।
`billable_basis`	बिलिंग :`actual` (वास्तविक वजन के आधार पर) या `volumetric` (मात्रा के आधार पर) पर आधारित है।
`freight`	मूल भाड़ा = बिलिंग वजन × दर प्रति किलोग्राम (अधिभार को छोड़कर)।
`surcharge`	इस लेन-देन के लिए वास्तविक अधिभार (यदि ट्रिगर न हुआ हो तो 0)।
`surcharge_applied`	क्या सरचार्ज ट्रिगर करना है (बिलिंग भार <सीमा)।
`total_fee`	प्राप्य अंतिम मालभाड़ा (RMB, निकटतम पूर्ण संख्या में पूर्णांकित) है।

5 बिलिंग सूत्र और उदाहरण

इस एपीआई का गणना तर्क 0523.tw आधिकारिक वेबसाइट समुद्री एक्सप्रेस कैलकुलेटर के अनुरूप है, केवल दर को सहयोग परियोजना दर में बदल दिया गया है। आप अपने सिस्टम में उसी सूत्र का उपयोग करके इसकी पूर्वगणना कर सकते हैं।

① आयतन भार = लंबाई × चौड़ाई × ऊंचाई (सेमी) ÷ 10000
② बिलिंग वजन = अधिकतम (वास्तविक वजन, बड़ा वजन)
③ मूल भाड़ा = बिलिंग वजन × ¥10/किग्रा
④ अधिभार = बिलिंग भार < 10kg ? +¥20 : ¥0
⑤ माल प्राप्य = राउंड(③ + ④)

व्यावहारिक उदाहरण

¥1008 kg पैकेज → बिलिंग वजन 8kg <10kg → 8×10 + 20 = 100

¥20020 kg पैकेज → बिलिंग वजन 20kg ≥ 10kg → 20×10 = 200 (कोई अधिभार नहीं)

¥705 kg + बॉक्स 40×30×30 सेमी → वॉल्यूम वजन 3.6 किलोग्राम, बिल योग्य वजन 5 किलोग्राम → 5×10 + 20 = 70

¥1203 kg + बॉक्स 60×50×40 सेमी → वॉल्यूम वजन 12 किलो > वास्तविक वजन, बिल योग्य वजन 12 किलो ≥ 10 किलो → 12×10 = 120 (कोई अधिभार नहीं)

¥150 बॉक्स 50×50×60cm (केवल आकार) → वॉल्यूम वजन 15 किलो, बिलिंग वजन 15 किलो ≥ 10 किलो → 15×10 = 150

6 त्रुटि कोड

त्रुटि प्रतिक्रिया हमेशा {"सफलता": गलत, "त्रुटि": "...", "संदेश": "..." } होती है।

HTTP	`error`	उदाहरण देकर स्पष्ट करना
401	`missing_api_key`	कोई API कुंजी प्रदान नहीं की गई है. कृपया प्राधिकरण या एक्स-एपीआई-कुंजी हेडर जोड़ें।
401	`invalid_api_key`	एपीआई कुंजी अमान्य है.
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://0523.tw']);

$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://0523.tw/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://0523.tw/api/v1/freight/quote \
  -H "Authorization: Bearer $LUCKY_FREIGHT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"weight": 8, "method": "sea"}'

8 लारवेल मॉल एकीकरण सुझाव

0337.tw Laravel मॉल है। शिपिंग शुल्क एपीआई को बैकएंड सेवा में पैकेज करने और चेकआउट प्रक्रिया के दौरान कॉल करने की अनुशंसा की जाती है:

चेकआउट पर शॉपिंग कार्ट का कुल वजन (किलो)/मात्रा प्राप्त करने के बाद, बैकएंड पर /api/v1/freight/quote पर कॉल करें, और लौटाए गए total_fee को शिपिंग शुल्क के रूप में सेट करें।
कुंजी को .env (उदाहरण के लिए, LUCKY_FREIGHT_KEY) में रखा गया है और config() के साथ पढ़ा जाता है। कुंजी को प्रोग्राम कोड या फ्रंट-एंड में हार्ड-कोड न करें।
जब कॉल विफल हो जाती है (टाइमआउट / 429), तो निर्बाध चेकआउट सुनिश्चित करने के लिए /rats में कैश्ड दर की गणना बैकअप के समान सूत्र का उपयोग करके स्थानीय रूप से की जाती है।
राशि आरएमबी में है; यदि मॉल न्यू ताइवान डॉलर में बिल का निपटान करता है, तो कृपया विनिमय दर रूपांतरण स्वयं लागू करें।

लारवेल उदाहरण (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);
    }
}

'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] को config/services.php में जोड़ें, और फिर प्राप्त करने के लिए चेकआउट नियंत्रक में LuckyFreightService इंजेक्ट करें। माल ढुलाई.

सत्य का एकल स्रोत : दर केंद्रीकरण HowBridge द्वारा बनाए रखा जाता है। हमारे द्वारा दर समायोजित करने के बाद, एपीआई इसे तुरंत प्रतिबिंबित करेगा, और आपका मॉल बिना किसी संशोधन के एक साथ अपडेट हो जाएगा।

9 समर्थन और संस्करण

तकनीकी समर्थन: howyunqisoftware@gmail.com

एपीआई संस्करण: v1 (स्थिर). कोई भी ब्रेकिंग परिवर्तन एक नए संस्करण संख्या (v2) के साथ जारी किया जाएगा, v1 संगत रहेगा।

इतिहास बदलें: 2026-06-01 — फ्रेट एपीआई v1 ऑनलाइन है (हाई एक्सप्रेस, कीमत आरएमबी में)।

एपीआई कुंजी के लिए आवेदन करें