ویترین روی کد خودتان (headless)
مسیر معمول، ویترین ما یا ویجت‌ها در سایت شما است. اما اگر سایت را توسعه‌دهنده یا آژانس شما می‌نویسد و قالب باید کاملاً اختصاصی باشد، گزینه سوم کار می‌کند: شما داده‌ها و دریافت سفارش را از ما می‌گیرید و کل فرانت‌اند را خودتان، با هر استکی، می‌سازید.
خواندن داده‌ها به کلید و احراز هویت نیاز ندارد: هر چیزی که در ویترین عمومی است، در JSON هم عمومی است.
محل تنظیم: بازاریابی → «سایت من» → کارت «ویترین روی کد خودتان». همان‌جا نشانی مانیفست شعبه شما، پیوندهای مستندات فنی و JSON-سکیماها و تنظیم وب‌هوک‌ها قرار دارد. نیازی به فعال کردن چیزی نیست: داده‌ها همیشه منتشر می‌شوند.
مانیفست storefront.json#
تنها نشانی‌ای که توسعه‌دهنده باید بداند:
https://cdn.cenaly.com/{ДОМЕН}/storefront.json
بقیه چیزها در مانیفست است:
| بخش | محتوا |
|---|---|
location |
شناسه، اسلاگ، ورتیکال (رستوران، فروشگاه، هتل، سالن) |
languages |
زبان پیش‌فرض و فهرست زبان‌های فعال |
currency |
کد و نماد ارز |
cdnBase + data |
مسیرهای منو، پروفایل، صفحه‌ها، مجموعه‌ها، نظرات و پیشنهادهای «با این خریداری می‌شود» |
catalog |
حالت کاتالوگ: همه‌چیز در فایل‌ها یا کارت‌های فایل‌به‌فایل و API کاتالوگ |
images |
پایه تصاویر، قالب‌های مسیر (عکس مورد و گالری، ویدیو، دسته‌ها، مجموعه‌ها، کاور و لوگو، favicon) و اندازه‌های موجود |
api |
نشانی‌های API مهمان، مشخصات OpenAPI، محیط تجاری، MCP-اندپوینت و WebSocket وضعیت‌های زنده سفارش |
publishId، publishedAt |
شناسه انتشار: با هر بازتولید داده‌ها تغییر می‌کند |
قرارداد نسخه‌بندی می‌شود (contractVersion) و در کنارش JSON-سکیماها قرار دارند — با آن‌ها می‌توان داده‌ها را اعتبارسنجی و تایپ‌ها را تولید کرد. فیلدهای ناشناخته را باید نادیده گرفت: قرارداد بدون شکستن سازگاری گسترش می‌یابد.
داده‌ها و تصاویر#
هر چیزی که ویترین نشان می‌دهد به‌صورت فایل در دسترس است: منو و کاتالوگ به تفکیک زبان، پروفایل شعبه (نام، نشانی، ساعات کاری، تماس‌ها، تنظیمات)، صفحه‌ها و مقاله‌ها، مجموعه‌ها، نظرات.
برای کاتالوگ‌های بزرگ، مانیفست به حالت api سوئیچ می‌کند: در فایل منو یک نمونه سبک قرار دارد و کارت‌های کامل فایل‌به‌فایل یا از طریق API کاتالوگ با فیلترها و زیردسته‌ها گرفته می‌شوند.
تصاویر از CDN ما، در چند اندازه بر اساس قالب مانیفست هستند؛ هنگام به‌روزرسانی عکس، مسیر نسخه‌بندی می‌شود، بنابراین کش را می‌توان «برای همیشه» نگه داشت.
نوشتن همه این درخواست‌ها با دست الزامی نیست: بسته npm با نام @cenaly/storefront وجود دارد — کلاینت تایپ‌دار قرارداد (مانیفست، پروفایل، منوی هر دو حالت کاتالوگ، ثبت سفارش)، سازنده URL تصاویر و React-هوک‌ها. این بسته یک نقطه ورود جداگانه برای بیلدهای استاتیک دارد (@cenaly/storefront/static: نقشه نشانی‌های سایت، sitemap.xml، robots.txt، پیوندهای تصاویر) و یک فرمان کنسولی cenaly-storefront — اسنپ‌شات همه داده‌های شعبه در یک پوشه، فهرست نشانی‌ها و حالت watch که مانیفست را رصد می‌کند و به‌محض تغییر publishId بیلد شما را اجرا می‌کند. همین بسته پایه پروژه شروع با Next.js است که می‌توانید کلون کنید و فقط رنگ‌هایش را عوض کنید.
سفارش‌ها و API مهمان#
دریافت سفارش، وضعیت سفارش، جستجو و رزرو — از طریق API مهمان: بدون احراز هویت، نشانی از مانیفست گرفته می‌شود، مشخصات — OpenAPI 3.1. جداگانه یک محیط تجاری وجود دارد: کوپن‌ها، محاسبه ارسال، فرم‌ها، اشتراک‌ها. جزئیات بیشتر — Guest API برای AI-ایجنت‌ها، همان رابط.
سفارشی که سایت شما ایجاد می‌کند در بخش مشترک «سفارش‌ها» قرار می‌گیرد و طبق قواعد معمول پیش می‌رود: وضعیت‌ها، آشپزخانه، پیک‌ها، رسیدها، اعلان‌ها.
وب‌هوک‌های تغییرات#
برای اینکه CDN را نظرسنجی نکنید، روی رویدادها مشترک شوید:
menu.updated— منو یا کاتالوگ بازتولید شده است؛profile.updated— پروفایل شعبه تغییر کرده است؛pages.updated— صفحه‌ها و مقاله‌ها تغییر کرده‌اند.
در بدنه رویداد publishId می‌آید — با آن می‌توان صفحه‌های استاتیک را بازسازی یا کش ISR را پاک کرد. اگر رمز تعیین کرده باشید، درخواست با HMAC-SHA256 امضا می‌شود و با هدر X-Meni-Signature می‌آید — پیش از هر بازسازی، امضا را بررسی کنید؛ برای deploy-هوک Vercel/Netlify نیازی به تعیین رمز نیست. حداکثر پنج نشانی برای هر شعبه، و پس از ده شکست پیاپی اشتراک خودبه‌خود غیرفعال می‌شود (در حساب، آخرین تحویل و شمارنده خطاها دیده می‌شود؛ ذخیره دوباره تنظیمات آن را دوباره فعال می‌کند).
سرور چه نشانی‌ای را می‌پذیرد. فقط https://، بدون نام کاربری و رمز در خود URL، و هاست باید عمومی باشد: نشانی‌های محلی، داخلی و سرویسی (localhost، 10.0.0.0/8، 192.168.0.0/16، 172.16.0.0/12، 100.64.0.0/10، 169.254.169.254) هنگام ذخیره رد می‌شوند. برای دیباگ روی دستگاه خودتان، یک تونل با نشانی https عمومی راه بیندازید.
چه زمانی تکرار رخ می‌دهد. تایم‌اوت‌ها و پاسخ‌های 5xx، 408، 429 تکرار می‌شوند — یعنی چیزهایی که شبیه خطای موقت هستند. هر پاسخ 4xx دیگری خطای دائمی شمرده می‌شود: تکراری نخواهد بود و تلاش بلافاصله در شمارنده شکست‌ها ثبت می‌شود.
وب‌هوک‌ها در کارت «ویترین روی کد خودتان» تنظیم می‌شوند و در طرح‌های پولی در دسترس هستند؛ خواندن داده‌ها همیشه در دسترس است.
از کجا شروع کنید#
- بازاریابی → «سایت من» → «ویترین روی کد خودتان» را باز کنید و نشانی مانیفست را کپی کنید.
- مانیفست را بارگیری کنید و از آن — داده‌های منو و پروفایل را (یا بسته
@cenaly/storefrontرا نصب کنید و اسلاگ شعبه را به آن بدهید). در این مرحله هیچ کلیدی لازم نیست. - صفحه‌ها را با فریم‌ورک خودتان بسازید؛ برای سفارش‌ها از API مهمان استفاده کنید.
- یک وب‌هوک اضافه کنید تا سایت را بر اساس تغییرات بازسازی کنید — یا اگر نشانی عمومی برای دریافت رویدادها ندارید،
cenaly-storefront watchرا اجرا کنید: خودشpublishIdرا در مانیفست رصد می‌کند و بیلد شما را اجرا می‌کند.
توصیف فنی کامل — از پیوند «مستندات توسعه‌دهنده» در همان کارت؛ در کنارش پیوندهایی به راهنمای جداگانه سایت استاتیک و به JSON-سکیماها. یک پروژه شروع آماده با Next.js وجود دارد و کل مستندات به‌صورت llms.txt برای دستیارهای هوش مصنوعی توسعه‌دهنده هم تکرار می‌شود — از جمله llms.txt شخصی شعبه شما روی CDN.
بخش‌های مرتبط#
- سایت من — ویجت‌ها، اگر نیازی به بازنویسی کامل سایت نیست
- Guest API برای AI-عامل‌ها — همان API مهمان
- API و MCP مرکز تلفن شما — دسترسی عامل‌های هوش مصنوعی و CRM به تلفن
- فروشگاه اینترنتی — اینکه دقیقاً چه چیزی در داده‌های کاتالوگ می‌آید
پرسش‌های پرتکرار#
آیا خواندن داده‌ها هزینه دارد؟ نه. JSONهای عمومی در هر طرحی در دسترس هستند — همان فایل‌هایی که ویترین ما از آن‌ها استفاده می‌کند. هزینه‌بر بودن مربوط به وب‌هوک‌ها است.
وضعیت SEO چگونه است؟ کاملاً بر عهده شماست: خودتان صفحه‌ها را می‌سازید و خودتان نشانه‌گذاری را مدیریت می‌کنید. داده‌های نشانه‌گذاری خرد (JSON-LD) در قرارداد وجود دارد.
آیا می‌توان آن را با ویترین خودتان ترکیب کرد؟ بله. ویترین ما، ویجت‌ها و سایت خودتان با داده‌های یکسان و یک سبد سفارش کار می‌کنند.