API الطلبات

استرجاع الطلبات وتحديث حالتها وإدارة الشحنات.

نقاط النهاية

GET

/orders

orders:read

استرجاع قائمة مرقمة من الطلبات. يدعم التصفية حسب الحالة ونطاق التاريخ.

GET

/orders/:id

orders:read

استرجاع طلب واحد مع جميع العناصر وتفاصيل الشحن.

PUT

/orders/:id/status

orders:write

تحديث حالة الطلب (مثلاً: تعليم كمشحون).

POST

/orders/:id/shipment

orders:write

إرفاق معلومات تتبع الشحن بالطلب.

مرجع الحقول

الحقل	النوع	مطلوب	الوصف
id	string	لا	معرف الطلب الفريد (للقراءة فقط)
orderNumber	string	لا	رقم طلب مقروء (للقراءة فقط)
customerId	string	لا	معرف العميل (غير موجود للطلبات الضيفية)
status	string	لا	PENDING، CONFIRMED، PROCESSING، SHIPPED، DELIVERED، CANCELLED، REFUNDED
paymentStatus	string	لا	pending, paid, refunded, failed
paymentMethod	string	لا	طريقة الدفع المستخدمة (مثل stripe, cod)
total	integer	لا	المبلغ الإجمالي بالسنتات (للقراءة فقط)
items	OrderLine[]	لا	مصفوفة العناصر (للقراءة فقط)
shippingAddress	Address	لا	كائن عنوان الشحن
fulfillmentType	string	لا	shipping أو pickup أو delivery أو digital
createdAt	datetime	لا	طابع زمني ISO 8601 (للقراءة فقط)
updatedAt	datetime	لا	طابع زمني ISO 8601 (للقراءة فقط)

معاملات الاستعلام (القائمة)

الحقل	النوع	مطلوب	الوصف
page	integer	لا	رقم الصفحة (افتراضي: 1)
limit	integer	لا	عناصر لكل صفحة (افتراضي: 20، حد أقصى: 100)

مثال

عرض الطلبات الأخيرة

bash

curl "https://api.mercozy.com/api/v1/external/orders?page=1&limit=10" \
  -H "X-API-Key: mk_live_your_key_here"

تحديث حالة الطلب

bash

curl -X PUT "https://api.mercozy.com/api/v1/external/orders/ord_abc123/status" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped"
  }'

إنشاء تتبع شحن

bash

curl -X POST "https://api.mercozy.com/api/v1/external/orders/ord_abc123/shipment" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "fedex",
    "trackingNumber": "7489236401",
    "trackingUrl": "https://www.fedex.com/track?id=7489236401"
  }'