सप्लायर API: मैन्युअल ऑर्डर दावा करना, बिना खुद को भागदौड़ में डाले

यदि आप API के माध्यम से मैन्युअल ऑर्डर पूरे करते हैं, तो पहला निर्णय यह होता है कि कौन सा एंडपॉइंट काम को क्लेम करता है, और यह वही निर्णय है जिसे अधिकांश इंटीग्रेशन गलत करते हैं। GET /orders एक रीड है। यह मांगने वाले को मिलते-जुलते ऑर्डर लौटाता है और कुछ भी नहीं बदलता। दो वर्कर चलाएँ, या एक वर्कर को रीट्राय के साथ चलाएँ, और दोनों को एक ही ऑर्डर सौंपा जाएगा और दोनों उसे डिलीवर करने का प्रयास करेंगे।

काम को क्लेम करने वाला एंडपॉइंट POST /orders-pull है। यह आपके लंबित मैन्युअल ऑर्डर चुनता है, कंपेयर एंड सेट के साथ प्रत्येक को पेंडिंग से प्रोसेसिंग में बदलता है, और केवल उन्हीं को लौटाता है जिनका फ्लिप वास्तव में सफल हुआ। यदि कोई दूसरा वर्कर एक मिलीसेकंड बाद पूछता है, तो कंपेयर विफल हो जाता है और वह ऑर्डर उसके रिस्पॉन्स में नहीं होता। इसका अपना सोर्स नोट इसे PerfectPanel संगत बताता है, जो वह रूप है जिसकी अधिकांश पैनल इंटीग्रेशन पहले से अपेक्षा करते हैं।

लूप, उस क्रम में जिसमें उसे चलना चाहिए

1. क्लेम। POST /orders-pull। वैकल्पिक बॉडी limit, डिफ़ॉल्ट 100, हार्ड कैप 500। सबसे पुराना ऑर्डर पहले।
2. लीज़, यदि आपका वर्कर धीमा है। PATCH /orders/{id}/last-process-time बिना बॉडी के अभी का समय स्टैम्प करता है, जो ऑर्डर को आपके अपने पोलिंग से तीस मिनट के लिए छिपा देता है।
3. डिलीवर। POST /orders-update क्रेडेंशियल लाइनों के साथ, या किसी बड़ी चीज़ के लिए POST /orders/{id}/accounts-bulk।
4. बंद करें। वही orders-update कॉल status: "completed" ले जाता है, या "partial" यदि आपने इसका कुछ हिस्सा भरा है।

प्रमाणीकरण हर कॉल पर एक हेडर है, और दो स्वीकृत रूप हैं:

curl -X POST "https://api.hstockplus.com/api/admin/v2/orders-pull" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50}'

# समतुल्य
curl -X POST "https://api.hstockplus.com/api/admin/v2/orders-pull" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50}'

अपने डैशबोर्ड के API Settings पेज पर कुंजी जनरेट करें। गायब हेडर API_KEY_REQUIRED लौटाता है; गलत कुंजी INVALID_API_KEY लौटाती है। ये अलग-अलग कोड हैं और इनका मतलब अलग-अलग बग हैं।

तीस मिनट की विंडो एक लीज़ है, और यह ऑप्ट इन है

दोनों लिस्टिंग एंडपॉइंट किसी भी ऑर्डर को छोड़ देते हैं जिसका lastProcessTime पिछले तीस मिनट के भीतर है। यह स्वचालित डीडुप्लिकेशन जैसा लगता है और ऐसा नहीं है, क्योंकि कोई भी एंडपॉइंट फ़ील्ड नहीं लिखता। PATCH /orders/{id}/last-process-time के माध्यम से आपके अलावा कुछ भी इसे नहीं लिखता।

इसलिए यह फ़ील्ड एक सहकारी लीज़ है। जब आप ऑर्डर उठाते हैं तो इसे स्टैम्प करें और यह आपके अगले पोल से आधे घंटे के लिए गायब हो जाता है, जो आप चाहते हैं यदि डिलीवरी में समय लगता है और आपका पोलर हर मिनट चलता है। एक अलग समाप्ति निर्धारित करने के लिए स्पष्ट ISO टाइमस्टैम्प भेजें, या इसे तुरंत रिलीज़ करने के लिए null भेजें। एंडपॉइंट को पूरी तरह से अनदेखा करें और विंडो आप पर कभी लागू नहीं होती।

orders-pull पहले से ही स्टेटस फ्लिप के माध्यम से आपको डबल क्लेमिंग से बचाता है। लीज़ दूसरे विफलता मोड के लिए है: आपके वर्कर ने ऑर्डर ले लिया, अभी भी काम कर रहा है, और आप इसे इस बीच फिर से नहीं देखना चाहते।

ऑर्डर पढ़ना, उन फ़िल्टर डिफ़ॉल्ट के साथ जो लोगों को आश्चर्यचकित करते हैं

GET /orders अभी भी रिकंसिलिएशन, बैकफिल और डैशबोर्ड के लिए सही एंडपॉइंट है। इसके दो डिफ़ॉल्ट जानने लायक हैं इससे पहले कि आप इस पर निर्माण करें।

• भुगतान स्थिति डिफ़ॉल्ट रूप से दो मानों पर सेट है, एक नहीं। बिना paymentStatus पैरामीटर के आपको वे ऑर्डर मिलते हैं जो completed या partial हैं। Partial का मतलब आंशिक रूप से रिफंड किया गया है, और वे ऑर्डर अभी भी सक्रिय काम हैं। पैरामीटर स्वयं pending, completed, failed, refunded, processing और partial से अल्पविराम से अलग की गई सूची स्वीकार करता है।
• उत्पाद प्रकार वैकल्पिक और बहुवचन है। यह मैन्युअल ऑर्डर के लिए आवश्यक नहीं है। यह manual, inventory और auto स्वीकार करता है, अल्पविराम से अलग, इसलिए productType=manual,auto मान्य है।

ऑर्डर स्थिति फ़िल्टर pending, processing, completed, refunded और error लेता है। partial उनमें से नहीं है; यह एक भुगतान स्थिति है। अन्य फ़िल्टर: entityType product या smm_service के रूप में, subCategory नाम से, createdFrom और createdTo ISO इंस्टेंट के रूप में, limit 500 तक, और offset।

curl -X GET "https://api.hstockplus.com/api/admin/v2/orders\
?status=pending,processing&productType=manual&paymentStatus=completed,partial&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

आपके द्वारा भेजी गई क्रेडेंशियल लाइनों का क्या होता है

यह वह जगह है जहाँ API पर अधिकांश सपोर्ट टिकट आते हैं, क्योंकि कुछ भी संग्रहीत होने से पहले तीन परिवर्तन चलते हैं और उनमें से कोई भी रिस्पॉन्स में दिखाई नहीं देता।

• हर तत्व न्यूलाइन पर विभाजित होता है। एक ऐरे एंट्री पूरी फ़ाइल रख सकती है। ["a:1\nb:2\nc:3"] और ["a:1","b:2","c:3"] एक ही सबमिशन हैं। खाली लाइनें और आसपास की व्हाइटस्पेस हट जाती हैं।
• दोहराव हटा दिए जाते हैं, केस-असंवेदनशील रूप से। बैच के भीतर, और उस ऑर्डर पर पहले से डिलीवर की गई हर चीज़ के विरुद्ध। टाइमआउट के बाद उसी बैच को फिर से भेजना सुरक्षित है और कुछ भी दो बार डिलीवर नहीं करता।
• ऑर्डर मात्रा से अधिक अतिरिक्त लाइनें चुपचाप छोड़ दी जाती हैं। सबमिशन शेष स्लॉट्स तक छोटा कर दिया जाता है। यह त्रुटि नहीं देता, इसलिए सही संख्या भेजें।

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

क्योंकि पिछली डिलीवरी के विरुद्ध डुप्लिकेट अस्वीकार करने के बजाय हटा दिए जाते हैं, कई कॉलों में आंशिक डिलीवरी एक समर्थित पैटर्न है। जो आपके पास है भेजें, ऑर्डर को partial चिह्नित करें, बाकी बाद में भेजें, फिर इसे completed चिह्नित करें।

दो दर सीमाएँ, दोनों अब तक अनिर्दिष्ट

orders-update प्रति API कुंजी न्यूनतम अंतराल रखता है, डिफ़ॉल्ट रूप से 200 मिलीसेकंड, और प्रति उपयोगकर्ता दो अनुरोधों की समवर्ती कैप। किसी भी एक से अधिक होने पर HTTP 429 मशीन-पठनीय देरी के साथ लौटता है:

{ "error": "RATE_LIMIT", "message": "Too many order update requests",
  "retry_after_ms": 137 }

{ "error": "CONCURRENCY_LIMIT", "message": "Too many concurrent sync requests",
  "retry_after_ms": 5000 }

retry_after_ms पढ़ें और उसके लिए सोएँ। एक निश्चित बैकऑफ़ या तो 200 ms मामले के लिए बहुत धीमा होगा या समवर्ती मामले के लिए बहुत तेज़। प्रति ऑर्डर म्यूटेक्स भी है: एक ही ऑर्डर पर दो डिलीवरी दौड़ने से ORDER_DELIVERY_BUSY मिलता है, जो भी 429 है, और सही प्रतिक्रिया अलग-अलग क्रेडेंशियल्स को फिर से भेजने के बजाय एक छोटा रीट्राय है।

त्रुटि कोड जिन्हें अलग से संभालना उचित है

• API_KEY_REQUIRED और INVALID_API_KEY: कोई हेडर नहीं बनाम एक हेडर जिसे कैश पहचान नहीं पाता।
• ORDER_NOT_FOUND: ऑर्डर आईडी कैश में नहीं है। ध्यान दें कि एक नियमित आपूर्तिकर्ता को नए बनाए गए ऑटो ऑर्डर के लिए थोड़ी दृश्यता देरी के लिए कुछ भी नहीं दिखाया जा सकता है, इसलिए निर्माण के कुछ सेकंड बाद 404 आवश्यक रूप से स्थायी नहीं है।
• ACCESS_DENIED: ऑर्डर में आपसे संबंधित कोई लाइन नहीं है।
• PAYMENT_NOT_COMPLETED: अवैतनिक या पूरी तरह से रिफंड किया गया। आप इसमें डिलीवर नहीं कर सकते और आपको रीट्राय नहीं करना चाहिए।
• INVALID_ACCOUNTS, संदेश "No valid accounts provided": ऐरे समतल होकर कुछ नहीं रह गया। आमतौर पर एक खाली स्ट्रिंग या गैर-स्ट्रिंग की ऐरे।
• RATE_LIMIT, CONCURRENCY_LIMIT, ORDER_DELIVERY_BUSY: बैक ऑफ़ करें और समान अनुरोध को फिर से करें।

आपके अपने बहीखाते के लिए दो फ़ील्ड

orders-update आपके आंतरिक ऑर्डर संदर्भ के लिए external_id स्वीकार करता है, और यह supplierOrderId को एक उपनाम के रूप में भी स्वीकार करता है यदि यह वह रूप है जो आपका पैनल पहले से भेजता है। यह external_price स्वीकार करता है, एक संख्या जो रिकॉर्ड करती है कि ऑर्डर की लागत आपको अपस्ट्रीम में कितनी थी। यह आंकड़ा संदर्भ के लिए संग्रहीत है और प्लेटफ़ॉर्म कुल को नहीं छूता। null या खाली स्ट्रिंग भेजने से जो पहले से है वह छूट जाता है, इसलिए बार-बार अपडेट इसे मिटाएंगे नहीं।

मैन्युअल का वास्तव में क्या मतलब है, और यह वास्तव में कितना तेज़ है

उत्पाद प्रकार मैन्युअल का मतलब है कि आपूर्तिकर्ता ऑर्डर आने के बाद माल अपलोड करता है। यह डिलीवरी गति सेटिंग नहीं है, और रिकॉर्ड यह स्पष्ट रूप से कहता है। साइट पर हर पूर्ण मैन्युअल उत्पाद ऑर्डर में, उनमें से 6,552, भुगतान से पूर्णता तक का औसत समय तीस सेकंड से कम है, तीन चौथाई दस मिनट के भीतर समाप्त होते हैं, और केवल लगभग चालीस में से एक को एक दिन से अधिक लगता है।

इन्वेंट्री ऑर्डर प्रभावी रूप से तत्काल हैं क्योंकि पंक्तियाँ पहले से वहाँ बैठी हैं। ऑटो ऑर्डर दोनों के बीच बैठते हैं। मैन्युअल लगभग उतना ही तेज़ दिखने का कारण ठीक यह है कि उस पर वॉल्यूम करने वाले आपूर्तिकर्ता डैशबोर्ड देखने के बजाय छोटे पोल पर इस API को चला रहे हैं। यदि आपका इंटीग्रेशन मिनट जोड़ता है, तो आप धीमी पूंछ हैं, आदर्श नहीं।

एक घड़ी जानने लायक है यदि आप खातों के बजाय विकास सेवाएँ बेचते हैं: एक विकास-सेवा ऑर्डर को डिलीवर होने के क्षण से ठीक तीन दिन की आफ्टर-सेल्स विंडो मिलती है, चाहे लिस्टिंग कुछ भी कहे। खाता लिस्टिंग अपनी वारंटी ले जाती है, प्रति लिस्टिंग निर्धारित।

एक वर्कर जो सही व्यवहार करता है

const BASE = 'https://api.hstockplus.com/api/admin/v2';
const HEAD = { 'X-Api-Key': process.env.API_KEY, 'Content-Type': 'application/json' };

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function call(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: HEAD,
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json().catch(() => ({}));
  if (res.status === 429) {
    await sleep(json.retry_after_ms ?? 1000);
    return call(method, path, body);
  }
  if (!res.ok) throw Object.assign(new Error(json.message || res.status), { code: json.error });
  return json;
}

async function tick() {
  const { orders = [] } = await call('POST', '/orders-pull', { limit: 50 });
  for (const order of orders) {
    // ऑर्डर पहले से 'processing' है और आपका है। यदि आप धीमे हैं तो लीज़ लें।
    await call('PATCH', '/orders/' + order.id + '/last-process-time', {});

    const accounts = await prepareCredentials(order); // आपका सिस्टम
    await call('POST', '/orders-update', {
      order: order.id,
      status: accounts.length >= order.quantity ? 'completed' : 'partial',
      accounts,
      supplierOrderId: 'SUP-' + order.id,
    });
  }
}

तीन चीज़ें जो यह लूप करता है जो पुराने रूप ने नहीं कीं: यह पढ़ने के बजाय क्लेम करता है, यह अनुमान लगाने के बजाय सर्वर की अपनी रीट्राय देरी का सम्मान करता है, और यह उस ऑर्डर को बंद करने के बजाय ईमानदारी से partial रिपोर्ट करता है जिसे वह भर नहीं सका।

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