मर्चेंट API: SKU, ख़रीद की अग्रिम सूचना और शेन्ज़ेन वेयरहाउस का स्टॉक अपने सिस्टम से जोड़ें

अभी आप क्या कर सकते हैं

• SKU थोक में बनाएँ या अपडेट करें (आपके seller_sku के आधार पर), हर रंग और साइज़ के लिए अलग उत्पाद बारकोड के साथ, और उन्हें Shopee / Coupang / momo के उत्पाद वेरिएंट नंबर से जोड़ें।
• 11 अंकों के ताइवान टैरिफ कोड के आधार पर आयात आवश्यकताओं की अपने-आप जाँच करें, और उन उत्पादों को चिह्नित करें जिन्हें निरीक्षण या परमिट चाहिए या जिनका आयात नहीं हो सकता।
• ख़रीदारी के समय ट्रैकिंग नंबर और हर बॉक्स की सामग्री की अग्रिम सूचना दें; माल शेन्ज़ेन वेयरहाउस पहुँचने पर WO-SK लेबलिंग वर्क ऑर्डर अपने-आप बनता है, और वेयरहाउस हर पीस पर बारकोड लगाकर उसे स्कैन करके शेल्फ़ पर रखता है।
• वेयरहाउस-वार स्टॉक और स्टॉक लेजर देखें, और वेयरहाउस पहुँचने, इनबाउंड पूरा होने, मात्रा में अंतर और स्टॉक में बदलाव की सूचना webhook से तुरंत पाएँ।

इनबाउंड प्रक्रिया

1. SKU बनाएँ: उत्पाद बारकोड, वेरिएंट, घोषित उत्पाद नाम और टैरिफ कोड भेजें।
2. इनबाउंड की अग्रिम सूचना: ट्रैकिंग नंबर और हर SKU की अपेक्षित मात्रा भेजें।
3. शेन्ज़ेन वेयरहाउस में प्राप्ति: ट्रैकिंग नंबर स्कैन होते ही WO-SK वर्क ऑर्डर अपने-आप बनकर प्रिंट होता है।
4. बारकोड लगाना और शेल्फ़ पर रखना: वेयरहाउस उत्पाद बारकोड प्रिंट करता है, हर पीस पर लगाता है और स्कैन करके गिनता है।
5. इनबाउंड पूरा: वास्तव में प्राप्त मात्रा शेन्ज़ेन वेयरहाउस के स्टॉक में जुड़ती है, क्षतिग्रस्त माल अलग गिना जाता है, और अंतर की सूचना आपके सिस्टम को भेजी जाती है।

नियोजित सुविधाएँ

थोक आउटबाउंड ऑर्डर, घोषणा नियमों के अनुसार अपने-आप समूहित शिपमेंट बैच, और ताओयुआन वेयरहाउस में अग्रिम स्टॉक, छँटाई और प्लेटफ़ॉर्म शिपिंग लेबल। ये सुविधाएँ शुरू होने पर इसी पेज पर घोषित की जाएँगी।

सक्रिय करने के चरण

1. सदस्य केंद्र में “कंपनी” प्रकार का घोषणाकर्ता जोड़ें और 8 अंकों की कर पहचान संख्या भरें।
2. मर्चेंट API सक्रिय करवाने के लिए HowBridge ग्राहक सहायता से संपर्क करें; स्वीकृति मिलने पर कुंजी जारी की जाएगी।
3. कुंजी केवल एक बार दिखाई जाती है। इसे सर्वर-साइड एनवायरनमेंट वेरिएबल में रखें, ब्राउज़र या ऐप में न डालें।
4. अगर webhook चाहिए, तो पहले सदस्य केंद्र के API पेज पर URL सेट और सत्यापित करें, फिर मर्चेंट इवेंट सब्सक्राइब करें।

Base URL

फ़ॉर्मैट और भाषा

अनुरोध और रिस्पॉन्स दोनों JSON में होते हैं। त्रुटि संदेश डिफ़ॉल्ट रूप से पारंपरिक चीनी में होते हैं; अंग्रेज़ी के लिए Accept-Language: en भेजें। प्रोग्राम में जाँच के लिए हमेशा स्थिर अंग्रेज़ी error.code का उपयोग करें।

रिस्पॉन्स संरचना

सफल होने पर {"success": true, "data": …, "meta": …} लौटता है; विफल होने पर {"success": false, "error": {"code", "message", "errors", "context"}} लौटता है, जिसमें errors फ़ील्ड-वार विवरण है। एकमात्र अपवाद कुंजी न भेजना या अमान्य कुंजी है: HTTP 401, और body {"message": "Unauthenticated."} होती है।

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "errors": [
      { "code": "TRACKING_IN_USE", "field": "packages.0.tracking_no", "message": "…" }
    ]
  }
}

रेट लिमिट

हर कुंजी के लिए प्रति मिनट 60 और प्रति दिन 5,000 अनुरोध (हाई-वॉल्यूम प्लान में प्रति मिनट 300 और प्रति दिन 50,000); एक थोक अनुरोध एक ही गिना जाता है। रियल-टाइम डेटा के लिए polling न करें, webhook सब्सक्राइब करें।

आइडेम्पोटेंसी (Idempotency-Key)

राइट अनुरोधों में Idempotency-Key हेडर भेजा जा सकता है (8–128 अक्षर: अंग्रेज़ी अक्षर, अंक और _-:.)। नेटवर्क टाइमआउट के बाद उसी key और उसी सामग्री के साथ दोबारा भेजने पर पहला रिस्पॉन्स मिलता है, हेडर Idempotent-Replayed: true के साथ; उसी key को अलग सामग्री के साथ भेजने पर 422 लौटता है। रिकॉर्ड 24 घंटे तक रखे जाते हैं।

थोक रिस्पॉन्स

थोक एंडपॉइंट हर आइटम का परिणाम अलग से बताते हैं: सब सफल होने पर 200, कुछ विफल होने पर 207, और सब विफल होने पर 422। हर आइटम में index, status (created / updated / failed) और विफलता का कारण होता है।

पहचानकर्ता के अक्षर

seller_sku में केवल अंग्रेज़ी अक्षर, अंक और ._- (1–64 अक्षर) हो सकते हैं; उत्पाद बारकोड में इनके अलावा / और + (3–64 अक्षर) भी हो सकते हैं। बड़े और छोटे अक्षर एक समान माने जाते हैं।

SKU थोक में बनाएँ या अपडेट करें

POST/api/v1/merchant/skus/batch

एक बार में अधिकतम 200 आइटम। हर आइटम अलग से प्रोसेस होता है, इसलिए एक आइटम विफल होने से बाक़ी पर असर नहीं पड़ता।

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

curl -X POST https://0523.tw/api/v1/merchant/skus/batch \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-sync-20260917-001" \
  -d '{
  "items": [
    {
      "seller_sku": "TEE-RED-S",
      "barcode": "4710000000011",
      "product_name": "Cotton T-shirt",
      "spec": { "color": "red", "size": "S" },
      "declared_name_en": "Cotton knitted T-shirt",
      "declared_unit_value": 18.5,
      "declared_currency": "CNY",
      "hs_code": "61091000006",
      "weight_g": 160,
      "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566" } ]
    }
  ]
}'

प्रतिक्रिया 200

{
  "success": true,
  "data": [
    {
      "index": 0,
      "seller_sku": "TEE-RED-S",
      "status": "created",
      "sku": {
        "seller_sku": "TEE-RED-S",
        "barcode": "4710000000011",
        "system_barcode": null,
        "pick_code": "131999",
        "hs_code": "61091000006",
        "regulation": { "status": "ok", "import_codes": [], "reasons": [] },
        "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566", "platform_sku": null } ]
      }
    }
  ],
  "meta": { "summary": { "created": 1, "updated": 0, "failed": 0 } }
}

आयात आवश्यकता निर्धारण (regulation.status)

SKU खोजें

GET/api/v1/merchant/skus

seller_sku, barcode, regulation_status, updated_since (ISO 8601) से फ़िल्टर करें, और page / per_page (अधिकतम 100) से पेज बाँटें।

एक SKU

GET/api/v1/merchant/skus/{seller_sku}

प्लेटफ़ॉर्म उत्पाद मैपिंग अपडेट करें

PUT/api/v1/merchant/skus/{seller_sku}/channels

भेजी गई सूची पुरानी सभी मैपिंग की जगह ले लेती है; प्लेटफ़ॉर्म का एक ही वेरिएंट एक साथ दो SKU से नहीं जोड़ा जा सकता।

उत्पाद बारकोड लेबल डाउनलोड करें

GET/api/v1/merchant/skus/{seller_sku}/label.pdf?qty=10

40×30mm लेबल की PDF लौटाता है; qty लेबल की संख्या है (1–1000)। शेन्ज़ेन वेयरहाउस बारकोड लगाते समय यही लेबल प्रिंट करता है; यह एंडपॉइंट तब काम आता है जब आप शिपिंग से पहले ख़ुद बारकोड लगाना चाहें।

इनबाउंड ऑर्डर बनाएँ

POST/api/v1/merchant/inbound-orders

पूरे ऑर्डर का एक साथ सत्यापन: कोई भी त्रुटि होने पर कुछ नहीं बनेगा। एक ट्रैकिंग नंबर एक समय में केवल एक चालू इनबाउंड ऑर्डर में हो सकता है; एक ही पार्सल में दोहराए गए SKU की मात्रा जोड़ दी जाती है।

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

curl -X POST https://0523.tw/api/v1/merchant/inbound-orders \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: po-20260917-0001" \
  -d '{
  "reference_no": "PO-20260917-0001",
  "supplier_order_no": "1688-3312456789",
  "packages": [
    {
      "tracking_no": "YT1234567890123",
      "carrier": "yto",
      "items": [
        { "seller_sku": "TEE-RED-S", "qty": 40 },
        { "seller_sku": "TEE-RED-M", "qty": 60 }
      ]
    }
  ]
}'

इनबाउंड ऑर्डर की स्थिति

पार्सल की स्थिति

इनबाउंड ऑर्डर खोजें

GET/api/v1/merchant/inbound-orders

GET/api/v1/merchant/inbound-orders/{id}

status, reference_no, updated_since से फ़िल्टर करें। हर पार्सल के लिए अग्रिम सूचना वाली, वास्तव में प्राप्त और क्षतिग्रस्त मात्रा तथा अंतर लौटाया जाता है।

इनबाउंड ऑर्डर रद्द करें

POST/api/v1/merchant/inbound-orders/{id}/cancel

केवल तभी रद्द किया जा सकता है जब कोई पार्सल वेयरहाउस न पहुँचा हो; रद्द करने के बाद उन ट्रैकिंग नंबर की दोबारा अग्रिम सूचना दी जा सकती है।

स्टॉक देखें

GET/api/v1/merchant/inventory?warehouse_code=SZ

warehouse_code और seller_sku[] (अधिकतम 200) से फ़िल्टर करें।

प्रतिक्रिया 200

{
  "success": true,
  "data": [
    { "seller_sku": "TEE-RED-S", "barcode": "4710000000011", "warehouse_code": "SZ",
      "on_hand": 38, "reserved": 0, "available": 38, "damaged": 2, "updated_at": "2026-09-17T15:20:11+08:00" }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 100, "last_page": 1 }
}

स्टॉक लेजर

GET/api/v1/merchant/inventory/movements?after_id=0&limit=200

केवल जोड़े जाने वाले, कभी न बदले जाने वाले मूवमेंट रिकॉर्ड। after_id कर्सर से आगे के पेज लें (हर बार अधिकतम 500), और रिस्पॉन्स का meta.next_after_id सहेज लें, ताकि मिलान के लिए आगे का डेटा लेते रहें।

सेटअप कैसे करें

1. सदस्य केंद्र के API पेज पर webhook URL सेट करें (केवल https) और स्वामित्व सत्यापन पूरा करें: आपके एंडपॉइंट को HTTP 200 लौटाना होगा, जिसकी body {"challenge": "प्राप्त मान"} हो।
2. मर्चेंट इवेंट सब्सक्राइब करने के लिए PUT /api/v1/merchant/webhook/events कॉल करें। बाद में सदस्य केंद्र में URL बदलने से मर्चेंट इवेंट की सदस्यता नहीं हटती।

curl -X PUT https://0523.tw/api/v1/merchant/webhook/events \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["inbound.arrived", "inbound.received", "inbound.discrepancy", "inventory.changed"]}'

इवेंट सूची

inbound.received

{
  "event": "inbound.received",
  "delivery_id": "5b0f1c2e-8f3a-4d7e-9c21-0a6b2d4e8f10",
  "created_at": "2026-09-17T15:20:11+08:00",
  "data": {
    "inbound_order_id": 128,
    "reference_no": "PO-20260917-0001",
    "order_status": "completed_with_discrepancy",
    "tracking_no": "YT1234567890123",
    "work_order": "WO-SK-315",
    "warehouse_code": "SZ",
    "items": [
      { "seller_sku": "TEE-RED-S", "expected_qty": 40, "received_qty": 38, "damaged_qty": 2, "difference": 0 },
      { "seller_sku": "TEE-RED-M", "expected_qty": 60, "received_qty": 59, "damaged_qty": 0, "difference": -1 }
    ],
    "received_at": "2026-09-17T15:20:10+08:00"
  }
}

सिग्नेचर सत्यापित करें

हर डिलीवरी में X-Lucky-Event, X-Lucky-Delivery-Id और X-Lucky-Signature: t=टाइमस्टैम्प,v1=सिग्नेचर होते हैं। अपने webhook secret से “टाइमस्टैम्प + . + मूल body” पर HMAC-SHA256 निकालें, उसे v1 से मिलाएँ, और 5 मिनट से पुराने टाइमस्टैम्प अस्वीकार करें। एक ही इवेंट की दोबारा डिलीवरी में delivery_id नहीं बदलता, इसलिए इससे डुप्लिकेट हटाए जा सकते हैं।

2xx के अलावा कोई भी रिस्पॉन्स मिलने पर 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे और 6 घंटे बाद दोबारा भेजा जाता है; लगातार 20 बार विफल होने पर webhook अपने-आप निष्क्रिय हो जाता है और सदस्य केंद्र में दोबारा सेट करना पड़ता है।

// PHP
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_LUCKY_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig);   // ['t' => '1789…', 'v1' => 'ab12…']

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('LUCKY_WEBHOOK_SECRET'));

if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);   // de-duplicate by $event['delivery_id']
http_response_code(200);

LINE आधिकारिक खाता @0523tw

तकनीकी ईमेल howyunqisoftware@gmail.com

संस्करण v1 चरण 1 (2026-09-17): उत्पाद SKU, इनबाउंड अग्रिम सूचना, शेन्ज़ेन वेयरहाउस में बारकोड लगाना और शेल्फ़ पर रखना, स्टॉक क्वेरी, webhook।