فروش هاستینگ Zinn® از سیستم‌های خودتان

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

مشتریانتان در واقع چه چیزی می‌بینند

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

| رابط کاربری | متعلق به چه کسی است | |---|---| | پنل هاستینگ، با نام میزبان خودتان | یک نام میزبان برای پنل در بخش فروش مجدد ← برند شما تنظیم کنید و مشتریانتان با لوگو و رنگ‌های شما در panel.yourcompany.com وارد می‌شوند. همان پنل، آدرس شما. | | سایت خودتان | افزونه WordPress جستجوی دامنه و لینک ورود با یک کلیک را روی سایت شما قرار می‌دهد و سفارش را از طریق تسویه حساب WooCommerce خودتان دریافت می‌کند. | | پنل صورت‌حساب شما | WHMCS یا HostBill به عنوان درگاه ورودی باقی می‌ماند؛ ماژول در پشت صحنه سرویس را راه‌اندازی می‌کند و دکمه ناحیه کاربری آن‌ها را مستقیماً وارد هاستینگشان می‌کند. |

⛔ هر کدام را که انتخاب کنید، شما شخص مسئول فروش (merchant of record) در برابر مشتریانتان هستید: قیمت‌های شما، فاکتورهای شما، شماره مالیات بر ارزش افزوده شما، درگاه پرداخت شما. ما ماهانه یک بار به قیمت عمده‌فروشی از شما صورت‌حساب می‌گیریم.

هنگامی که نام میزبان پنل را تنظیم کردید، آن را فقط در فیلد آدرس پنل در افزونه WordPress وارد کنید و جای دیگری نگذارید — لینک‌های ورودی که این API تولید می‌کند به طور خودکار از آن پیروی می‌کنند.

چهار راه ورود

چهار راه برای ورود وجود دارد و همه آن‌ها در زیر کاپ کار مشابهی را انجام می‌دهند:

| | برای | |---|---| | ماژول WHMCS | یک فروشگاه WHMCS | | ماژول HostBill | یک فروشگاه HostBill | | افزونه WordPress | فروش از سایت WordPress یا WooCommerce خودتان | | API | هر چیز دیگری — Blesta، یک سیستم داخلی، یک اسکریپت cron |

۱. دریافت کلید API

در داشبورد خود، به کلیدهای API بروید و یکی بسازید. فقط دسترسی‌های مورد نیاز را به آن بدهید:

| دسترسی | چرا | |---|---| | org.read | خواندن حساب‌های مشتریان شما | | sites.create | راه‌اندازی یک سایت | | sites.view | خواندن یک سرویس | | sites.delete | خاتمه دادن | | reseller.view | فهرست کردن سرویس‌ها و خواندن میزان مصرف | | reseller.provision | معلق کردن، آزاد کردن و وارد کردن مشتری به سیستم |

⛔ به هیچ یک از یکپارچه‌سازی‌ها دسترسی reseller.manage را ندهید. این دسترسی لیست قیمت شما و اطلاعات ورود درگاه پرداخت خودتان را ویرایش می‌کند. دسترسی reseller.provision دقیقاً به این منظور وجود دارد که کلیدی که در پنل صورت‌حساب یا وب‌سایت جای‌گذاری می‌کنید نیازی به آن نداشته باشد.

این کلید فقط یک بار نمایش داده می‌شود. آن را در جایی ذخیره کنید که سایر اطلاعات ورود خود را ذخیره می‌کنید — هرگز در فایلی که وب‌سرور شما آن را سرویس می‌دهد قرار ندهید.

۲. انجام اولین درخواست

curl https://api.zinndigital.com/v1/reseller/services \
  -H "Authorization: Bearer zdk_live_…"

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

۳. کل یکپارچه‌سازی، در شش درخواست

WHEN                 CALL
an order is paid     POST   /v1/orgs                                   once per CUSTOMER
                     POST   /v1/sites                                  once per SERVICE
they have not paid   POST   /v1/reseller/services/{siteId}/suspend
they pay             POST   /v1/reseller/services/{siteId}/unsuspend
they cancel          DELETE /v1/sites/{siteId}
"log in to hosting"  POST   /v1/reseller/services/{siteId}/sso

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

# 1. the customer's account — keyed on YOUR customer id
curl -X POST https://api.zinndigital.com/v1/orgs \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-4211" \
  -d '{"type":"customer","name":"Acme Ltd"}'

# 2. their site — keyed on YOUR service id
curl -X POST https://api.zinndigital.com/v1/sites \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: service-9915" \
  -d '{"org_id":"<from step 1>","product_line":"mainstream","primary_domain":"acme.com"}'

دو قانون که اگر اشتباه پیاده‌سازی شوند هزینه‌بر خواهند بود

۱. حساب را بر اساس مشتری خود (CUSTOMER) و سایت را بر اساس سرویس خود (SERVICE) کلیدگذاری کنید. سفارش دوم یک مشتری باید در حسابی که از قبل دارد ثبت شود. اگر هر دو را بر اساس سرویس کلیدگذاری کنید، در نهایت یک مشتری با سه حساب نامرتبط و سه پنل جداگانه خواهید داشت. ۲. برای هر POST یک Idempotency-Key ارسال کنید که از شناسه خود شما برای آن آیتم ساخته شده است. هر سیستم صورت‌حسابی مجدداً تلاش می‌کند — بازخورد درگاه دو بار می‌رسد، یک مدیر یک راه‌اندازی ناموفق را دوباره اجرا می‌کند، یک مشتری دوبار کلیک می‌کند. بدون این کلید، تلاش دوم سایت دومی ایجاد می‌کند و هزینه آن برای شما منظور می‌شود.

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

• unsuspend ممکن است پاسخ 409 بدهد. این یعنی تیم سوءاستفاده ما سایت را مسدود کرده است، نه شما. پیام را نمایش دهید؛ آن را دوباره تلاش نکنید.
• **خاتمه دادن، حذف را زمان‌بندی می‌کند، نه اینکه آن را انجام دهد.** تاریخ به صورت pending_deletion_at برگردانده می‌شود. اینکه به مشتری بگویید اطلاعاتش از بین رفته است در حالی که نرفته، بدتر از این است که چیزی به او نگویید.
• disk_used_bytes ممکن است null باشد و null برابر با صفر نیست. این یعنی ما نتوانستیم اندازه‌گیری کنیم، نه اینکه از چیزی استفاده نشده است. از آن بگذرید — مقدار 0 را در رکوردهای خود ننویسید، وگرنه به مشتری نوار مصرف سبزی را نشان خواهید داد که هیچ داده‌ای برای آن ندارید.

۴. ورود یک مشتری به سیستم

درخواست POST /v1/reseller/services/{siteId}/sso یک URL یک‌بار مصرف برمی‌گرداند که مشتری شما را مستقیماً، در حالی که از قبل وارد سیستم شده است، به حساب خودشان هدایت می‌کند.

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

۵. نصب یک ماژول به جای آن

• WHMCS — ماژول را در پوشه modules/servers/zinn/ کپی کنید، یک سرور اضافه کنید که رمز عبور (Password) آن کلید API شماست، و خط محصول را روی محصول تنظیم کنید. روی تست اتصال (Test Connection) کلیک کنید: این کار یک درخواست واقعی انجام می‌دهد و به شما می‌گوید پلتفرم چه پاسخی داده است.
• HostBill — آن را در includes/modules/Hosting/zinn/ کپی کنید و به همین ترتیب متصل کنید.
• WordPress — ابزارک فروش مجدد Zinn®: جستجوی دامنه، لینک ورود به هاستینگ مشتریان، و راه‌اندازی WooCommerce هنگام پرداخت سفارش. منبع باز در <https://github.com/Zinn-Digital/zinn-reseller-toolkit>، یا آن را از بخش افزونه‌ها (Plugins) در داشبورد خود دانلود کنید.

۶. شروع به کار واقعی

قبل از ثبت یک سفارش واقعی، این موارد را بررسی کنید:

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

سایر موارد در کجا قرار دارند

مرجع کامل API — تمامی نقطه‌های پایانی (endpoints)، تولید شده از مشخصات ما، به همراه دسترسی مورد نیاز هر کدام — در آدرس <https://zinndigital.com/developers/api> موجود است.