كيفية استخدام Magento 2 API: دليل شامل لتكامل التجارة الإلكترونية (2026)

ملخص سريع (TL;DR)

تُمكن واجهة برمجة تطبيقات Magento 2 (Adobe Commerce) المطورين من التكامل برمجيًا مع متاجر التجارة الإلكترونية. تستخدم نقاط نهاية REST و SOAP و GraphQL مع مصادقة OAuth 1.0a والمصادقة المستندة إلى الرمز المميز، مما يوفر الوصول إلى المنتجات والطلبات والعملاء والمخزون والمزيد، مع حدود معدل قابلة للتكوين. يغطي هذا الدليل إعداد المصادقة وعمليات الإنشاء والقراءة والتحديث والحذف (CRUD) والخطافات (webhooks) ونقاط النهاية المخصصة واستراتيجيات التكامل في بيئة الإنتاج.

مقدمة

تُشغل Adobe Commerce (Magento) أكثر من 250,000 متجر للتجارة الإلكترونية بقيمة إجمالية للبضائع تزيد عن 155 مليار دولار سنويًا. بالنسبة للمطورين الذين يقومون ببناء عمليات تكامل التجارة الإلكترونية أو موصلات تخطيط موارد المؤسسات (ERP) أو تطبيقات الهاتف المحمول، فإن تكامل واجهة برمجة تطبيقات Magento ليس خيارًا - إنه ضروري للوصول إلى هذه القاعدة الضخمة من التجار.

هذا هو الواقع: يفقد التجار الذين يديرون قنوات بيع متعددة 20-30 ساعة أسبوعيًا في إدخال البيانات يدويًا بين Magento والأنظمة الأخرى. يقوم تكامل واجهة برمجة تطبيقات Magento القوي بأتمتة مزامنة المنتجات، ومعالجة الطلبات، وتحديثات المخزون، وإدارة بيانات العملاء.

يشرح هذا الدليل عملية تكامل واجهة برمجة تطبيقات Magento 2 بالكامل. ستتعلم مصادقة OAuth 1.0a والرمز المميز، ونقاط نهاية REST/SOAP/GraphQL، وإدارة المنتجات والطلبات، والخطافات (webhooks)، وتطوير واجهة برمجة تطبيقات مخصصة، واستراتيجيات النشر في بيئة الإنتاج. بنهاية هذا الدليل، سيكون لديك تكامل Magento جاهز للإنتاج.

ما هي واجهة برمجة تطبيقات Magento 2؟

توفر Magento 2 ثلاثة أنواع من واجهات برمجة التطبيقات للوصول إلى بيانات التجارة الإلكترونية:

• REST API: قائمة على JSON لتطبيقات الويب والهاتف المحمول
• SOAP API: قائمة على XML لعمليات تكامل المؤسسات
• GraphQL: قائمة على الاستعلام لتطبيقات الواجهة الأمامية الفعالة

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

• المنتجات، الفئات، والمخزون
• الطلبات، الفواتير، والشحنات
• العملاء ومجموعات العملاء
• عربة التسوق وسداد الطلب
• العروض الترويجية وقواعد التسعير
• صفحات ومكونات نظام إدارة المحتوى (CMS)
• إعدادات المتجر

الميزات الرئيسية

مقارنة واجهات برمجة التطبيقات

إصدارات Magento

البدء: إعداد المصادقة

الخطوة 1: إنشاء حساب مشرف أو تكامل

قبل الوصول إلى واجهة برمجة التطبيقات:

1. سجل الدخول إلى لوحة إدارة Magento
2. انتقل إلى System > Permissions > All Users
3. إنشاء مستخدم مشرف (للحصول على رمز مشرف مميز) أو
4. انتقل إلى System > Extensions > Integrations
5. إنشاء تكامل جديد (لـ OAuth)

الخطوة 2: اختيار طريقة المصادقة

الخطوة 3: الحصول على رمز المشرف المميز (الطريقة الأبسط)

إنشاء رمز مشرف مميز لعمليات التكامل الداخلية:

const MAGENTO_BASE_URL = process.env.MAGENTO_BASE_URL;
const MAGENTO_ADMIN_USERNAME = process.env.MAGENTO_ADMIN_USERNAME;
const MAGENTO_ADMIN_PASSWORD = process.env.MAGENTO_ADMIN_PASSWORD;

const getAdminToken = async () => {
  const response = await fetch(`${MAGENTO_BASE_URL}/rest/V1/integration/admin/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      username: MAGENTO_ADMIN_USERNAME,
      password: MAGENTO_ADMIN_PASSWORD
    })
  });

  if (!response.ok) {
    throw new Error('بيانات اعتماد المشرف غير صالحة');
  }

  // الاستجابة هي سلسلة نصية بسيطة (الرمز المميز)، وليست JSON
  const token = await response.text();
  return token;
};

// الاستخدام
const token = await getAdminToken();
console.log(`رمز المشرف المميز: ${token}`);
// تخزين الرمز المميز بشكل آمن - استخدمه لمكالمات API اللاحقة

ملاحظة أمنية: قم بتخزين الرموز المميزة بأمان:

# ملف .env
MAGENTO_BASE_URL="https://store.example.com"
MAGENTO_ADMIN_USERNAME="api_user"
MAGENTO_ADMIN_PASSWORD="secure_password_here"
MAGENTO_ACCESS_TOKEN="obtained_via_auth"

الخطوة 4: إنشاء تكامل (موصى به للجهات الخارجية)

إنشاء تكامل عبر لوحة الإدارة:

انتقل إلى System > Extensions > Integrations

انقر فوق Add New Integration

املأ التفاصيل:

• الاسم: "تكاملي"
• البريد الإلكتروني: your-email@example.com
• عنوان URL للاتصال العكسي (Callback URL): (لـ OAuth)
• عنوان URL لرابط الهوية (Identity Link URL): (لـ OAuth)

تعيين API Permissions:

• الموارد: حدد الأذونات المطلوبة
• موصى به: المنتجات، الطلبات، العملاء، المخزون

انقر فوق Save

انقر فوق Activate على التكامل الجديد

انسخ Access Token و Token Secret

الخطوة 5: الحصول على رمز العميل المميز

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

const getCustomerToken = async (email, password) => {
  const response = await fetch(`${MAGENTO_BASE_URL}/rest/V1/integration/customer/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      username: email,
      password: password
    })
  });

  if (!response.ok) {
    throw new Error('بيانات اعتماد العميل غير صالحة');
  }

  const token = await response.text();
  return token;
};

// الاستخدام
const customerToken = await getCustomerToken('customer@example.com', 'password123');

الخطوة 6: إجراء مكالمات API مصادق عليها

إنشاء عميل API قابل لإعادة الاستخدام:

const magentoRequest = async (endpoint, options = {}) => {
  const token = await getAdminToken(); // أو استرداد الرمز المميز المخزن

  const response = await fetch(`${MAGENTO_BASE_URL}/rest${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`خطأ في واجهة برمجة تطبيقات Magento: ${error.message}`);
  }

  return response.json();
};

// الاستخدام
const products = await magentoRequest('/V1/products');
console.log(`تم العثور على ${products.items.length} منتج`);

إدارة المنتجات

الحصول على المنتجات

جلب المنتجات مع التصفية:

const getProducts = async (filters = {}) => {
  const params = new URLSearchParams();

  // بناء معايير البحث
  if (filters.search) {
    params.append('searchCriteria[filterGroups][0][filters][0][field]', 'sku');
    params.append('searchCriteria[filterGroups][0][filters][0][value]', `%${filters.search}%`);
    params.append('searchCriteria[filterGroups][0][filters][0][conditionType]', 'like');
  }

  if (filters.priceFrom) {
    params.append('searchCriteria[filterGroups][1][filters][0][field]', 'price');
    params.append('searchCriteria[filterGroups][1][filters][0][value]', filters.priceFrom);
    params.append('searchCriteria[filterGroups][1][filters][0][conditionType]', 'gteq');
  }

  params.append('searchCriteria[pageSize]', filters.limit || 20);
  params.append('searchCriteria[currentPage]', filters.page || 1);

  const response = await magentoRequest(`/V1/products?${params.toString()}`);
  return response;
};

// الاستخدام
const products = await getProducts({ search: 'قميص', priceFrom: 20, limit: 50 });

products.items.forEach(product => {
  console.log(`${product.sku}: ${product.name} - $${product.price}`);
});

الحصول على منتج واحد

جلب المنتج بواسطة SKU:

const getProduct = async (sku) => {
  const response = await magentoRequest(`/V1/products/${sku}`);
  return response;
};

// الاستخدام
const product = await getProduct('TSHIRT-001');
console.log(`الاسم: ${product.name}`);
console.log(`السعر: $${product.price}`);
console.log(`المخزون: ${product.extension_attributes?.stock_item?.qty}`);

إنشاء منتج

إنشاء منتج بسيط:

const createProduct = async (productData) => {
  const product = {
    product: {
      sku: productData.sku,
      name: productData.name,
      attribute_set_id: productData.attributeSetId || 4, // المجموعة الافتراضية
      type_id: 'simple',
      price: productData.price,
      status: productData.status || 1, // 1=ممكن، 2=معطل
      visibility: productData.visibility || 4, // 4=الكتالوج والبحث
      weight: productData.weight || 1,
      extension_attributes: {
        stock_item: {
          qty: productData.qty || 0,
          is_in_stock: productData.qty > 0 ? true : false
        }
      },
      custom_attributes: [
        {
          attribute_code: 'description',
          value: productData.description
        },
        {
          attribute_code: 'short_description',
          value: productData.shortDescription
        },
        {
          attribute_code: 'color',
          value: productData.color
        },
        {
          attribute_code: 'size',
          value: productData.size
        }
      ]
    }
  };

  const response = await magentoRequest('/V1/products', {
    method: 'POST',
    body: JSON.stringify(product)
  });

  return response;
};

// الاستخدام
const newProduct = await createProduct({
  sku: 'TSHIRT-NEW-001',
  name: 'تي شيرت قطني فاخر',
  price: 29.99,
  qty: 100,
  description: 'تي شيرت قطني عالي الجودة',
  shortDescription: 'تي شيرت قطني فاخر',
  color: 'أزرق',
  size: 'M'
});

console.log(`تم إنشاء المنتج: ${newProduct.id}`);

تحديث منتج

تحديث معلومات المنتج:

const updateProduct = async (sku, updates) => {
  const product = {
    product: {
      sku: sku,
      ...updates
    }
  };

  const response = await magentoRequest(`/V1/products/${sku}`, {
    method: 'PUT',
    body: JSON.stringify(product)
  });

  return response;
};

// الاستخدام - تحديث السعر والمخزون
await updateProduct('TSHIRT-001', {
  price: 24.99,
  extension_attributes: {
    stock_item: {
      qty: 150,
      is_in_stock: true
    }
  }
});

حذف منتج

إزالة المنتج:

const deleteProduct = async (sku) => {
  await magentoRequest(`/V1/products/${sku}`, {
    method: 'DELETE'
  });

  console.log(`تم حذف المنتج ${sku}`);
};

أنواع المنتجات

إدارة الطلبات

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

جلب الطلبات مع التصفية:

const getOrders = async (filters = {}) => {
  const params = new URLSearchParams();

  if (filters.status) {
    params.append('searchCriteria[filterGroups][0][filters][0][field]', 'status');
    params.append('searchCriteria[filterGroups][0][filters][0][value]', filters.status);
    params.append('searchCriteria[filterGroups][0][filters][0][conditionType]', 'eq');
  }

  if (filters.dateFrom) {
    params.append('searchCriteria[filterGroups][1][filters][0][field]', 'created_at');
    params.append('searchCriteria[filterGroups][1][filters][0][value]', filters.dateFrom);
    params.append('searchCriteria[filterGroups][1][filters][0][conditionType]', 'gteq');
  }

  params.append('searchCriteria[pageSize]', filters.limit || 20);
  params.append('searchCriteria[currentPage]', filters.page || 1);

  const response = await magentoRequest(`/V1/orders?${params.toString()}`);
  return response;
};

// الاستخدام - الحصول على الطلبات المعلقة من آخر 7 أيام
const orders = await getOrders({
  status: 'pending',
  dateFrom: '2026-03-18 00:00:00',
  limit: 50
});

orders.items.forEach(order => {
  console.log(`الطلب رقم #${order.increment_id}: ${order.customer_email} - $${order.grand_total}`);
});

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

جلب الطلب بواسطة المعرف (ID):

const getOrder = async (orderId) => {
  const response = await magentoRequest(`/V1/orders/${orderId}`);
  return response;
};

// الاستخدام
const order = await getOrder(12345);
console.log(`الطلب رقم #${order.increment_id}`);
console.log(`الحالة: ${order.status}`);
console.log(`الإجمالي: $${order.grand_total}`);
console.log(`العناصر:`);
order.items.forEach(item => {
  console.log(`  - ${item.name} x ${item.qty_ordered}`);
});

تدفق حالة الطلب

pending ← قيد الانتظار
processing ← قيد المعالجة
complete ← مكتمل
canceled ← ملغى
on_hold ← معلق
payment_review ← مراجعة الدفع

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

تغيير حالة الطلب:

const updateOrderStatus = async (orderId, newStatus) => {
  // ملاحظة: تحديث الحالة المباشر يتطلب نقطة نهاية مخصصة
  // استخدم سير عمل إدارة الطلبات بدلاً من ذلك:

  // للإلغاء:
  await magentoRequest(`/V1/orders/${orderId}/cancel`, {
    method: 'POST'
  });

  // للتعليق:
  await magentoRequest(`/V1/orders/${orderId}/hold`, {
    method: 'POST'
  });

  // لإزالة التعليق:
  await magentoRequest(`/V1/orders/${orderId}/unhold`, {
    method: 'POST'
  });
};

إنشاء فاتورة

إنشاء فاتورة للطلب:

const createInvoice = async (orderId, items = [], notify = true, appendComment = false, comment = null) => {
  const invoice = {
    capture: true, // true = تحصيل الدفعة
    last: true,
    items: items // مصفوفة من {order_item_id, qty}
  };

  if (comment) {
    invoice.comment = comment;
    invoice.notify_customer = notify ? 1 : 0;
    invoice.append_comment = appendComment ? 1 : 0;
  }

  const response = await magentoRequest(`/V1/order/${orderId}/invoice`, {
    method: 'POST',
    body: JSON.stringify(invoice)
  });

  return response;
};

// الاستخدام - إصدار فاتورة وتحصيل طلب كامل
const invoiceId = await createInvoice(12345, [], true, false, 'شكرا لطلبك!');
console.log(`تم إنشاء الفاتورة: ${invoiceId}`);

إنشاء شحنة

شحن الطلب:

const createShipment = async (orderId, items = [], notify = true, appendComment = false, comment = null, tracks = []) => {
  const shipment = {
    items: items, // مصفوفة من {order_item_id, qty}
    notify: notify ? 1 : 0,
    append_comment: appendComment ? 1 : 0,
    comment: comment,
    tracks: tracks // مصفوفة من {track_number, title, carrier_code}
  };

  const response = await magentoRequest(`/V1/order/${orderId}/ship`, {
    method: 'POST',
    body: JSON.stringify(shipment)
  });

  return response;
};

// الاستخدام - الشحن مع التتبع
const shipmentId = await createShipment(12345, [], true, false, 'تم شحن طلبك!', [
  {
    track_number: '1Z999AA10123456784',
    title: 'رقم التتبع',
    carrier_code: 'ups'
  }
]);
console.log(`تم إنشاء الشحنة: ${shipmentId}`);

إدارة العملاء

الحصول على العملاء

جلب العملاء:

const getCustomers = async (filters = {}) => {
  const params = new URLSearchParams();

  if (filters.email) {
    params.append('searchCriteria[filterGroups][0][filters][0][field]', 'email');
    params.append('searchCriteria[filterGroups][0][filters][0][value]', filters.email);
    params.append('searchCriteria[filterGroups][0][filters][0][conditionType]', 'eq');
  }

  params.append('searchCriteria[pageSize]', filters.limit || 20);

  const response = await magentoRequest(`/V1/customers/search?${params.toString()}`);
  return response;
};

// الاستخدام
const customers = await getCustomers({ email: 'customer@example.com' });
customers.items.forEach(customer => {
  console.log(`${customer.firstname} ${customer.lastname} - ${customer.email}`);
});

إنشاء عميل

تسجيل عميل جديد:

const createCustomer = async (customerData) => {
  const customer = {
    customer: {
      websiteId: customerData.websiteId || 1,
      email: customerData.email,
      firstname: customerData.firstname,
      lastname: customerData.lastname,
      middlename: customerData.middlename || '',
      gender: customerData.gender || 0,
      store_id: customerData.storeId || 0,
      extension_attributes: {
        is_subscribed: customerData.subscribed || false
      }
    },
    password: customerData.password
  };

  const response = await magentoRequest('/V1/customers', {
    method: 'POST',
    body: JSON.stringify(customer)
  });

  return response;
};

// الاستخدام
const newCustomer = await createCustomer({
  email: 'newcustomer@example.com',
  firstname: 'جون',
  lastname: 'دو',
  password: 'SecurePass123!',
  subscribed: true
});

console.log(`تم إنشاء العميل: ID ${newCustomer.id}`);

إدارة المخزون (MSI)

الحصول على حالة المخزون

التحقق من مخزون المنتج:

const getStockStatus = async (sku) => {
  const response = await magentoRequest(`/V1/products/${sku}/stockItems/1`);
  return response;
};

// الاستخدام
const stock = await getStockStatus('TSHIRT-001');
console.log(`الكمية: ${stock.qty}`);
console.log(`في المخزون: ${stock.is_in_stock}`);
console.log(`الكمية الدنيا: ${stock.min_qty}`);

تحديث المخزون

تحديث كمية المنتج:

const updateStock = async (sku, qty, isInStock = null) => {
  const stockItem = {
    stockItem: {
      qty: qty,
      is_in_stock: isInStock !== null ? isInStock : qty > 0
    }
  };

  const response = await magentoRequest(`/V1/products/${sku}/stockItems/1`, {
    method: 'PUT',
    body: JSON.stringify(stockItem)
  });

  return response;
};

// الاستخدام
await updateStock('TSHIRT-001', 100, true);

الخطافات (Webhooks) والعمليات غير المتزامنة

إعداد الخطافات (Webhooks)

تستخدم Magento قوائم انتظار الرسائل للإشعارات غير المتزامنة:

// لا تملك Magento خطافات (webhooks) أصلية
// استخدم هذه الأساليب بدلاً من ذلك:

// 1. استطلاع نقطة نهاية الطلبات بشكل دوري
const pollNewOrders = async (lastOrderId) => {
  const orders = await getOrders({
    dateFrom: new Date().toISOString()
  });

  const newOrders = orders.items.filter(o => o.id > lastOrderId);
  return newOrders;
};

// 2. استخدم أحداث Adobe I/O (Adobe Commerce فقط)
// قم بتكوين الأحداث في Adobe Developer Console

// 3. إنشاء وحدة خطاف (webhook) مخصصة
// انظر: https://devdocs.magento.com/guides/v2.4/extension-dev-guide/message-queues/message-queues.html

تحديد المعدل

فهم حدود المعدل

حدود معدل Magento قابلة للتكوين:

• الافتراضي: لا يوجد حد (قم بالتكوين في لوحة الإدارة)
• الموصى به: 100-1000 طلب/دقيقة

التكوين في لوحة الإدارة: Stores > Configuration > Services > Web API > Security

تنفيذ معالجة حدود المعدل

const makeRateLimitedRequest = async (endpoint, options = {}, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await magentoRequest(endpoint, options);
      return response;
    } catch (error) {
      if (error.message.includes('429') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

قائمة التحقق لنشر الإنتاج

قبل النشر المباشر:

• [ ] استخدم رموز التكامل المميزة (وليس بيانات اعتماد المشرف) في بيئة الإنتاج
• [ ] قم بتخزين الرموز المميزة بأمان (قاعدة بيانات مشفرة)
• [ ] قم بتطبيق تحديد المعدل وقوائم انتظار الطلبات
• [ ] أضف معالجة شاملة للأخطاء
• [ ] قم بإعداد التسجيل لجميع مكالمات API
• [ ] أنشئ بديلاً للخطافات (webhooks) (استطلاع أو Adobe I/O)
• [ ] اختبر بحجم بيانات الإنتاج
• [ ] طبق منطق إعادة المحاولة للطلبات الفاشلة

حالات الاستخدام الواقعية

تكامل تخطيط موارد المؤسسات (ERP)

يقوم مصنع بمزامنة المخزون:

• التحدي: تحديثات يدوية للمخزون بين نظام تخطيط موارد المؤسسات (ERP) وماجنتو
• الحل: مزامنة ثنائية الاتجاه لواجهة برمجة التطبيقات كل 15 دقيقة
• النتيجة: مخزون فوري، لا يوجد بيع زائد

تطبيق الهاتف المحمول

يقوم بائع تجزئة ببناء تطبيق تسوق:

• التحدي: الحاجة إلى تجربة تطبيق جوال أصلية
• الحل: واجهة برمجة تطبيقات GraphQL لتصفح المنتجات، وواجهة REST لسداد الطلب
• النتيجة: زيادة بنسبة 40% في تحويلات الهاتف المحمول

الخلاصة

توفر واجهة برمجة تطبيقات Magento 2 وظائف تجارة إلكترونية شاملة. النقاط الرئيسية المستفادة:

• واجهات برمجة تطبيقات REST و SOAP و GraphQL متاحة
• مصادقة قائمة على الرمز المميز لعمليات التكامل
• وظائف CRUD كاملة للمنتجات والطلبات والعملاء
• MSI لإدارة المخزون المتقدمة
• حدود المعدل قابلة للتكوين لكل تثبيت
• Apidog تبسط اختبار واجهة برمجة التطبيقات وتعاون الفريق

قسم الأسئلة الشائعة

كيف أقوم بالمصادقة باستخدام واجهة برمجة تطبيقات Magento؟

استخدم رمز المشرف المميز لعمليات التكامل الداخلية أو أنشئ تكاملاً في System > Extensions لـ OAuth. رمز العميل المميز للتطبيقات الموجهة للعملاء.

ما الفرق بين REST و GraphQL في Magento؟

توفر REST عمليات CRUD كاملة. GraphQL مُحسّنة لاستعلامات الواجهة الأمامية مع جلب البيانات بكفاءة.

كيف أنشئ منتجًا عبر واجهة برمجة التطبيقات؟

استخدم POST إلى /V1/products مع بيانات المنتج بما في ذلك SKU، والاسم، والسعر، و stock_item في extension_attributes.

هل يمكنني الحصول على خطافات (webhooks) للطلبات الجديدة؟

لا تحتوي Magento على خطافات (webhooks) أصلية. استخدم الاستطلاع، أو أحداث Adobe I/O (Adobe Commerce)، أو أنشئ وحدة مخصصة.

كيف أقوم بتحديث كميات المخزون؟

استخدم PUT إلى /V1/products/{sku}/stockItems/1 مع قيم qty و is_in_stock.