سپلائر 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. خرابیوں کا ازالہ: