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

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

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

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

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

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

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

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

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

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

⛔ Не предоставляйте интеграции разрешение 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/, добавьте сервер, указав в качестве поля Пароль ваш

ключ 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>.