सप्लायर एपीआई गाइड: मैन्युअल ऑर्डर प्रोसेसिंग

पूर्वापेक्षाएँ

शुरू करने से पहले, सुनिश्चित करें कि आपके पास:

• API एक्सेस वाला एक आपूर्तिकर्ता खाता
• आपकी API कुंजी (आप इसे अपने आपूर्तिकर्ता डैशबोर्ड से जनरेट कर सकते हैं)
• Admin API v2 एंडपॉइंट तक पहुंच

चरण 1: अपनी API कुंजी प्राप्त करें

1. अपने आपूर्तिकर्ता डैशबोर्ड में लॉग इन करें
2. API सेटिंग्स (/api-settings) पर जाएं
3. यदि आपके पास नहीं है तो "Generate API Key" पर क्लिक करें
4. अपनी API कुंजी कॉपी करें और इसे सुरक्षित रखें

महत्वपूर्ण: आपकी API कुंजी को गुप्त रखा जाना चाहिए। इसे कभी भी सार्वजनिक रूप से साझा न करें या वर्जन कंट्रोल में कमिट न करें।

चरण 2: मैन्युअल ऑर्डर प्राप्त करें

लंबित और प्रोसेसिंग मैन्युअल ऑर्डर प्राप्त करने के लिए GET /api/admin/v2/orders एंडपॉइंट का उपयोग करें।

API अनुरोध

curl -X GET "https://your-domain.com/api/admin/v2/orders?status=pending,processing&productType=manual&limit=50&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

अनुरोध पैरामीटर

• status (वैकल्पिक): ऑर्डर स्थिति फ़िल्टर। अल्पविराम से अलग किए गए मानों का समर्थन करता है: pending,processing
• productType (मैन्युअल ऑर्डर के लिए आवश्यक): manual पर सेट करें
• entityType (वैकल्पिक): product या smm_service द्वारा फ़िल्टर करें
• subCategory (वैकल्पिक): उपश्रेणी नाम से फ़िल्टर करें
• limit (वैकल्पिक): वापस किए जाने वाले ऑर्डर की संख्या (अधिकतम 500, डिफ़ॉल्ट 50)
• offset (वैकल्पिक): पेजिनेशन ऑफ़सेट (डिफ़ॉल्ट 0)

उदाहरण प्रतिक्रिया

{
  "orders": [
    {
      "id": 12345,
      "order": 12345,
      "status": "pending",
      "paymentStatus": "completed",
      "quantity": 10,
      "user": {
        "id": "507f1f77bcf86cd799439011",
        "email": "customer@example.com",
        "name": "John Doe"
      },
      "items": [
        {
          "product": {
            "id": "507f1f77bcf86cd799439012",
            "name": "Instagram Followers",
            "type": "product"
          },
          "quantity": 10,
          "unitPrice": 5.00,
          "totalPrice": 50.00
        }
      ],
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "total": 1
}

महत्वपूर्ण नोट्स

• केवल paymentStatus: "completed" वाले ऑर्डर ही वापस किए जाते हैं
• डुप्लिकेट प्रोसेसिंग को रोकने के लिए ऑर्डर फ़िल्टर किए जाते हैं (30 मिनट का अंतराल)
• आप केवल उन उत्पादों/सेवाओं के ऑर्डर देख सकते हैं जो एक आपूर्तिकर्ता के रूप में आपके हैं

चरण 3: ऑर्डर प्रोसेस करें और खाते सबमिट करें

एक बार जब आपके पास ऑर्डर हों, तो उन्हें प्रोसेस करें और खाता क्रेडेंशियल तैयार करें। फिर खाते सबमिट करने और ऑर्डर स्थिति अपडेट करने के लिए POST /api/admin/v2/orders-update एंडपॉइंट का उपयोग करें।

API अनुरोध

curl -X POST "https://your-domain.com/api/admin/v2/orders-update" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 12345,
    "status": "completed",
    "accounts": [
      "username1:password1",
      "username2:password2",
      "username3:password3"
    ],
    "supplierOrderId": "SUP-ORDER-12345"
  }'

अनुरोध बॉडी पैरामीटर

• order (आवश्यक): ऑर्डर आईडी (संख्या)
• status (वैकल्पिक): नई ऑर्डर स्थिति। मान्य मान: pending, processing, completed, partial, cancelled, error
• accounts (वैकल्पिक, उत्पाद ऑर्डर के लिए): "username:password" या "email:password" प्रारूप में खाता क्रेडेंशियल की सरणी
• supplierOrderId (वैकल्पिक): ट्रैकिंग के लिए आपका आंतरिक ऑर्डर आईडी

खाता प्रारूप

उत्पाद ऑर्डर के लिए, खातों को स्ट्रिंग्स की एक सरणी के रूप में प्रदान किया जाना चाहिए। प्रत्येक स्ट्रिंग एक खाते का प्रतिनिधित्व करती है:

• प्रारूप: "username:password" या "email:password"
• उदाहरण: ["user1:pass123", "user2:pass456"]
• मात्रा: ऑर्डर मात्रा से मेल खाने वाले खाते प्रदान करें

पूर्ण कार्यप्रवाह उदाहरण

यहाँ JavaScript/Node.js का उपयोग करते हुए एक पूर्ण उदाहरण दिया गया है:

const axios = require('axios');

const API_BASE_URL = 'https://your-domain.com/api/admin/v2';
const API_KEY = 'YOUR_API_KEY';

// Step 1: लंबित और प्रोसेसिंग मैन्युअल ऑर्डर प्राप्त करें
async function getOrders() {
  try {
    const response = await axios.get(`${API_BASE_URL}/orders`, {
      params: {
        status: 'pending,processing',
        productType: 'manual',
        limit: 50,
        offset: 0
      },
      headers: {
        'X-Api-Key': API_KEY
      }
    });
    
    return response.data.orders;
  } catch (error) {
    console.error('Error fetching orders:', error.response?.data || error.message);
    throw error;
  }
}

// Step 2: ऑर्डर प्रोसेस करें और खाते सबमिट करें
async function updateOrder(orderId, accounts, supplierOrderId) {
  try {
    const response = await axios.post(
      `${API_BASE_URL}/orders-update`,
      {
        order: orderId,
        status: 'completed',
        accounts: accounts,
        supplierOrderId: supplierOrderId
      },
      {
        headers: {
          'X-Api-Key': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error updating order:', error.response?.data || error.message);
    throw error;
  }
}

// मुख्य कार्यप्रवाह
async function processOrders() {
  try {
    // ऑर्डर प्राप्त करें
    const orders = await getOrders();
    console.log(`Found ${orders.length} orders to process`);
    
    // प्रत्येक ऑर्डर प्रोसेस करें
    for (const order of orders) {
      console.log(`Processing order ${order.id}...`);
      
      // खाते तैयार करें (यह वह जगह है जहाँ आप अपने सिस्टम से लाएंगे)
      const accounts = [
        'user1:pass1',
        'user2:pass2',
        // ... order.quantity से मेल खाने वाले और खाते
      ];
      
      // खातों के साथ ऑर्डर अपडेट करें और पूर्ण के रूप में चिह्नित करें
      const updatedOrder = await updateOrder(
        order.id,
        accounts,
        `SUP-${order.id}`
      );
      
      console.log(`Order ${order.id} completed successfully`);
    }
  } catch (error) {
    console.error('Error in workflow:', error);
  }
}

// कार्यप्रवाह चलाएं
processOrders();

त्रुटि प्रबंधन

सामान्य त्रुटियाँ

1. अमान्य API कुंजी

   {
         "error": "INVALID_API_KEY",
         "message": "Invalid API key"
       }

   समाधान: जांचें कि आपकी API कुंजी सही और सक्रिय है।

2. ऑर्डर नहीं मिला

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Order not found"
       }

   समाधान: सत्यापित करें कि ऑर्डर आईडी मौजूद है और आपकी है।

3. पहुंच अस्वीकृत

   {
         "error": "ACCESS_DENIED",
         "message": "You do not have access to this order"
       }

   समाधान: सुनिश्चित करें कि ऑर्डर में ऐसे उत्पाद/सेवाएँ हैं जो आपके हैं।

4. अमान्य खाते

   {
         "error": "INVALID_ACCOUNTS",
         "message": "No valid accounts provided after deduplication"
       }

   समाधान: सुनिश्चित करें कि खातों की सरणी खाली नहीं है और इसमें मान्य स्ट्रिंग्स हैं।

सर्वोत्तम अभ्यास

1. पोलिंग आवृत्ति: बहुत बार पोल न करें। API 30 मिनट के अंतराल पर डुप्लिकेट प्रोसेसिंग को रोकता है।
2. त्रुटि प्रबंधन: हमेशा उचित त्रुटि प्रबंधन और पुनः प्रयास तर्क लागू करें।
3. खाता सत्यापन: सबमिट करने से पहले खातों को सत्यापित करें ताकि यह सुनिश्चित हो सके कि वे सही प्रारूप में हैं।
4. ऑर्डर ट्रैकिंग: अपने सिस्टम में ऑर्डर ट्रैक करने के लिए supplierOrderId का उपयोग करें।
5. स्थिति अपडेट: आप स्थिति को चरणबद्ध तरीके से अपडेट कर सकते हैं:
   • पहले इसे processing पर सेट करें जब आप इस पर काम शुरू करते हैं
   • फिर इसे completed पर सेट करें जब खाते तैयार हो जाते हैं
6. आंशिक ऑर्डर: यदि आप केवल ऑर्डर का एक हिस्सा पूरा कर सकते हैं, तो स्थिति को partial पर सेट करें और उपलब्ध खाते सबमिट करें।

सारांश

पूर्ण कार्यप्रवाह इस प्रकार है:

1. ऑर्डर प्राप्त करें: GET /api/admin/v2/orders?status=pending,processing&productType=manual
2. ऑर्डर प्रोसेस करें: प्रत्येक ऑर्डर के लिए खाते तैयार करें
3. खाते सबमिट करें: POST /api/admin/v2/orders-update खातों और status: "completed" के साथ

यह सरल तीन-चरणीय प्रक्रिया आपको अपने ऑर्डर पूर्ति कार्यप्रवाह को पूरी तरह से स्वचालित करने की अनुमति देती है!

ये दोनों मुख्य आपूर्तिकर्ता दस्तावेज़ीकरण गाइड हैं। इन्हें जोड़ने से आपूर्तिकर्ताओं को उत्पाद सेटअप से ऑर्डर प्रोसेसिंग तक नेविगेट करने में मदद मिलती है, जिससे एक तार्किक कार्यप्रवाह बनता है। उत्पाद प्रबंधन गाइड।