Продажа хостинга Zinn® с ваших собственных систем

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

Что на самом деле видят ваши клиенты

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

| Интерфейс | Кому принадлежит | |---|---| | Хостинг-панель на вашем доменном имени | Укажите доменное имя панели в разделе Перепродажа → Ваш бренд, и ваши клиенты будут входить по адресу panel.yourcompany.com, видя ваш логотип и ваши цвета. Та же панель, ваш адрес. | | Ваш собственный сайт | Плагин WordPress добавляет поиск доменов и ссылку для входа в один клик на ваш сайт, а заказы оформляются через вашу корзину WooCommerce. | | Ваша биллинг-панель | WHMCS или HostBill остается главным входом; модуль выполняет подготовку ресурсов на стороне бэкенда, а кнопка в клиентской зоне перенаправляет пользователей напрямую в их хостинг. |

⛔ Что бы вы ни выбрали, вы являетесь принципалом (продавцом) для своих клиентов: ваши цены, ваши счета, ваш номер плательщика НДС, ваш платежный шлюз. Мы выставляем счет вам, один раз в месяц, по оптовым ценам.

Установив доменное имя панели, введите его только в поле Адрес панели плагина WordPress и больше нигде — ссылки для входа, создаваемые этим API, будут формироваться на его основе автоматически.

Четыре способа интеграции

Существует четыре способа интеграции, и все они выполняют одно и то же на бэкенде:

| | Для чего | |---|---| | Модуль WHMCS | Магазин на базе WHMCS | | Модуль HostBill | Магазин на базе HostBill | | Плагин WordPress | Продажи с вашего собственного сайта WordPress или WooCommerce | | API | Все остальное — Blesta, внутренняя система, cron-скрипт |

1. Получите ключ API

В вашей панели управления перейдите в раздел Ключи API и создайте новый. Предоставьте ему только те разрешения, которые необходимы:

| Разрешение | Зачем нужно | |---|---| | org.read | Чтение учетных записей ваших клиентов | | sites.create | Создание сайта | | sites.view | Чтение данных услуги | | sites.delete | Удаление | | reseller.view | Просмотр списка ваших услуг и потребления ресурсов | | reseller.provision | Приостановка, возобновление и авторизация клиента |

⛔ Не давайте интеграции разрешение 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. учетная запись клиента — индексируется по ВАШЕМУ 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. их сайт — индексируется по ВАШЕМУ 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"}'

Два правила, нарушение которых стоит денег

1. Индексируйте учетную запись по вашему КЛИЕНТУ, а сайт — по вашей УСЛУГЕ. Второй заказ клиента должен быть добавлен к его существующей учетной записи. Если индексировать оба объекта по услуге, у одного клиента окажется три несвязанных аккаунта и три отдельные панели.
2. Передавайте заголовок Idempotency-Key для каждого метода POST, формируя его из вашего внутреннего ID объекта. Любая биллинг-система выполняет повторные попытки: обратный вызов шлюза приходит дважды, администратор повторно запускает неудачное создание услуги, клиент дважды кликает по кнопке. Без этого ключа вторая попытка приведет к созданию второго сайта, и вам придется за него платить.

Три ответа, которые нельзя упрощать до двух

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

4. Выполните вход от имени клиента

Метод POST /v1/reseller/services/{siteId}/sso возвращает одноразовый URL, который перенаправляет вашего клиента прямо в его учетную запись с уже выполненным входом.

⛔ Генерируйте ссылку по клику, а не во время рендеринга страницы. Эта ссылка является одноразовой и действует всего несколько минут, поэтому ссылка, зашитая на странице, будет использована при первом же просмотре и останется во всех кэш-памятях между вами и браузером.

5. Или установите готовый модуль

• WHMCS — скопируйте модуль в директорию modules/servers/zinn/, добавьте сервер, у которого в поле Пароль указан ваш API-ключ, и задайте линейку продуктов для товара. Нажмите Тест соединения: модуль выполнит реальный вызов и покажет ответ платформы.
• HostBill — скопируйте в каталог includes/modules/Hosting/zinn/ и подключите аналогичным образом.
• WordPress — инструмент Zinn® Reseller Toolkit: поиск доменов, ссылка для входа в хостинг ваших клиентов и создание ресурсов в WooCommerce при оплате заказа. Исходный код доступен на странице <https://github.com/Zinn-Digital/zinn-reseller-toolkit> или в вашей панели управления в разделе Плагины.

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

Проверьте следующие пункты перед обработкой реальных заказов:

• Тест соединения для модуля успешно пройден, либо ваш первый запрос curl возвращает список.
• Ваш прайс-лист настроен (Перепродажа → Ваши цены).
• Ваш платежный шлюз подключен (Перепродажа → Платежные шлюзы) — клиенты платят вам через ваш собственный аккаунт.
• Указаны реквизиты вашей компании (Перепродажа → Ваша компания), благодаря чему в счета клиентов будут входить ваши юридические данные и номер НДС, а не наши.
• Вы успешно оформили один реальный заказ от начала и до конца и убедились, что сайт появился в системе.

Где найти остальную информацию

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