Magento 2 REST API : دليل أفضل الممارسات (2026)

# طلب token
curl -X POST https://store.com/rest/V1/integration/admin/token \
  -H "Content-Type: application/json" \
  -d '{"username": "integration_name", "password": "integration_password"}'

# الاستجابة: "q7x3p2m9..."

# استخدام token في الطلبات اللاحقة
curl https://store.com/rest/V1/products/24-MB01 \
  -H "Authorization: Bearer q7x3p2m9..."

curl -X POST https://store.com/rest/V1/integration/admin/token \
  -H "Content-Type: application/json" \
  -d '{"username": "admin_user", "password": "admin_password"}'

curl -X POST https://store.com/rest/V1/integration/customer/token \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "customer_password"}'

GET /rest/V1/products/search?
  searchCriteria[filterGroups][0][filters][0][field]=sku&
  searchCriteria[filterGroups][0][filters][0][value]=24-MB&
  searchCriteria[filterGroups][0][filters][0][conditionType]=like&
  searchCriteria[pageSize]=20&
  searchCriteria[currentPage]=1

{
  "product": {
    "sku": "CUSTOM-SKU-001",
    "name": "Custom Product",
    "price": 29.99,
    "status": 1,
    "visibility": 4,
    "type_id": "simple",
    "attribute_set_id": 4,
    "extension_attributes": {
      "stock_item": {
        "qty": 100,
        "is_in_stock": true
      }
    },
    "custom_attributes": [
      {
        "attribute_code": "description",
        "value": "Product description here"
      }
    ]
  }
}

{
  "id": 42,
  "sku": "CUSTOM-SKU-001",
  "name": "Custom Product",
  ...
}

{
  "message": "Product with SKU \"CUSTOM-SKU-001\" already exists.",
  "trace": "...",
  "parameters": {
    "sku": "CUSTOM-SKU-001"
  }
}

use Magento\Framework\Exception\LocalizedException;
use Magento\Framework\Webapi\Exception as WebapiException;

// خطأ تحقق
throw new WebapiException(
    __('Product SKU is required'),
    0,
    WebapiException::HTTP_BAD_REQUEST
);

// المورد غير موجود
throw new LocalizedException(
    __('Product with SKU "%1" not found.', $sku)
);

GET /rest/V1/products/search?
  searchCriteria[filterGroups][0][filters][0][field]=price&
  searchCriteria[filterGroups][0][filters][0][value]=50&
  searchCriteria[filterGroups][0][filters][0][conditionType]=gteq&
  searchCriteria[sortOrders][0][field]=created_at&
  searchCriteria[sortOrders][0][direction]=DESC&
  searchCriteria[pageSize]=50&
  searchCriteria[currentPage]=2

{
  "total_count": 342,
  "items": [ ... ]
}

# إنشاء منتجات مجمعة غير متزامن
POST /rest/V1/async/bulk/V1/products
Content-Type: application/json
Authorization: Bearer {token}

[
  { "product": { "sku": "BULK-001", "name": "Bulk 1", "price": 10 } },
  { "product": { "sku": "BULK-002", "name": "Bulk 2", "price": 20 } },
  ...
]

GET /rest/V1/bulk/{bulkUuid}/status

// في نقطة النهاية المخصصة الخاصة بك
$this->resultFactory->create(ResultFactory::TYPE_JSON)
    ->setData($data)
    ->setHeader('Cache-Control', 'public, max-age=3600')
    ->setHeader('ETag', md5(serialize($data)));

<!-- app/code/Vendor/Module/etc/webapi.xml -->
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    <route url="/V1/vendor/price-check/:sku" method="GET">
        <service class="Vendor\Module\Api\PriceManagementInterface" method="getPrice"/>
        <resources>
            <resource ref="anonymous"/>
        </resources>
    </route>
</routes>

<?php
declare(strict_types=1);

namespace Vendor\Module\Api;

interface PriceManagementInterface
{
    /**
     * Get current price and special price for a product
     *
     * @param string $sku
     * @return \Vendor\Module\Api\Data\PriceDataInterface
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     */
    public function getPrice(string $sku): \Vendor\Module\Api\Data\PriceDataInterface;
}

<?php
declare(strict_types=1);

namespace Vendor\Module\Api\Data;

interface PriceDataInterface
{
    /**
     * @return float
     */
    public function getPrice(): float;

    /**
     * @param float $price
     * @return $this
     */
    public function setPrice(float $price): self;

    /**
     * @return float|null
     */
    public function getSpecialPrice(): ?float;

    /**
     * @param float|null $specialPrice
     * @return $this
     */
    public function setSpecialPrice(?float $specialPrice): self;
}

<?php
declare(strict_types=1);

namespace Vendor\Module\Model;

use Vendor\Module\Api\PriceManagementInterface;
use Vendor\Module\Api\Data\PriceDataInterfaceFactory;
use Magento\Catalog\Api\ProductRepositoryInterface;

class PriceManagement implements PriceManagementInterface
{
    public function __construct(
        private readonly ProductRepositoryInterface $productRepository,
        private readonly PriceDataInterfaceFactory $priceDataFactory
    ) {}

    public function getPrice(string $sku): PriceDataInterface
    {
        $product = $this->productRepository->get($sku);
        $priceData = $this->priceDataFactory->create();
        $priceData->setPrice((float)$product->getPrice());
        $priceData->setSpecialPrice($product->getSpecialPrice() !== null
            ? (float)$product->getSpecialPrice()
            : null);
        return $priceData;
    }
}

<!-- app/code/Vendor/Module/etc/extension_attributes.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Api/etc/extension_attributes.xsd">
    <extension_attributes for="Magento\Catalog\Api\Data\ProductInterface">
        <attribute code="custom_badge" type="string"/>
    </extension_attributes>
</config>

POST /rest/V1/async/bulk/V1/products/bySkus/stockItems
[
  { "sku": "PROD-001", "qty": 50, "is_in_stock": true },
  { "sku": "PROD-002", "qty": 0, "is_in_stock": false }
]

POST /rest/V1/async/bulk/V1/customers
[
  {
    "customer": {
      "email": "[email protected]",
      "firstname": "John",
      "lastname": "Doe",
      "website_id": 1,
      "store_id": 1,
      "group_id": 1
    },
    "password": "temporary_password"
  }
]

# استخدم إطار اختبار التكامل لماجنتو
vendor/bin/phpunit -c dev/tests/integration/phpunit.xml \
  --filter testPriceEndpoint

/**
 * Get product price
 *
 * @api
 * @param string $sku
 * @return PriceDataInterface
 * @throws NoSuchEntityException
 */
public function getPrice(string $sku): PriceDataInterface;