سپلائر API گائیڈ: دستی آرڈرز کی پروسیسنگ

پیش شرط

شروع کرنے سے پہلے، یقینی بنائیں کہ آپ کے پاس ہے:

• ایک سپلائر اکاؤنٹ جس میں API تک رسائی ہو
• آپ کی API کلید (آپ اسے اپنے سپلائر ڈیش بورڈ سے بنا سکتے ہیں)
• ایڈمن 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 (ضروری): آرڈر ID (نمبر)
• status (اختیاری): نئی آرڈر کی حیثیت۔ درست اقدار: pending, processing, completed, partial, cancelled, error
• accounts (اختیاری، پروڈکٹ آرڈرز کے لیے): فارمیٹ "username:password" یا "email:password" میں اکاؤنٹ اسناد کی صف
• supplierOrderId (اختیاری): ٹریکنگ کے لیے آپ کا اندرونی آرڈر ID

اکاؤنٹ فارمیٹ

پروڈکٹ آرڈرز کے لیے، اکاؤنٹس کو تاروں کی ایک صف کے طور پر فراہم کیا جانا چاہیے۔ ہر تار ایک اکاؤنٹ کی نمائندگی کرتی ہے:

• فارمیٹ: "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';

// مرحلہ 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;
  }
}

// مرحلہ 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"
       }

   حل: تصدیق کریں کہ آرڈر ID موجود ہے اور آپ سے تعلق رکھتا ہے۔

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" کے ساتھ

یہ سادہ تین مرحلے کا عمل آپ کو اپنے آرڈر کی تکمیل کے ورک فلو کو مکمل طور پر خودکار بنانے کی اجازت دیتا ہے!

یہ دونوں سپلائر دستاویزات کے بنیادی گائیڈز ہیں۔ انہیں جوڑنے سے سپلائرز کو پروڈکٹ سیٹ اپ سے آرڈر پروسیسنگ تک تشریف لے جانے میں مدد ملتی ہے، جو ایک منطقی ورک فلو تخلیق کرتی ہے۔ پروڈکٹ مینجمنٹ گائیڈ۔