دليل واجهة برمجة التطبيقات للمورد: معالجة الطلبات اليدوية

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

• حساب مورد مع وصول إلى API
• مفتاح API الخاص بك (يمكنك إنشاؤه من لوحة تحكم المورد)
• الوصول إلى نقاط نهاية Admin API v2

الخطوة 1: الحصول على مفتاح API الخاص بك

1. قم بتسجيل الدخول إلى لوحة تحكم المورد الخاصة بك
2. انتقل إلى إعدادات API (/api-settings)
3. انقر على "إنشاء مفتاح API" إذا لم يكن لديك واحد
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';

// الخطوة 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"
       }

   الحل: تحقق من وجود معرف الطلب وأنه ينتمي إليك.

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. تكرار الاستعلام: لا تستعلم بشكل متكرر جداً. تمنع واجهة برمجة التطبيقات المعالجة المكررة بفاصل زمني مدته 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"

تسمح لك عملية الخطوات الثلاث البسيطة هذه بأتمتة سير عمل تنفيذ الطلبات بالكامل!

كلاهما أدلة أساسية لوثائق الموردين. ربطهما يساعد الموردين على الانتقال من إعداد المنتج إلى معالجة الطلب، مما يخلق سير عمل منطقي. دليل إدارة المنتجات.