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

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

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

• حساب مورد مع إمكانية الوصول إلى 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';

// Step 1: Get pending and processing manual orders
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: Process order and submit accounts
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;
  }
}

// Main workflow
async function processOrders() {
  try {
    // Get orders
    const orders = await getOrders();
    console.log(`Found ${orders.length} orders to process`);
    
    // Process each order
    for (const order of orders) {
      console.log(`Processing order ${order.id}...`);
      
      // Prepare accounts (this is where you would fetch from your system)
      const accounts = [
        'user1:pass1',
        'user2:pass2',
        // ... more accounts matching order.quantity
      ];
      
      // Update order with accounts and mark as completed
      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);
  }
}

// Run the workflow
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"

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

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