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

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

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

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

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

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

چهار روش دسترسی

چهار روش دسترسی وجود دارد و همه آنها در باطن کار یکسانی انجام می‌دهند:

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

در داشبورد خود، به بخش API keys بروید و یک کلید ایجاد کنید. تنها دسترسی‌هایی را که نیاز دارد به آن بدهید:

⛔ دسترسی 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 ارسال کنید که از شناسه اختصاصی خودتان برای آن مورد ساخته شده باشد. هر سیستم صورت‌حسابی تلاش مجدد (retry) انجام می‌دهد — یک فراخوانی بازگشتی درگاه دو بار دریافت می‌شود، یک مدیر فرایند تحویل ناموفق را دوباره اجرا می‌کند، یا مشتری دو بار کلیک می‌کند. بدون این کلید، تلاش دوم یک سایت دوم ایجاد می‌کند و هزینه آن برای شما منظور می‌شود.

سه پاسخ که نباید آن‌ها را یکی در نظر بگیرید

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

۴. مشتری را وارد سیستم کنید

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

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

۵. در عوض یک ماژول نصب کنید

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

۶. آغاز به کار نهایی (Go live)

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

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

دسترسی به سایر بخش‌ها

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