فروش هاستینگ Zinn® از طریق WHMCS

ماژول Zinn Digital® دکمه‌های WHMCS را به عملکردهای واقعی روی پلتفرم ما تبدیل می‌کند. یک سفارش، هاست مشتری شما را پروویژن (راه‌اندازی) می‌کند. اتوماسیون فاکتور معوق WHMCS آن را معلق می‌کند. علامت‌گذاری فاکتور به عنوان پرداخت‌شده، آن را آزاد می‌کند. لغو کردن، زمان‌بندی حذف را تعیین می‌کند. و مشتری شما یک دکمه ورود به پنل هاست در ناحیه کاربری خود دریافت می‌کند که مستقیماً او را وارد سیستم می‌کند.

این ماژول رایگان است، تحت مجوز GPL-2.0-or-later ارائه شده است و هیچ مسیر ممتازی به پلتفرم ما ندارد: هر فراخوانی که انجام می‌دهد یک نقطه پایانی مستندشده است که خودتان نیز می‌توانید با کلید API خودتان آن را انجام دهید.

پیش از شروع

به دو چیز نیاز دارید، و مورد دوم معمولاً باعث غافلگیری افراد می‌شود.

1. یک حساب نمایندگی (Reseller) در Zinn® با یک برنامه فعال. در zinndigital.com ثبت‌نام کنید و نمایندگی فروش را فعال کنید.
2. یک پلن نمایندگی با ظرفیت سایت. سایت‌هایی که مشتریانتان سفارش می‌دهند از پلن شما کسر می‌شوند، بنابراین به پلنی نیاز دارید که فضای کافی داشته باشد.

⚠️ تست اتصال نمی‌تواند به شما بگوید که آیا یک سفارش موفق خواهد بود یا خیر. این ابزار برنامه شما را می‌خواند و چیزی را پروویژن نمی‌کند، بنابراین گزارش یک حساب active (فعال) سالم را می‌دهد که هنوز نمی‌تواند چیزی بفروشد. اگر اولین سفارش شما با خطای "این سازمان هیچ پلن هاستی ندارد، بنابراین هنوز نمی‌تواند سایتی را میزبانی کند" با شکست مواجه شد، دقیقاً همین اتفاق افتاده است — پلن نمایندگی خود را خریداری یا تمدید کنید و سفارش را دوباره ثبت کنید. هیچ مشکلی در ماژول وجود ندارد.

۱. ایجاد کلید API

در داشبورد Zinn® خود، بخش API keys را باز کنید و یک کلید با دقیقاً این یازده دسترسی ایجاد کنید:

| دسترسی | دلیل نیاز به آن | | -------------------- | ----------------------------------------------------------- | | org.create | باز کردن حساب Zinn® مشتری در اولین سفارش او. | | org.read | خواندن حساب‌های مشتریان. | | sites.create | پروویژن کردن سایت. | | sites.view | خواندن یک سرویس و میزان مصرف آن. | | sites.delete | خاتمه دادن. | | reseller.view | فهرست کردن آنچه فروخته‌اید، و خواندن دیسک و پهنای باند. | | reseller.provision | تعلیق، آزادی، ورود مشتری به سیستم، تنظیم پلن و تغییر پکیج او. | | billing.view | خواندن هزینه ارتقا قبل از اجرای آن. | | sites.manage | پاکسازی کش و تهیه نسخه پشتیبان از طریق دکمه‌ها. | | sites.panel_access | تغییر رمز عبور مدیر WordPress. | | hosting.php.manage | تعویض نسخه PHP هنگام ارتقا یا تنزل. |

⛔ دسترسی reseller.manage را اعطا نکنید. کلیدی که در پنل صورت‌حساب جای‌گذاری می‌شود باید بتواند به دلیل عدم پرداخت، خدمات مشتری را متوقف کرده و او را وارد سیستم کند. این کلید نباید بتواند اعتبارنامه‌های درگاه پرداخت خود شما را بخواند و بازنویسی کند. دسترسی reseller.provision وجود دارد تا مجبور نباشید دسترسی بزرگ‌تر را اعطا کنید. ⛔ دسترسی org.create اختیاری نیست. بدون آن، ماژول می‌تواند حساب‌های شما را بخواند اما نمی‌تواند حسابی را باز کند، بنابراین تست اتصال موفق می‌شود اما اولین سفارش پاسخ 403 را برمی‌گرداند. ⛔⛔ کل جدول دسترسی‌ها را اعطا کنید، و توجه داشته باشید که تست اتصال نمی‌تواند به شما بگوید اگر این کار را نکرده‌اید. این ابزار برنامه نمایندگی شما را می‌خواند و چیزی را پروویژن نمی‌کند، بنابراین برای کلیدی که هر یک از این موارد را کم دارد نیز سبز می‌شود. در عوض، آنچه ماه بعد از طرف یک مشتری دریافت خواهید کرد، خطای 403 در همان عملیاتی است که دسترسی گم‌شده پوشش می‌دهد.

۲. نصب ماژول

1. ماژول را دانلود کرده و از حالت فشرده خارج کنید.
2. دایرکتوری zinn را در نصب WHMCS خود آپلود کنید تا فایل ماژول در مسیر modules/servers/zinn/zinn.php قرار گیرد.

⛔ نام دایرکتوری باید دقیقاً zinn باشد. WHMCS نام عملکردهای یک ماژول پروویژنینگ را از نام دایرکتوری آن مشتق می‌کند، بنابراین تغییر نام آن به zinn-whmcs یا zinndigital ماژولی ایجاد می‌کند که WHMCS آن را فهرست می‌کند، به شما اجازه انتخاب می‌دهد، اما هرگز آن را فراخوانی نمی‌کند — بدون هیچ‌گونه خطایی در هیچ‌جا. فایل فشرده از قبل با نام درست استخراج می‌شود؛ فقط نام آن را تغییر ندهید.

۳. افزودن سرور

در WHMCS: مسیر Configuration → System Settings → Servers → Add New Server.

• نام (Name): هر چیزی، مثلاً Zinn Digital®
• نام میزبان (Hostname): api.zinndigital.com
• نوع (Type): Zinn Digital®
• رمز عبور (Password): کلید API شما از مرحله ۱

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

روی Test Connection (تست اتصال) کلیک کنید. این دکمه یک فراخوانی واقعی انجام می‌دهد و گزارش می‌دهد که پلتفرم ما چه پاسخی داده است، به‌جای اینکه صرفاً بررسی کند که آیا فیلدها پر شده‌اند یا خیر.

۴. ایجاد محصول

مسیر Configuration → System Settings → Products/Services، سپس Module Settings را روی سروری که تازه اضافه کرده‌اید تنظیم کنید. فیلدها عبارتند از:

| فیلد | الزامی | چیست | | ---------------- | -------- | -------------------------------------------------------------------------- | | Product line | بله | خطوط Zinn® که می‌فروشید — mainstream (وردپرس مدیریت‌شده)، footprint_free، wordpress، linux، cloud، agency، app_hosting، ai_hosting، lms_hosting، managed_database، vector_hosting، zinn_compute، fleet_linux، fleet_enterprise، mail یا reseller. | | Stack | بله | آنچه ساخته می‌شود: wordpress (پیش‌فرض)، woocommerce، php، static، node، one_click، headless_cms، nextcloud یا owncloud. | | Application | خیر | فقط برای استک‌های one_click و headless_cms — اینکه کدام برنامه نصب شود. نام بردن از یک برنامه روی هر استک دیگری رد می‌شود، زیرا آن استک از قبل تصمیم می‌گیرد چه چیزی نصب شود. | | PHP version | خیر | مثلاً 8.3. برای استفاده از نسخه پیش‌فرض خط تولید، آن را خالی بگذارید. نسخه‌ای که خط تولید ارائه نمی‌دهد با فهرستی از نسخه‌های موجود رد می‌شود. | | Plan code | بله | پلن Zinn® که این محصول می‌فروشد. دستور GET /v1/reseller/prices موارد شما را فهرست می‌کند. سفارش بدون آن رد می‌شود — هشدار زیر را ببینید. | | Billing interval | خیر | monthly (پیش‌فرض) یا annual — بازه‌ای که خط عمده‌فروشی شما برای این مشتری بر اساس آن صادر می‌شود. مبلغی که از مشتری خودتان دریافت می‌کنید در محصول WHMCS تنظیم می‌شود و تحت تأثیر قرار نمی‌گیرد. |

⛔⛔ کد پلن الزامی است و سفارش بدون آن به طور عمدا رد می‌شود. تا تاریخ 2026-09-01 این فیلد تزئینی بود و هیچ‌کس آن را نمی‌خواند، بنابراین ماژول هاستی را سفارش می‌داد که هیچ پلنی نداشت — و تمام پیامدهای آن بی‌صدا بود. صورت‌حساب عمده‌فروشی شما از اشتراک‌های فعال مشتریانتان ساخته می‌شود، بنابراین هیچ ردیفی برای سرویس وجود نداشت و تا زمانی که اجرا می‌شد، هیچ صورت‌حصالی برای شما صادر نمی‌شد؛ مشتری شما هیچ سهمیه‌ای به ارث نمی‌برد، بنابراین هیچ سهمیه دیسک یا فایلی روی سایت او اعمال نمی‌شد؛ و تغییر پکیج (Change Package) چیزی برای تغییر نداشت، بنابراین ارتقایی که فروخته بودید قابل اجرا نبود. سایت در تمام مدت به طور عالی پروویژن شده و سرویس‌دهی می‌کرد.

ماژول اکنون به‌جای آن، سفارش را رد می‌کند، زیرا هیچ پلن امنی برای حدس زدن وجود ندارد: حدس زدن باعث پروویژن هاست روی پلنی می‌شود که شما انتخاب نکرده‌اید و ممکن است برای آن قیمتی تعیین نکرده باشید، و برخلاف رد شدن (که بلافاصله متوجه آن می‌شوید) این مورد فقط زمانی ظاهر می‌شود که صورت‌حساب می‌رسد، آن هم اگر برسد.

گزینه Auto Setup را روی هرکدام که ترجیح می‌دهید تنظیم کنید — ماژول روی شناسه سرویس WHMCS ایزمپوتنت (Idempotent) است، بنابراین پروویژن مجدد، به‌جای صورت‌حساب برای دومین سایت، همان سایت قبلی را برمی‌گرداند.

عملکرد هر یک از اقدامات WHMCS

| اقدام WHMCS | آنچه در سمت ما رخ می‌دهد | | --------------------------- | ---------------------------------------------------------------------------------------- | | Create | حساب Zinn® مشتری را ایجاد می‌کند (یا از حساب موجود استفاده مجدد می‌کند) و سایت او را پروویژن می‌کند. | | Suspend | سایت را در وضعیت تعلیق به دلیل عدم پرداخت قرار می‌دهد. محتوا حفظ می‌شود؛ هیچ‌چیز حذف نمی‌شود. | | Unsuspend | تعلیق اعمال‌شده توسط شما را لغو می‌کند. | | Terminate | زمان‌بندی حذف سایت را با یک دوره مهلت انجام می‌دهد. تاریخ در ناحیه کاربری نمایش داده می‌شود. | | Usage update | مصرف دیسک و پهنای باند را در هر سرویس، یک بار در روز به‌روزرسانی می‌کند. | | Log in to hosting panel | یک لینک ورود یک‌بارمصرف مستقیماً به پنل مشتری شما باز می‌کند. | | Change Package | سرویس را ارتقا یا تنزل می‌دهد. پکیج و همچنین نسخه PHP را (در صورتی که محصول جدید مشخص کرده باشد) جابه‌جا می‌کند. | | Change Password | رمز عبور مدیر WordPress را تنظیم می‌کند. این کادر روی استک‌هایی که چنین حسابی ندارند ظاهر نمی‌شود. | | Renew | تأیید می‌کند که سرویس همچنان وجود دارد. هاستینگ Zinn® پیوسته است، بنابراین هیچ مدت‌زمان راهوری برای تمدید وجود ندارد. | | Sync Usage / Purge Cache / Take Backup | دکمه‌های صفحه مدیریت سرویس. مشتری شما گزینه‌های Purge Cache و Take Backup را در ناحیه کاربری خود دریافت می‌کند. | | Service tab | وضعیت، پلن، دیسک، پهنای باند، هرگونه حذف زمان‌بندی‌شده، و اینکه چه کسی تعلیق را انجام داده است. | | Import | دستور ListAccounts تمام صفحات را می‌خواند، بنابراین وارد کردن (Import) نمی‌تواند به طور خودکار در اولین صفحه متوقف شود. |

ارتقاها: چه کسی از چه کسی هزینه دریافت می‌کند

مشتری شما هرگز توسط Zinn®، چه در سفارش و چه در ارتقا، فاکتور نمی‌شود. شما از طریق WHMCS برای آن‌ها فاکتور صادر می‌کنید؛ ما روی صورت‌حساب عمده‌فروشی شما، برای شما فاکتور صادر می‌کنیم. بنابراین، تغییر پکیج (Change Package) حقوق مشتری شما و ردیف صورت‌حساب بعدی شما را تغییر می‌دهد و به هیچ کارتی دست نمی‌زند — WHMCS از قبل پول مشتری شما را دریافت کرده و تناسب زمانی (Proration) خود را محاسبه کرده است.

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

تغییر رمز عبور فقط برای WordPress وجود دارد. هاستینگ Zinn® هیچ «رمز عبور سرویس» واحدی ندارد — مشتری شما با دکمه ورود به سیستم به پنل خود می‌رسد — و یک سایت php یا static هیچ حساب برنامه‌ای برای تغییر ندارد. WHMCS به‌جای نمایش کادری که نمی‌تواند کار کند، آن را به طور کامل پنهان می‌کند.

سه پاسخی که نباید به دو پاسخ تبدیل کنید

• Unsuspend می‌تواند با رد درخواست پاسخ دهد. این بدان معناست که سایت توسط تیم سوءاستفاده ما معلق شده است، نه توسط شما، و هیچ پنل صورت‌حسابی نمی‌تواند آن را آزاد کند. پیام دقیقاً همین را می‌گوید؛ به‌جای تلاش مجدد، آن را به مدیر خود نشان دهید.
• Terminate زمان‌بندی حذف را انجام می‌دهد، نه خود حذف را. تاریخ به صورت pending_deletion_at برگردانده می‌شود و ناحیه کاربری آن را نشان می‌دهد. اینکه به مشتری بگویید داده‌هایشان از بین رفته در حالی که نرفته است، بدتر از این است که چیزی به آن‌ها نگویید.
• دیسک و پهنای باند می‌توانند ناشناخته باشند، و ناشناخته به معنای صفر نیست. زمانی که نتوانسته‌ایم مقداری را بخوانیم، ماژول به‌جای نوشتن 0 مقدار را دست‌نخورده رها می‌کند — در غیر این صورت WHMCS نوار مصرف خالی و آرامش‌بخشی را برای سایتی که هیچ خوانشی از آن نداریم به مشتری شما نشان می‌دهد.

عیب‌یابی

تست اتصال موفق است و اولین سفارش با خطای دسترسی شکست می‌خورد. کلید API فاقد دسترسی org.create است. ماژول باید قبل از اینکه بتواند سایت مشتری را ایجاد کند، حساب او را باز کند.

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

یک سفارش با ذکر یک استک شکست می‌خورد. فیلد Stack روی محصول خالی است یا نامی از چیزی که ما می‌سازیم ندارد. مگر اینکه چیز دیگری بفروشید، آن را روی wordpress تنظیم کنید.

لغو سفارش‌ها با شکست مواجه می‌شوند. مطمئن شوید که از نسخه ماژول 1.0.0 یا بالاتر استفاده می‌کنید. نسخه‌های قبلی هیچ تأییدیه حذفی ارسال نمی‌کردند و هر پایانی رد می‌شد، که باعث می‌شد سرویس همچنان فعال بماند و برای آن صورت‌حساب صادر شود.

رد درخواستی که نام یک فیلد را ذکر می‌کند. خطاهای اعتبارسنجی ما نام فیلد و دلیل آن را داخل پرانتز بعد از پیام ذکر می‌کنند، به عنوان مثال (php_version: 7.2 is not offered on this product line). این نیمه قابل اقدام است — جمله قبل از آن عمدتاً عمومی است.

تأیید دانلود خود

هر آرشیو از طریق TLS از نام میزبان خود ما ارائه می‌شود و هرگز به یک میزبان شخص ثالث هدایت نمی‌شود. مقدار چک‌سام SHA-256 آن در کنار لینک دانلود در صفحه دانلودها چاپ شده است. پس از دانلود آن را مقایسه کنید:

• سیستم‌عامل مک یا لینوکس: shasum -a 256 zinn-whmcs-1.0.0.zip
• ویندوز: certutil -hashfile zinn-whmcs-1.0.0.zip SHA256

از WHMCS استفاده نمی‌کنید؟

یک ماژول HostBill و یک کلاینت PHP تک‌فایلی برای هر چیز دیگری وجود دارد که هر دو رایگان هستند و در همان صفحه دانلودها قرار دارند. هر نقطه پایانی که ماژول‌ها استفاده می‌کنند در مرجع API موجود است.