Продаж хостингу Zinn® із власних систем

Ви перепродуєте наш хостинг. Ваші клієнти — ваші: ваші ціни, ваші рахунки, ваш платіжний провайдер. Так ви керуєте нашою платформою з будь-якого вже наявного у вас інструменту — білінг-панелі, власного сайту WordPress чи скрипта.

Що насправді бачать ваші клієнти

Перш ніж перейти до технічних деталей: ваші клієнти взагалі не повинні бачити нас. Три інтерфейси, і ви обираєте, яким користуватися.

⛔ Що б ви не вибрали, ви є юридичною особою, яка здійснює продаж для своїх клієнтів: ваші ціни, ваші рахунки, ваш номер ПДВ, ваш платіжний провайдер. Ми виставляємо рахунок вам, раз на місяць, за оптовими цінами.

Щойно ви встановите хост панелі, введіть його в поле Panel address плагіна WordPress і нікуди більше — посилання для входу, які генерує цей API, слідують за ним автоматично.

Чотири шляхи інтеграції

Існує чотири шляхи інтеграції, і всі вони роблять одне й те саме під капотом:

1. Отримайте ключ API

У своїй панелі керування перейдіть до API keys і створіть його. Надайте йому лише те, що потрібно:

⛔ Не давайте інтеграції дозвіл reseller.manage. Цей дозвіл редагує ваш прайс-лист і облікові дані вашого власного платіжного шлюзу. Дозвіл reseller.provision створений саме для того, щоб ключ, який ви вставляєте в білінг-панель або на сайт, не потребував його.

Ключ відображається лише один раз. Зберігайте його там же, де й інші свої облікові дані — ніколи у файлі, який обслуговує ваш вебсервер.

2. Здійсніть перший виклик

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

Це повертає кожну надану вами послугу, по одному рядку на сайт, із клієнтом, якому вона належить, її статусом і тим, скільки ви за неї стягуєте. Для нового облікового запису це порожній список — що є правильною відповіддю, а не помилкою.

3. Вся інтеграція в шість викликів

КОЛИ                  ВИКЛИК
замовлення сплачено   POST   /v1/orgs                                   один раз на КЛІЄНТА
                      POST   /v1/sites                                  один раз на ПОСЛУГУ
вони не сплатили      POST   /v1/reseller/services/{siteId}/suspend
вони сплачують        POST   /v1/reseller/services/{siteId}/unsuspend
вони скасовують       DELETE /v1/sites/{siteId}
«увійти в хостинг»    POST   /v1/reseller/services/{siteId}/sso

Надання послуг — це два виклики, і ключі мають значення:

# 1. обліковий запис клієнта — прив'язаний до ВАШОГО ідентифікатора клієнта
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. їхній сайт — прив'язаний до ВАШОГО ідентифікатора послуги
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"}'

Дві помилки, які коштують грошей, якщо їх припуститися

1. Прив’язуйте обліковий запис до вашого КЛІЄНТА, а сайт — до вашої ПОСЛУГИ. Друге замовлення клієнта має потрапити до облікового запису, який у нього вже є. Якщо прив'язати обидва елементи до послуги, один клієнт зрештою отримає три непов'язані облікові записи та три окремі панелі.
2. Надсилайте Idempotency-Key для кожного POST, створений на основі вашого власного ідентифікатора для цього об'єкта. Будь-яка білінгова система повторює спроби — зворотний виклик шлюзу надходить двічі, адміністратор повторно запускає невдале надання послуги, клієнт двічі клікає мишею. Без ключа друга спроба створить другий сайт, і вам доведеться за нього платити.

Три відповіді, які не можна зводити до двох

• unsuspend може повернути 409. Це означає, що сайт заблоковано нашою командою боротьби з порушеннями, а не вами. Покажіть повідомлення; не повторюйте запит.
• **Закриття планує видалення, а не виконує його одразу.** Дата повертається як pending_deletion_at. Казати клієнту, що його дані вже зникли, коли це не так — гірше, ніж нічого йому не казати.
• disk_used_bytes може бути null, і null — це не нуль. Це означає, що ми не змогли виміряти показник, а не те, що нічого не використовувалося. Пропустіть це — не записуйте 0 у власні записи, інакше ви покажете клієнту зелену шкалу використання для сайту, з якого у вас немає жодних даних.

4. Виконайте вхід клієнта

POST /v1/reseller/services/{siteId}/sso повертає одноразову URL-адресу, яка перенаправляє вашого клієнта безпосередньо в його власний обліковий запис із уже виконаним входом.

⛔ Створюйте її, коли вони натискають, а не під час рендерингу сторінки. Посилання є одноразовим і дійсним лише кілька хвилин, тому посилання, записане на сторінці, згорає при першому перегляді сторінки та залишається в кожному кеші між вами та браузером.

5. Натомість встановіть модуль

• 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 у своїй панелі керування.

6. Запускайтеся в роботу

Перевірте це перед тим, як прийняти справжнє замовлення:

• Тест з'єднання в модулі пройдено успішно, або ваш перший curl повертає список.
• Ваш прайс-лист налаштовано (Reselling → Your prices).
• Ваш платіжний шлюз підключено (Reselling → Payment gateways) — ваші клієнти платять вам через власний обліковий запис.
• Дані вашої компанії введено (Reselling → Your company), щоб рахунки ваших клієнтів містили інформацію про вашу юридичну особу та номер ПДВ, а не нашу.
• Ви оформили одне справжнє замовлення від початку до кінця й переконалися, що сайт з'явився.

Де знайти все інше

Повний довідник API — кожну кінцеву точку, згенеровану з нашої специфікації, із зазначенням дозволу, який потрібен для кожної з них — можна знайти на сайті <https://zinndigital.com/developers/api>.