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

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

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

جرّب Apidog اليوم

مقدمة

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

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

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

💡 نصيحة: Apidog تبسط اختبار تكاملات API. اختبر نقاط نهاية Magento، وتحقق من المصادقة، وافحص الاستجابات، وصحح الأخطاء في مساحة عمل واحدة. استورد المواصفات، وجرّب الاستجابات الوهمية، وشارك سيناريوهات الاختبار مع فريقك.

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

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

• REST API: مبنية على JSON، مناسبة لتطبيقات الويب والجوال.
• SOAP API: مبنية على XML، مثالية لتكامل المؤسسات.
• GraphQL: تعتمد على الاستعلامات، فعالة في تطبيقات الواجهة الأمامية.

مهام الـ API تشمل:

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

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

الميزة	الوصف
بروتوكولات متعددة	REST, SOAP, GraphQL
OAuth 1.0a	وصول آمن للجهات الخارجية
مصادقة الرمز المميز	رموز مميزة للمشرف والتكامل
Webhooks (الخطافات)	عمليات غير متزامنة عبر قوائم الانتظار
تحديد المعدل	قابل للتكوين لكل تثبيت
نقاط نهاية مخصصة	التوسع عبر API مخصص
المتاجر المتعددة	API واحد، طرق عرض متعددة للمتجر

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

نوع API	البروتوكول	حالة الاستخدام
REST	JSON	تطبيقات الجوال، التكاملات
SOAP	XML	أنظمة المؤسسات (SAP, Oracle)
GraphQL	GraphQL	واجهة المتجر، تطبيقات الويب التقدمية (PWA)

إصدارات Magento

الإصدار	الحالة	نهاية الدعم
Magento 2.4.x	الحالي	نشط
Adobe Commerce 2.4.x	الحالي	نشط
Magento 1.x	EOL	يونيو 2020 (لا تستخدم)

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

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

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

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

الطريقة	الأفضل لـ	مدة صلاحية الرمز المميز
رمز المشرف المميز	التكاملات الداخلية	قابل للتكوين (افتراضي: 4 ساعات)
رمز التكامل المميز	تطبيقات الجهات الخارجية	حتى الإلغاء
OAuth 1.0a	تطبيقات السوق العامة	حتى الإلغاء
رمز العميل المميز	تطبيقات العملاء	قابل للتكوين

الخطوة 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('بيانات اعتماد المشرف غير صالحة');
  const token = await response.text();
  return token;
};

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

ملاحظة أمنية: استخدم متغيرات البيئة لتخزين بيانات الاعتماد والرموز المميزة:

# ملف .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: إنشاء تكامل (موصى به للجهات الخارجية)

1. انتقل إلى System > Extensions > Integrations.
2. اضغط Add New Integration.
3. أدخل التفاصيل (الاسم، البريد الإلكتروني، Callback URL، Identity Link URL).
4. حدد الأذونات المطلوبة (منتجات، طلبات، عملاء، مخزون).
5. اضغط Save ثم Activate.
6. انسخ 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('[e-mail]', '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,
      visibility: productData.visibility || 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}`);
};

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

النوع	الوصف	حالة الاستخدام
بسيط (Simple)	SKU واحد بدون اختلافات	منتجات قياسية
قابل للتكوين	أصل له اختلافات فرعية	خيارات اللون/الحجم
مجمع (Grouped)	مجموعة من المنتجات البسيطة	حزم المنتجات
افتراضي (Virtual)	منتج غير مادي	خدمات/تنزيلات
حزمة (Bundle)	حزم منتجات قابلة للتخصيص	مجموعات "ابنِ بنفسك"
قابل للتنزيل	منتجات رقمية	كتب إلكترونية/برامج

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

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

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

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}`);
});

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

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}`);
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,
    last: true,
    items: items
  };

  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,
    notify: notify ? 1 : 0,
    append_comment: appendComment ? 1 : 0,
    comment: comment,
    tracks: tracks
  };

  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: '[e-mail]' });
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: '[e-mail]',
  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 لا توفر 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

تحديد المعدل

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

• الافتراضي: لا توجد حدود (يمكن ضبطها عبر لوحة الإدارة)
• الموصى به: 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 وMagento
• الحل: مزامنة ثنائية الاتجاه عبر API كل 15 دقيقة
• النتيجة: مخزون لحظي، منع البيع الزائد

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

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

الخلاصة

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

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

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

كيف أقوم بالمصادقة باستخدام واجهة برمجة تطبيقات 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.