راه‌اندازی فید محصول Searchwise / Snap ووکامرس

فید محصول، نشانی‌ای برای دریافت اطلاعات کاتالوگ از طریق API است. Searchwise / Snap از این نشانی، اطلاعات به‌روز محصولات را از فروشگاه شما دریافت می‌کند. عنوان، لینک، قیمت، موجودی، تصاویر، دسته‌بندی، ویژگی‌ها، برند و شناسه کالا از محصولات منتشرشده خوانده و در قالب ساختاریافته ارائه می‌شوند.

فید هنگام هر درخواست، اطلاعات را از فروشگاه می‌خواند. تغییر قیمت، موجودی و مشخصات در دریافت بعدی فید دیده می‌شود. زمان نمایش این تغییرها در اپلیکیشن اسنپ به برنامه دریافت و پردازش اطلاعات توسط Searchwise بستگی دارد.

فید در بخش تنظیمات اسنپ‌پی نمایش داده می‌شود، اما از درگاه پرداخت اسنپ‌پی مستقل است. برای استفاده از آن به Merchant ID، رمز عبور، توکن یا فعال‌بودن درگاه پرداخت اسنپ‌پی نیاز ندارید. تنها ارتباط این دو بخش، محل نمایش تنظیمات در فرایند راه‌اندازی اسنپ است.

تفاوت فید محصول با درگاه اسنپ‌پی

این دو قابلیت هدف‌های متفاوتی دارند:

قابلیت	کاربرد
فید Searchwise / Snap	ارسال اطلاعات کاتالوگ برای جست‌وجو و نمایش محصول در اپلیکیشن اسنپ
درگاه اسنپ‌پی	پرداخت اقساطی سفارش در Checkout ووکامرس

در نتیجه:

• می‌توانید فید را با درگاه اسنپ‌پی خاموش استفاده کنید؛
• فید هیچ‌یک از اطلاعات ورود درگاه را مصرف نمی‌کند؛
• خاموش‌کردن درگاه پرداخت نباید فید فعال را متوقف کند؛
• تغییر کلید فید اثری بر تراکنش‌های اسنپ‌پی ندارد؛
• خطای پرداخت اسنپ‌پی با خطای دریافت فید یک مسئله واحد نیست.

ورود به تنظیمات فید محصول

تنظیمات فید در پنل اسنپ‌پی از بخش درگاه‌های پرداخت قرار دارد:

1. وارد پیشخوان وردپرس شوید.
2. از منوی جم پک، «درگاه‌های پرداخت» را انتخاب کنید.
3. پنل «اسنپ‌پی» را باز کنید.
4. بخش «فید محصول برای جست‌وجوی اپلیکیشن اسنپ» را پیدا کنید.

نشانی صفحه تنظیمات:

/wp-admin/admin.php?page=gempack#payment-gateways

قرارگرفتن تنظیمات فید داخل پنل اسنپ‌پی به معنی وابستگی فنی آن به درگاه پرداخت نیست.

ساخت کلید امن فید

کلید فید مانند یک رمز دسترسی به کاتالوگ عمل می‌کند. هرکس آن را در اختیار داشته باشد می‌تواند اطلاعات محصولات منتشرشده، از جمله وضعیت محصولات ناموجود را از مسیر فید بخواند.

یک کلید مناسب باید:

• حداقل ۳۲ کاراکتر داشته باشد؛
• تصادفی و غیرقابل حدس باشد؛
• با رمز مدیریت، کلید درگاه یا رمز دیتابیس یکسان نباشد؛
• فقط در اختیار Searchwise و مدیران مجاز قرار بگیرد؛
• در تیکت عمومی، تصویر آموزشی یا گزارش خطا نمایش داده نشود؛
• در پارامتر URL قرار نگیرد.

نمونه نمایشی زیر را استفاده نکنید:

YOUR_LONG_RANDOM_FEED_KEY

کلید واقعی را با ابزار امن مدیریت رمز بسازید. استفاده از نام دامنه، شماره تلفن یا عبارت قابل پیش‌بینی امنیت مناسبی ندارد.

فعال‌سازی مرحله‌به‌مرحله

1. در تنظیمات فید، گزینه «فعال‌سازی فید محصول» را روشن کنید.
2. کلید تصادفی حداقل ۳۲ کاراکتری را در فیلد «کلید فید» وارد کنید.
3. تنظیمات را ذخیره کنید.
4. آدرس فید نمایش‌داده‌شده در همان بخش را کپی کنید.
5. یک درخواست آزمایشی با هدر X-API-Key ارسال کنید.
6. پاسخ، واحد پول، تعداد محصولات و چند محصول نمونه را بررسی کنید.
7. آدرس و کلید را از مسیر امن در اختیار تیم Searchwise قرار دهید.
8. اگر فایروال دارید، IPهای تأییدشده خزنده را به فهرست مجاز آن اضافه کنید.

برای فعال‌شدن فید، گزینه فعال‌سازی را روشن کنید، کلید را وارد کنید و دسترسی Pro معتبر داشته باشید.

آدرس و روش درخواست فید

مسیر REST فید:

/wp-json/aio/v1/product/feed

نمونه کامل روی دامنه فرضی:

https://example.com/wp-json/aio/v1/product/feed

هر دو متد GET و POST پذیرفته می‌شوند. روش معمول برای مشاهده و آزمایش، GET است.

کلید باید در هدر درخواست ارسال شود:

X-API-Key: YOUR_LONG_RANDOM_FEED_KEY

هدرهای x_api_key و X-AIO-Feed-Key نیز در نسخه بررسی‌شده پذیرفته می‌شوند، اما X-API-Key انتخاب اصلی و خواناتر برای پیکربندی است.

کلید را به شکل ?key=... داخل URL قرار ندهید. پارامتر URL ممکن است در تاریخچه مرورگر، لاگ سرور، ابزار آمار یا سرویس‌های واسط ثبت شود.

آزمایش با curl

دریافت ده محصول از صفحه اول:

curl --request GET \
  --header "X-API-Key: YOUR_LONG_RANDOM_FEED_KEY" \
  "https://example.com/wp-json/aio/v1/product/feed?page=1&size=10"

دریافت صفحه دوم با صد محصول:

curl --request GET \
  --header "X-API-Key: YOUR_LONG_RANDOM_FEED_KEY" \
  "https://example.com/wp-json/aio/v1/product/feed?page=2&size=100"

در آزمایش واقعی، دامنه و کلید نمونه را جایگزین کنید. فرمان دارای کلید واقعی را در فایل عمومی، اسکرین‌شات یا تاریخچه اشتراکی ترمینال قرار ندهید.

صفحه‌بندی محصولات

برای خزش کل کاتالوگ از پارامترهای زیر استفاده می‌شود:

پارامتر	کاربرد	مقدار پیش‌فرض یا محدودیت
page	شماره صفحه	پیش‌فرض 1
size	تعداد محصول هر صفحه	پیش‌فرض 100، حداکثر 200

نمونه:

?page=3&size=100

نام‌های per_page و limit نیز برای اندازه صفحه پذیرفته می‌شوند. اگر چند نام هم‌زمان ارسال شوند، سیستم به‌ترتیب size، سپس per_page و بعد limit نخستین مقدار معتبر را استفاده می‌کند.

پاسخ صفحه‌بندی شامل این اطلاعات است:

• count: تعداد کل محصولات منطبق؛
• max_pages: تعداد صفحه‌ها؛
• page: صفحه فعلی؛
• size: اندازه صفحه؛
• products: آرایه محصولات همان صفحه.

محصولات در خزش عمومی بر اساس شناسه، از جدیدتر به قدیمی‌تر مرتب می‌شوند.

برای فروشگاه بزرگ، دریافت صفحه‌های ۱۰۰تایی معمولاً تعادل مناسبی میان سرعت و فشار سرور ایجاد می‌کند. افزایش اندازه تا ۲۰۰ مجاز است، اما باید زمان پاسخ و منابع هاست آزمایش شوند.

دریافت محصول مشخص

برای دریافت چند محصول بر اساس شناسه:

?products=123,456,789

برای دریافت بر اساس نامک (Slug) محصول:

?slugs=product-one,product-two

حداکثر ۲۰۰ شناسه یا Slug در یک درخواست پردازش می‌شود. مقدارهای تکراری حذف می‌شوند.

اگر هم‌زمان products و slugs ارسال شوند، شناسه‌های products اولویت دارند.

این حالت برای آزمایش محصول مشکل‌دار یا بروزرسانی انتخابی مفید است. فقط محصولات منتشرشده بازگردانده می‌شوند؛ پیش‌نویس، خصوصی یا حذف‌شده در خروجی قرار نمی‌گیرد.

نکته: خزش صفحه‌بندی‌شده محصولات مخفی از کاتالوگ را کنار می‌گذارد، اما درخواست مستقیم یک شناسه یا Slug می‌تواند محصول منتشرشده‌ای را که از کاتالوگ مخفی شده نیز برگرداند. کلید فید را با درنظرگرفتن همین سطح دسترسی محرمانه نگه دارید.

افزودن محتوای کامل محصول

به‌صورت پیش‌فرض محتوای کامل ویرایشگر محصول در پاسخ قرار نمی‌گیرد. برای افزودن آن:

?include_content=true

در این حالت فیلد content نیز به هر محصول اضافه می‌شود.

محتوای کامل می‌تواند HTML، شورت‌کد یا داده ساخته‌شده توسط صفحه‌ساز داشته باشد و حجم پاسخ را به‌شدت افزایش دهد. فقط زمانی آن را فعال کنید که Searchwise صریحاً به این فیلد نیاز داشته باشد. برای خزش معمول، توضیح کوتاه و سایر فیلدهای استاندارد سبک‌ترند.

چه محصولاتی در خزش اصلی قرار می‌گیرند؟

در دریافت صفحه‌بندی‌شده، محصول باید این شرایط را داشته باشد:

• Post Type محصول ووکامرس باشد؛
• وضعیت محصول publish باشد؛
• محصول با وضعیت «پنهان از کاتالوگ» علامت‌گذاری نشده باشد.

محصول ناموجود از فید حذف نمی‌شود. مقدار availability برای آن out of stock خواهد بود تا موتور جست‌وجو وضعیت موجودی را تشخیص دهد.

محصولی که فقط از نتایج جست‌وجوی داخلی فروشگاه مخفی شده اما از کاتالوگ حذف نشده است، بسته به تنظیم Product Visibility ممکن است همچنان در خزش قرار بگیرد. اگر نباید محصول به سرویس بیرونی معرفی شود، وضعیت دیده‌شدن آن را دقیق بررسی کنید.

فیلدهای هر محصول

هر رکورد می‌تواند فیلدهای زیر را داشته باشد:

فیلد	محتوا
id	شناسه محصول
sku	کد SKU
slug	Slug محصول
title	نام محصول
subtitle	عنوان دوم یا انگلیسی در صورت وجود
link	پیوند عمومی محصول
image_link	آرایه تصاویر اصلی با اندازه کامل
availability	in stock یا out of stock
regular_price	قیمت عادی به ریال
sale_price	قیمت فروش به ریال یا صفر
category	مسیر سلسله‌مراتبی دسته
description	ویژگی‌های محصول به‌صورت نام و مقدار
short_description	توضیح کوتاه محصول
brand	برند شناسایی‌شده
GTIN	شناسه جهانی یا بارکد شناسایی‌شده
color	مقدار ویژگی رنگ در صورت شناسایی
size	مقدار ویژگی سایز یا اندازه در صورت شناسایی
shipping_cost	هزینه ارسال اختصاصی محصول به ریال، در صورت وجود متا
delivery_time	روزهای تحویل اختصاصی محصول، در صورت وجود متا
stock_quantity	موجودی عددی یا null
type	نوع محصول ووکامرس

اگر include_content فعال باشد، فیلد content نیز افزوده می‌شود.

در سطح اصلی پاسخ نیز این موارد وجود دارند:

currency
generated_at
plugin_version
wc_version
wp_version

مقدار currency همیشه IRR است و generated_at زمان تولید پاسخ را به‌صورت Unix Timestamp نشان می‌دهد.

قیمت‌ها و تبدیل به ریال

Searchwise قیمت را به ریال انتظار دارد؛ به همین دلیل فید قیمت عادی، قیمت فروش و هزینه ارسال محصول را پیش از خروجی به ریال تبدیل می‌کند.

رفتار واحدهای پشتیبانی‌شده:

• ریال ایران: مقدار با همان مقیاس ارسال می‌شود؛
• تومان و نام‌های رایج واحد تومان: مبلغ در ۱۰ ضرب می‌شود؛
• هزار تومان با کد IRHT: مبلغ در ۱۰٬۰۰۰ ضرب می‌شود؛
• هزار ریال با کد IRHR: مبلغ در ۱٬۰۰۰ ضرب می‌شود.

برای نمونه، محصول ۸۲۸٬۰۰۰ تومانی باید در فید با مقدار زیر دیده شود:

8280000

فید سرویس تبدیل ارز عمومی نیست. اگر واحد فروشگاه دلار، یورو یا واحد ناشناخته دیگری باشد، نرخ تبدیل ارزی انجام نمی‌شود و عدد خام با برچسب IRR ارسال خواهد شد. بنابراین این فید را فقط با واحد ریال یا یکی از واحدهای تومان پشتیبانی‌شده فعال کنید.

پس از راه‌اندازی، حداقل سه محصول را با قیمت عادی، فروش ویژه و بدون تخفیف مقایسه کنید.

قیمت عادی و فروش ویژه

برای محصول ساده:

• regular_price قیمت عادی به ریال است؛
• اگر محصول در فروش ویژه باشد، sale_price قیمت جاری تخفیف‌خورده به ریال است؛
• اگر تخفیفی فعال نباشد، sale_price برابر صفر خواهد بود.

صفر بودن sale_price به معنی رایگان‌بودن محصول نیست. مصرف‌کننده فید باید در این حالت از regular_price استفاده کند.

تاریخ شروع و پایان فروش ویژه به‌عنوان فیلد جداگانه ارسال نمی‌شود. وضعیت تخفیف در زمان تولید پاسخ توسط ووکامرس تعیین می‌شود.

رفتار محصولات متغیر

هر محصول متغیر، یک رکورد محصول مادر در فید دارد. حالت‌های مختلف آن (Variation)، مثل رنگ یا اندازه، رکورد جداگانه‌ای در صفحه‌بندی ندارند.

برای تعیین قیمت:

1. Variationهای محصول به ترتیب داخلی بررسی می‌شوند؛
2. قیمت نخستین Variation موجود استفاده می‌شود؛
3. قیمت عادی همان Variation در regular_price قرار می‌گیرد؛
4. اگر آن Variation در فروش ویژه باشد، قیمت جاری آن در sale_price قرار می‌گیرد؛
5. اگر هیچ Variation موجودی پیدا نشود، کمترین قیمت عادی و جاری میان Variationها به‌عنوان مقدار جایگزین استفاده می‌شود.

«نخستین Variation موجود» لزوماً ارزان‌ترین Variation موجود نیست. ترتیب Variationها و قیمت نمایش‌داده‌شده را برای محصولات مهم بررسی کنید.

ویژگی‌های قابل استفاده محصول مادر در description قرار می‌گیرند. مقدارهای رنگ و سایز نیز از ویژگی‌هایی با نام‌های شناخته‌شده استخراج می‌شوند. اگر ساختار Variation یا ویژگی‌ها بسیار سفارشی است، خروجی را بررسی و در صورت نیاز با فیلتر توسعه‌دهنده اصلاح کنید.

موجودی محصول

وضعیت کلی موجودی در فیلد availability ارسال می‌شود:

in stock
out of stock

اگر مدیریت عددی موجودی برای محصول فعال باشد، stock_quantity مقدار موجودی را برمی‌گرداند. اگر ووکامرس موجودی عددی را برای آن محصول مدیریت نکند، این فیلد null خواهد بود.

محصولات ناموجود در فید باقی می‌مانند تا سرویس دریافت‌کننده بتواند وضعیت آن‌ها را بروزرسانی کند. کلید فید باید محرمانه باشد، زیرا دارنده آن به اطلاعات محصولات ناموجود نیز دسترسی دارد.

در محصول متغیر، وضعیت و موجودی محصول مادر می‌تواند با موجودی Variationها ارتباط داشته باشد. چند محصول متغیر کاملاً موجود، نیمه‌موجود و کاملاً ناموجود را آزمایش کنید.

دسته‌بندی محصول

فیلد category یک مسیر از دسته ریشه تا عمیق‌ترین دسته محصول می‌سازد. نمونه:

مد و پوشاک < مردانه < پیراهن

اگر محصول عضو چند دسته باشد، عمیق‌ترین مسیر شناسایی‌شده انتخاب می‌شود. فقط یک مسیر در این فیلد ارسال می‌شود، نه فهرست همه دسته‌ها.

برای بهبود کیفیت جست‌وجو:

• ساختار دسته‌ها را منطقی و سلسله‌مراتبی نگه دارید؛
• محصول را بدون نیاز در چند شاخه عمیق هم‌سطح قرار ندهید؛
• نام دسته‌ها را برای مشتری قابل فهم انتخاب کنید؛
• دسته‌های آزمایشی یا مدیریتی را از محصول عمومی حذف کنید.

تصاویر محصول

image_link یک آرایه از URL تصاویر است:

1. تصویر شاخص در ابتدا؛
2. سپس تصاویر گالری؛
3. تصویر تکراری حذف می‌شود.

تصاویر با اندازه full ارسال می‌شوند، نه Thumbnail. خود فایل تصویر داخل پاسخ قرار نمی‌گیرد؛ فقط URL آن ارائه می‌شود.

بررسی کنید:

• URL تصویر از بیرون سایت قابل دسترسی باشد؛
• تصویر با HTTPS بارگذاری شود؛
• فایروال یا Hotlink Protection خزنده را مسدود نکند؛
• تصاویر حذف‌شده یا دارای خطای ۴۰۴ در گالری نباشند؛
• اندازه فایل اصلی بیش از حد سنگین نباشد؛
• تصویر شاخص محصول مشخص شده باشد.

ویژگی‌ها، رنگ و سایز

ویژگی‌های محصول در فیلد description به‌صورت یک شیء نام و مقدار ارسال می‌شوند. اگر یک ویژگی چند مقدار داشته باشد، خروجی آن می‌تواند آرایه باشد.

برای پرکردن فیلد اختصاصی color، نام‌های زیر بررسی می‌شوند:

color
colour
رنگ

برای size:

size
سایز
اندازه

اگر نام ویژگی فروشگاه متفاوت باشد، فیلد عمومی description همچنان آن را دارد، اما color یا size ممکن است خالی بماند. در صورت نیاز می‌توان خروجی هر محصول را با فیلتر توسعه‌دهنده اصلاح کرد.

برند محصول

برای یافتن برند، منابع زیر به‌ترتیب بررسی می‌شوند:

1. دسته‌بندی برندِ خود ووکامرس با نام product_brand؛
2. pwb-brand؛
3. pa_brand؛
4. yith_product_brand؛
5. متای _brand.

نخستین برند شناسایی‌شده در خروجی قرار می‌گیرد. اگر فروشگاه از افزونه یا کلید دیگری استفاده کند، فیلد برند خالی می‌ماند مگر اینکه خروجی سفارشی شود.

GTIN و بارکد

اگر نسخه ووکامرس فیلد شناسه یکتای جهانی را پشتیبانی کند، مقدار آن در اولویت است. در غیر این صورت کلیدهای متداول زیر بررسی می‌شوند:

_gtin
_ean
_upc
_barcode
_isbn

نخستین مقدار موجود در فیلد GTIN قرار می‌گیرد. اگر افزونه بارکد شما از کلید دیگری استفاده می‌کند، باید نگاشت سفارشی ایجاد شود.

عنوان دوم محصول

فیلد subtitle از نخستین متای موجود در این فهرست خوانده می‌شود:

_aio_wc_subtitle
_subtitle
_english_title
_english_name

اگر هیچ‌کدام وجود نداشته باشند، عنوان دوم خالی است. این فیلد را می‌توان با فیلتر aio_wc_product_feed_subtitle نیز تولید کرد.

هزینه ارسال و زمان تحویل محصول

فید دو متای اختیاری را نیز می‌خواند:

_shipping_cost
_delivery_days

مقدار _shipping_cost مانند قیمت محصول به ریال تبدیل می‌شود و _delivery_days به عدد صحیح تبدیل خواهد شد.

این فیلدها هزینه نهایی روش‌های ارسال در مناطق حمل‌ونقل ووکامرس را نشان نمی‌دهند. اگر چنین متاهایی در محصول ذخیره نشده باشند، خروجی آن‌ها صفر خواهد بود. پیش از اتکا به این دو فیلد، ساختار داده موردنیاز Searchwise و منبع این اطلاعات در فروشگاه را بررسی کنید.

سفارشی‌سازی خروجی برای توسعه‌دهندگان

برای تغییر رکورد نهایی هر محصول از فیلتر زیر استفاده می‌شود:

aio_wc_product_feed_item

این فیلتر آرایه داده و شیء WC_Product را دریافت می‌کند. می‌توانید با آن:

• برند را از Taxonomy اختصاصی بخوانید؛
• بارکد را از کلید سفارشی منتقل کنید؛
• فیلد جدیدی اضافه کنید؛
• نام یک فیلد را متناسب با ساختار داده موردنیاز فروشگاه اصلاح کنید؛
• اطلاعات نامناسب را از خروجی حذف کنید.

برای عنوان دوم نیز فیلتر زیر موجود است:

aio_wc_product_feed_subtitle

کد سفارشی را داخل فایل‌های اصلی جم پک قرار ندهید؛ چون با بروزرسانی افزونه از بین می‌رود. آن را در افزونه اختصاصی سایت یا محل امن مدیریت اسنیپت‌ها نگه دارید و ابتدا در محیط آزمایشی بررسی کنید.

امنیت فید

برای محافظت از کاتالوگ، چند لایه کنترل وجود دارد:

• اجبار HTTPS؛
• الزام دسترسی Pro؛
• الزام روشن‌بودن سوییچ؛
• الزام کلید غیرخالی؛
• مقایسه امن کلید درخواست با کلید ذخیره‌شده؛
• محدودیت تعداد درخواست برای هر IP؛
• سقف اندازه صفحه و تعداد محصولات انتخابی؛
• پاسخ ۴۰۴ هنگام خاموش‌بودن فید برای آشکارنکردن وضعیت قابلیت.

فید اطلاعات مشتری، سفارش یا رمزهای فروشگاه را ارسال نمی‌کند، اما کاتالوگ کامل منتشرشده برای کسب‌وکار ارزشمند است. کلید باید مانند رمز سرویس نگهداری شود.

اگر کلید افشا شد:

1. کلید جدید و تصادفی بسازید.
2. آن را در تنظیمات ذخیره کنید.
3. کلید جدید را از مسیر امن به Searchwise بدهید.
4. کلید قدیمی را از مستندات، تیکت‌ها و ابزارهای مانیتورینگ حذف کنید.
5. لاگ درخواست‌های مشکوک را بررسی کنید.

با ذخیره کلید جدید، درخواست‌های دارای کلید قبلی دیگر پذیرفته نمی‌شوند.

محدودیت تعداد درخواست

در نسخه بررسی‌شده، هر IP می‌تواند حداکثر ۱۲۰ درخواست در یک بازه ۱۰ دقیقه‌ای ارسال کند. پس از عبور از این سقف، پاسخ 429 Too Many Requests بازگردانده می‌شود.

با اندازه پیش‌فرض ۱۰۰ محصول، این محدودیت امکان خزش کاتالوگ بزرگی را فراهم می‌کند. بااین‌حال، سرویس نباید صفحه‌های یکسان را در حلقه کوتاه و غیرضروری درخواست کند.

اگر چند خزنده پشت یک IP مشترک قرار دارند یا فایروال همه درخواست‌ها را با IP یکسان به وردپرس می‌رساند، احتمال رسیدن به سقف بیشتر می‌شود. تنظیم Reverse Proxy و تشخیص IP واقعی را بررسی کنید.

IPهای خزنده Searchwise

این IPها در صفحه تنظیمات برای Allowlist پیشنهاد می‌شوند:

185.206.93.115
185.206.94.25
37.152.176.176
188.121.106.231

این فهرست به‌صورت خودکار دسترسی را محدود نمی‌کند. کاربرد آن این است که اگر فایروال سرور، CDN یا افزونه امنیتی درخواست‌های ناشناس را مسدود می‌کند، بتوانید خزنده را مجاز کنید.

قبل از تغییر فایروال، IPهای جاری را با اطلاعات رسمی ارائه‌دهنده تطبیق دهید. IP ممکن است در نسخه‌های بعدی یا سمت سرویس تغییر کند.

معرفی فید به Searchwise

برای تحویل فید، معمولاً این اطلاعات لازم است:

• آدرس HTTPS فید؛
• متد GET یا POST مورد قبول؛
• نام هدر X-API-Key؛
• مقدار محرمانه کلید؛
• اندازه پیشنهادی صفحه؛
• واحد قیمت IRR؛
• IPهای موردنیاز برای Allowlist؛
• یک محصول نمونه برای کنترل نگاشت فیلدها.

کلید را در متن عمومی ایمیل یا گروه‌های گسترده ارسال نکنید. از کانال امن مورد توافق با ارائه‌دهنده استفاده کنید.

پس از ثبت فید، از تیم Searchwise بخواهید نتیجه این موارد را تأیید کند:

• دریافت موفق همه صفحه‌ها؛
• تشخیص قیمت عادی و فروش؛
• نمایش درست موجودی؛
• دسترسی به تصاویر؛
• نگاشت دسته، برند، GTIN، رنگ و سایز؛
• زمان‌بندی خزش بعدی؛
• نحوه گزارش خطاهای دریافت.

کارایی و کش

فید اطلاعات محصول را هنگام درخواست از ووکامرس می‌خواند. برای کاهش فشار:

• ابتدا با size=10 آزمایش کنید؛
• برای خزش عادی از اندازه ۱۰۰ شروع کنید؛
• فقط در صورت مناسب‌بودن منابع هاست تا ۲۰۰ افزایش دهید؛
• include_content را بدون نیاز فعال نکنید؛
• یک محصول مشکل‌دار را با products یا slugs دریافت کنید؛
• از درخواست مکرر صفحه یکسان خودداری کنید؛
• زمان پاسخ و مصرف حافظه را در فروشگاه بزرگ پایش کنید.

دسترسی به فید با کلید داخل هدر کنترل می‌شود. از مدیر فنی بخواهید مسیر فید را از کش عمومی خارج کند یا با تنظیم Vary مناسب، کش را به هدر احراز هویت وابسته کند. پاسخ یک درخواست مجاز نباید بدون بررسی کلید به دیگران تحویل داده شود.

کش تصویر با کش JSON فید متفاوت است و می‌تواند برای فایل‌های رسانه‌ای فعال باقی بماند.

غیرفعال‌کردن فید

برای توقف دسترسی:

1. وارد تنظیمات فید شوید.
2. سوییچ فعال‌سازی را خاموش کنید.
3. تنظیمات را ذخیره کنید.
4. آدرس را بدون تغییر کلید آزمایش کنید.

فید غیرفعال پاسخ ۴۰۴ می‌دهد. تنظیمات محصولات یا اطلاعات کاتالوگ حذف نمی‌شوند.

اگر توقف دائمی مدنظر است، کلید ذخیره‌شده را نیز پاک کنید. اگر فقط توقف موقت لازم است، خاموش‌کردن سوییچ کافی است و می‌توانید بعداً با همان کلید دوباره فعال کنید؛ اگر کلید مدت زیادی در اختیار دیگران بوده، بهتر است کلید تازه‌ای بسازید.

کدهای پاسخ مهم

کد HTTP	مفهوم احتمالی
200	درخواست موفق و پاسخ فید
400	پارامتر نامعتبر در مسیر REST
401	کلید ارسال نشده یا نادرست است
403	درخواست امن HTTPS تشخیص داده نشده است
404	فید خاموش، بدون کلید یا بدون مجوز Pro است
429	سقف درخواست IP در بازه زمانی پر شده است
500	ووکامرس یا وابستگی لازم در دسترس نیست

پاسخ ۴۰۴ عمداً میان «قابلیت غیرفعال» و «فید پیکربندی‌نشده» تفاوت آشکار ایجاد نمی‌کند.

چک‌لیست آزمایش پیش از تحویل

• سایت با HTTPS معتبر باز شود؛
• مجوز Pro فعال باشد؛
• سوییچ فید روشن و کلید حداقل ۳۲ کاراکتری ذخیره شده باشد؛
• درخواست بدون کلید رد شود؛
• درخواست با کلید اشتباه رد شود؛
• درخواست با کلید درست پاسخ ۲۰۰ بگیرد؛
• currency برابر IRR باشد؛
• قیمت محصول تومانی ده برابر و صحیح در فید دیده شود؛
• محصول عادی sale_price برابر صفر داشته باشد؛
• محصول فروش ویژه قیمت صحیح داشته باشد؛
• محصول ناموجود با وضعیت مناسب در خروجی باقی بماند؛
• محصول مخفی از کاتالوگ در خزش عمومی حذف شود؛
• صفحه‌بندی و max_pages درست باشد؛
• اندازه بیشتر از ۲۰۰ محدود شود؛
• دریافت با شناسه و Slug آزمایش شود؛
• محصول متغیر موجود و ناموجود بررسی شود؛
• تصویر شاخص و گالری از خارج سایت باز شوند؛
• مسیر دسته‌بندی صحیح باشد؛
• برند و GTIN محصولات نمونه تکمیل باشند؛
• رنگ و سایز از ویژگی‌های صحیح خوانده شوند؛
• include_content فقط در صورت نیاز آزمایش شود؛
• مسیر از کش عمومی خارج شده باشد؛
• فایروال IPهای تأییدشده خزنده را مسدود نکند؛
• کلید در تصویر، لاگ عمومی یا URL افشا نشود.

خطاهای رایج

آدرس فید پاسخ ۴۰۴ می‌دهد

• مجوز Pro را بررسی کنید.
• سوییچ فید باید فعال باشد.
• فیلد کلید نباید خالی باشد.
• تنظیمات را ذخیره و مسیر را دوباره آزمایش کنید.
• مطمئن شوید درخواست به سایت و محیط صحیح ارسال می‌شود.

وقتی فید غیرفعال است، پاسخ ۴۰۴ نمایش داده می‌شود تا وضعیت مسیر دسترسی آشکار نشود.

پاسخ ۴۰۱ دریافت می‌شود

• هدر X-API-Key را ارسال کنید.
• فاصله ابتدا یا انتهای کلید را بررسی کنید.
• کلید ذخیره‌شده و کلید سرویس باید کاملاً یکسان باشند.
• کلید را داخل Query String نفرستید.
• بررسی کنید CDN یا Proxy هدر سفارشی را حذف نمی‌کند.

پاسخ ۴۰۳ و خطای HTTPS دیده می‌شود

• URL باید با https:// آغاز شود.
• گواهی SSL و زنجیره آن را بررسی کنید.
• اگر TLS روی Proxy خاتمه می‌یابد، هدر X-Forwarded-Proto: https باید درست به وردپرس برسد.
• تنظیمات آدرس وردپرس و سایت را بررسی کنید.

پاسخ ۴۲۹ دریافت می‌شود

• تعداد درخواست‌ها از همان IP را کاهش دهید.
• تا پایان بازه ۱۰ دقیقه‌ای صبر کنید.
• صفحه‌های تکراری را دوباره درخواست نکنید.
• اندازه صفحه را افزایش دهید، مشروط به تحمل سرور.
• تشخیص IP واقعی پشت Proxy یا CDN را بررسی کنید.

بعضی محصولات در فید نیستند

• وضعیت محصول باید منتشرشده باشد.
• Product Visibility را بررسی کنید.
• محصول مخفی از کاتالوگ در خزش اصلی حذف می‌شود.
• صفحه و اندازه صفحه را کنترل کنید.
• محصول را با products=ID یا slugs=slug جداگانه آزمایش کنید.
• افزونه‌ای را که Query محصولات یا وضعیت دیده‌شدن را تغییر می‌دهد بررسی کنید.

محصول ناموجود هنوز در فید است

این رفتار صحیح است. فید محصول ناموجود را با availability: out of stock نگه می‌دارد تا سرویس بتواند وضعیت آن را بروزرسانی کند.

قیمت ده برابر یا یک‌دهم مقدار درست است

• واحد پول ووکامرس را بررسی کنید.
• خروجی همیشه با واحد IRR اعلام می‌شود.
• مبلغ فروشگاه تومانی باید در خروجی ده برابر شود.
• افزونه واحد پول ممکن است کد سفارشی ناشناخته‌ای ثبت کرده باشد.
• سه محصول را با قیمت ساده و فروش ویژه به‌صورت دستی مقایسه کنید.

اگر کد واحد پول توسط فید شناخته نشود، تبدیل مناسب انجام نمی‌شود و به نگاشت سفارشی یا اصلاح تنظیمات نیاز دارید.

قیمت محصول متغیر مطابق ارزان‌ترین Variation موجود نیست

فید نخستین Variation موجود را بر اساس ترتیب داخلی محصول انتخاب می‌کند، نه لزوماً ارزان‌ترین مورد موجود. ترتیب Variationها یا خروجی سفارشی را بررسی کنید.

اگر هیچ Variation موجود نباشد، کمترین قیمت Variationها به‌عنوان مقدار جایگزین استفاده می‌شود.

تصویر محصول باز نمی‌شود

• تصویر شاخص و گالری را در کتابخانه رسانه بررسی کنید.
• URL تصویر باید عمومی و HTTPS باشد.
• Hotlink Protection، CDN و فایروال را بررسی کنید.
• دسترسی IP خزنده به فایل‌های رسانه‌ای را آزمایش کنید.
• از حذف‌نشدن فایل اصلی تصویر مطمئن شوید.

برند، GTIN، رنگ یا سایز خالی است

• منبع برند و نام Taxonomy را بررسی کنید.
• بارکد باید در فیلد بومی ووکامرس یا یکی از کلیدهای شناخته‌شده باشد.
• نام ویژگی رنگ و سایز را با نام‌های پشتیبانی‌شده مقایسه کنید.
• برای ساختار اختصاصی از فیلتر aio_wc_product_feed_item استفاده کنید.

پاسخ بسیار سنگین یا کند است

• اندازه صفحه را کاهش دهید.
• include_content را خاموش کنید.
• محصول مشخص را با شناسه آزمایش کنید.
• افزونه‌های سنگین روی بارگذاری محصول را بررسی کنید.
• Object Cache، دیتابیس و منابع PHP را پایش کنید.
• تصاویر به‌صورت URL ارسال می‌شوند؛ کندی فایل تصویر را جدا از JSON بررسی کنید.

Searchwise خطا دارد اما آزمایش محلی موفق است

• IPهای جاری خزنده را Allowlist کنید.
• هدر کلید را با تیم سرویس تأیید کنید.
• لاگ فایروال، CDN و وب‌سرور را در زمان درخواست بررسی کنید.
• محدودیت ۱۲۰ درخواست در ۱۰ دقیقه را در نظر بگیرید.
• SSL و دسترسی عمومی DNS را از بیرون شبکه آزمایش کنید.
• از سرویس بخواهید کد HTTP و بدنه خطای واقعی را ارائه دهد.

آموزش‌های مرتبط

• راه‌اندازی قوانین سبد خرید ووکامرس
• راه‌اندازی روش‌های حمل‌ونقل ایرانی ووکامرس
• پرداخت اقساطی اسنپ‌پی ووکامرس
• آشنایی با محیط جم پک و مدیریت ماژول‌ها