توثيق واجهة برمجة التطبيقات (API)

هذه الصفحة توضح كيفية استخدام واجهة برمجة التطبيقات (API) للربط مع متجر Chicpoint. يمكن استخدام هذه الواجهة لإضافة طلبات جديدة، تحديث حالة الطلبات، والاستعلام عن الطلبات الحالية.

المصادقة

جميع طلبات API تتطلب مفتاح API للمصادقة. يجب إرسال المفتاح في رأس الطلب كالتالي:

Api-Key: chicpoint_api_key_123456

تنسيق الاستجابة

جميع استجابات API تكون بتنسيق JSON وتحتوي على حقل success يشير إلى نجاح أو فشل الطلب.

الحصول على طلب محدد

طريقة الطلب: GET

المسار: /api.php?order_id=YEM-1001

الوصف: يقوم بإرجاع تفاصيل طلب محدد بناءً على رقم الطلب.

مثال الاستجابة:

{
    "success": true,
    "data": {
        "id": 1,
        "order_id": "YEM-1001",
        "creation_date": "2023-07-01",
        "customer_name": "خالد العمري",
        "phone": "777123456",
        "city": "صنعاء",
        "address": "شارع الستين، بجوار مطعم الأصيل",
        "cod_amount": "15000.00",
        "status": "تم التسليم بنجاح",
        "agent_name": "أحمد محمد",
        "delivery_return_date": "2023-07-05",
        "notes": "تم التسليم بدون مشاكل"
    }
}

الحصول على الطلبات حسب الحالة

طريقة الطلب: GET

المسار: /api.php?status=تم التسليم بنجاح

الوصف: يقوم بإرجاع قائمة بجميع الطلبات التي لها حالة محددة.

الحصول على جميع الطلبات

طريقة الطلب: GET

المسار: /api.php?limit=50&offset=0

الوصف: يقوم بإرجاع قائمة بالطلبات مع إمكانية تحديد عدد النتائج وموضع البداية.

طريقة الطلب: POST

المسار: /api.php

الوصف: يقوم بإضافة طلب جديد إلى النظام.

مثال البيانات المرسلة:

{
    "action": "add_order",
    "order_id": "YEM-1006",
    "customer_name": "محمد علي",
    "phone": "777888999",
    "city": "صنعاء",
    "address": "شارع الزبيري، بجوار البنك المركزي",
    "cod_amount": 12500,
    "status": "تم الاستلام في السعودية",
    "notes": "طلب عاجل"
}

مثال الاستجابة:

{
    "success": true,
    "message": "Order added successfully",
    "order_id": "YEM-1006"
}

طريقة الطلب: POST

المسار: /api.php

الوصف: يقوم بتحديث حالة طلب محدد.

مثال البيانات المرسلة:

{
    "action": "update_status",
    "order_id": "YEM-1001",
    "status": "تم التسليم بنجاح"
}

مثال الاستجابة:

{
    "success": true,
    "message": "Order status updated successfully"
}

طريقة الطلب: POST

المسار: /api.php

الوصف: يقوم بتحديث حالة مجموعة من الطلبات دفعة واحدة.

مثال البيانات المرسلة:

{
    "action": "bulk_update",
    "orders": [
        {
            "order_id": "YEM-1001",
            "status": "تم التسليم بنجاح"
        },
        {
            "order_id": "YEM-1002",
            "status": "مع مندوب التوصيل"
        },
        {
            "order_id": "YEM-1003",
            "status": "مرتجع"
        }
    ]
}

مثال الاستجابة:

{
    "success": true,
    "message": "Bulk update completed",
    "success_count": 3,
    "error_count": 0
}

مثال باستخدام JavaScript/jQuery

// مثال لإضافة طلب جديد
$.ajax({
    url: 'https://yourwebsite.com/noman_logistic/api.php',
    type: 'POST',
    headers: {
        'Api-Key': 'chicpoint_api_key_123456'
    },
    data: JSON.stringify({
        action: 'add_order',
        order_id: 'YEM-1010',
        customer_name: 'أحمد علي',
        phone: '777123456',
        city: 'صنعاء',
        address: 'شارع التحرير',
        cod_amount: 15000,
        status: 'تم الاستلام في السعودية'
    }),
    contentType: 'application/json',
    success: function(response) {
        console.log('تم إضافة الطلب بنجاح:', response);
    },
    error: function(xhr, status, error) {
        console.error('حدث خطأ:', error);
    }
});

مثال باستخدام PHP

// مثال للاستعلام عن طلب
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://yourwebsite.com/noman_logistic/api.php?order_id=YEM-1001');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Api-Key: chicpoint_api_key_123456'
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);