API العملاء

إنشاء واستعلام وتحديث وحذف العملاء في متجرك.

نقاط النهاية

GET

/customers

customers:read

الحصول على قائمة مرقمة من العملاء.

GET

/customers/:id

customers:read

الحصول على عميل واحد حسب المعرف.

POST

/customers

customers:write

إنشاء عميل جديد.

PUT

/customers/:id

customers:write

تحديث عميل موجود. التحديثات الجزئية مدعومة.

DELETE

/customers/:id

customers:write

حذف ناعم للعميل. يمكن استعادة السجل خلال 30 يوماً.

مرجع الحقول

الحقل	النوع	مطلوب	الوصف
id	string	لا	معرف العميل الفريد (للقراءة فقط)
name	string	نعم	الاسم الكامل للعميل
email	string	نعم	البريد الإلكتروني للعميل
phone	string	لا	رقم الهاتف مع رمز البلد
createdAt	datetime	لا	طابع زمني ISO 8601 (للقراءة فقط)
updatedAt	datetime	لا	طابع زمني ISO 8601 (للقراءة فقط)

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

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

مثال

عرض العملاء مع ترقيم الصفحات

bash

curl "https://api.mercozy.com/api/v1/external/customers?page=1&limit=20" \
  -H "X-API-Key: mk_live_xxxxx"

إنشاء عميل

bash

curl -X POST "https://api.mercozy.com/api/v1/external/customers" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  }'

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

json

{
  "data": {
    "id": "cust_abc123",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "createdAt": "2025-12-15T10:30:00Z",
    "updatedAt": "2025-12-15T10:30:00Z"
  }
}