Sprzedawaj hosting Zinn® z WHMCS

Moduł Zinn Digital® zmienia przyciski WHMCS w rzeczywiste akcje na naszej platformie. Zamówienie inicjuje hosting Twojego klienta. Automatyzacja zaległych faktur w WHMCS zawiesza go. Oznaczenie faktury jako opłaconej zwalnia go. Anulowanie planuje usunięcie. A Twój klient otrzymuje w swojej strefie klienta przycisk Zaloguj się do panelu hostingu, który loguje go bezpośrednio.

Jest on bezpłatny, objęty licencją GPL-2.0-or-later i nie posiada uprzywilejowanej ścieżki dostępu do naszej platformy: każde wywołanie, które wykonuje, to udokumentowany punkt końcowy, który możesz wykonać samodzielnie za pomocą własnego klucza API.

Zanim zaczniesz

Potrzebujesz dwóch rzeczy, przy czym druga często zaskakuje użytkowników.

1. Konto resellerkie Zinn® z aktywnym programem. Zarejestruj się na stronie

zinndigital.com i włącz sprzedaż resellerską.

2. Plan resellerki z przydziałem stron. Strony zamówione przez Twoich klientów pomniejszają pulę Twojego

planu, więc potrzebujesz takiego, który ma jeszcze wolne miejsce.

⚠️ Test połączenia nie może określić, czy zamówienie zakończy się sukcesem. Odczytuje on Twój program i niczego nie inicjuje, więc zgłasza prawidłowe, aktywne konto, które nie może jeszcze niczego sprzedać. Jeśli Twoje pierwsze zamówienie zakończy się błędem "Ta organizacja nie ma planu hostingu, więc nie może jeszcze hostować strony" (This organization has no hosting plan, so it cannot host a site yet), to właśnie to się stało – kup lub przedłuż swój plan resellerki i złóż zamówienie ponownie. Z modułem wszystko jest w porządku.

1. Utwórz klucz API

W panelu Zinn® otwórz sekcję Klucze API (API keys) i utwórz klucz z dokładnie tymi jedenastoma uprawnieniami:

| Uprawnienie | Do czego jest potrzebne | | -------------------- | ----------------------------------------------------------- | | org.create | Otwórz konto Zinn® swojego klienta przy jego pierwszym zamówieniu. | | org.read | Odczytuj konta swoich klientów. | | sites.create | Inicjuj stronę. | | sites.view | Odczytuj usługę i jej wykorzystanie. | | sites.delete | Likwiduj. | | reseller.view | Wyświetlaj listę sprzedanych usług oraz odczytuj dysk i przepustowość. | | reseller.provision | Zawieszaj, zwalniaj, loguj klienta, ustawiaj jego plan i zmieniaj pakiet. | | billing.view | Odczytuj koszt uaktualnienia przed jego przeprowadzeniem. | | sites.manage | Czyszcz pamięć podręczną i wykonuj kopie zapasowe za pomocą przycisków. | | sites.panel_access | Zmieniaj hasło administratora WordPressa. | | hosting.php.manage | Przełączaj wersję PHP podczas uaktualniania lub obniżania wersji. |

⛔ Nie przyznawaj uprawnienia reseller.manage. Klucz wklejony do panelu rozliczeniowego powinien móc zablokować klienta z powodu braku płatności i zalogować go. Nie powinien natomiast mieć możliwości odczytywania i ponownego zapisywania poświadczeń Twojej własnej bramki płatności. Uprawnienie reseller.provision istnieje po to, aby nie trzeba było przyznawać szerszego dostępu. ⛔ Uprawnienie org.create nie jest opcjonalne. Bez niego moduł może odczytywać Twoje konta, ale nie może otworzyć nowego, przez co test połączenia przechodzi pomyślnie, a pierwsze zamówienie zwraca odpowiedź 403. ⛔⛔ Przyznaj uprawnienia dla całej tabeli i pamiętaj, że test połączenia nie poinformuje Cię, jeśli jakiegoś brakuje. Odczytuje on Twój program resellerki i niczego nie inicjuje, więc świeci się na zielono dla klucza, któremu brakuje któregokolwiek z tych uprawnień. Zamiast tego otrzymasz błąd 403 przy tej jednej operacji, którą obejmuje brakujące uprawnienie – miesiące później, od klienta.

2. Zainstaluj moduł

1. Pobierz moduł i rozpakuj archiwum ZIP.
2. Prześlij katalog zinn do instalacji WHMCS, tak aby plik modułu znalazł się w lokalizacji

modules/servers/zinn/zinn.php.

⛔ Katalog musi nazywać się zinn. WHMCS wyprowadza nazwy funkcji modułu inicjującego z nazwy jego katalogu, więc zmiana nazwy na zinn-whmcs lub zinndigital skutkuje utworzeniem modułu, który WHMCS wyświetla na liście, pozwala wybrać, a następnie nigdy go nie wywołuje – nie zgłaszając przy tym żadnego błędu. Archiwum ZIP rozpakowuje się już pod właściwą nazwą; po prostu jej nie zmieniaj.

3. Dodaj serwer

W WHMCS przejdź do: Konfiguracja → Ustawienia systemowe → Serwery → Dodaj nowy serwer (Configuration → System Settings → Servers → Add New Server).

• Nazwa (Name): cokolwiek, np. Zinn Digital®
• Nazwa hosta (Hostname): api.zinndigital.com
• Typ (Type): Zinn Digital®
• Hasło (Password): Twój klucz API z kroku 1

⛔ Klucz należy wpisać w polu Hasło (Password), które WHMCS przechowuje w postaci zaszyfrowanej. Nie umieszczaj go w opcji konfiguracji produktu – te są zapisywane jako zwykły tekst w bazie danych i są widoczne dla każdego administratora, a te poświadczenia mogą tworzyć i niszczyć hosting Twoich klientów.

Naciśnij przycisk Testuj połączenie (Test Connection). Wykonuje on rzeczywiste zapytanie i zgłasza odpowiedź naszej platformy, zamiast jedynie sprawdzać, czy pola zostały wypełnione.

4. Utwórz produkt

Przejdź do Konfiguracja → Ustawienia systemowe → Produkty/Usługi (Configuration → System Settings → Products/Services), a następnie ustaw Ustawienia modułu (Module Settings) na serwer, który właśnie dodano. Dostępne pola:

| Pole | Wymagane | Opis | | ---------------- | -------- | -------------------------------------------------------------------------- | | Linia produktów (Product line) | tak | Linia Zinn®, którą sprzedajesz – mainstream (zarządzany WordPress), footprint_free, wordpress, linux, cloud, agency, app_hosting, ai_hosting, lms_hosting, managed_database, vector_hosting, zinn_compute, fleet_linux, fleet_enterprise, mail lub reseller. | | Struktura (Stack) | tak | Co jest budowane: wordpress (domyślnie), woocommerce, php, static, node, one_click, headless_cms, nextcloud lub owncloud. | | Aplikacja (Application) | nie | Dotyczy tylko struktur one_click i headless_cms – określa, jaką aplikację zainstalować. Wskazanie aplikacji dla jakiejkolwiek innej struktury zostanie odrzucone, ponieważ dana struktura sama decyduje o tym, co jest instalowane. | | Wersja PHP (PHP version) | nie | np. 8.3. Pozostaw puste dla wartości domyślnej danej linii. Wersja niedostępna w danej linii zostanie odrzucona wraz z listą wersji oferowanych. | | Kod planu (Plan code) | tak | Plan Zinn®, który sprzedaje ten produkt. Polecenie GET /v1/reseller/prices wyświetli Twoje plany. Zamówienie bez niego zostanie odrzucone – zobacz ostrzeżenie poniżej. | | Interwał rozliczeniowy (Billing interval) | nie | monthly (domyślnie) lub annual – interwał, z jakim rozliczana jest Twoja linia hurtowa dla tego klienta. Kwota, jaką obciążasz własnego klienta, jest ustawiana w produkcie WHMCS i pozostaje bez wpływu. |

⛔⛔ Kod planu jest wymagany, a zamówienie bez niego jest celowo odrzucane. Do 2026-09-01 pole to miało charakter dekoracyjny i nikt go nie odczytywał, w związku z czym moduł zamawiał hosting, który nie posiadał żadnego planu – a wszelkie tego konsekwencje przebiegały bezgłośnie. Twoje rozliczenie hurtowe jest generowane na podstawie aktywnych subskrypcji Twoich klientów, więc w zestawieniu nie było pozycji dla tej usługi i nie wystawiono Ci żadnej faktury tak długo, jak ona działała; Twój klient nie odziedziczył żadnych przydziałów, więc na jego stronie nie zastosowano żadnego limitu dysku ani plików; oraz Funkcja Zmień pakiet nie miała niczego do zmienienia, więc sprzedane przez Ciebie uaktualnienie nie mogło zostać przeprowadzone. Strona była inicjowana i działała bez zarzutu przez cały ten czas.

Zamiast tego moduł odrzuca teraz zamówienie, ponieważ nie ma bezpiecznego planu, który mógłby odgadnąć: domysł skutkowałby zainicjowaniem hostingu w ramach planu, którego nie wybrałeś i którego ceny mogłeś nie ustalić, a – w przeciwieństwie do odrzucenia, o którym dowiadujesz się natychmiast – wyszłoby to na jaw dopiero po nadejściu rachunku, o ile w ogóle.

Ustaw opcję Automatyczna instalacja (Auto Setup) zgodnie z własnymi preferencjami – moduł jest idempotentny względem identyfikatora usługi WHMCS, więc ponowna próba inicjacji zwraca tę samą stronę zamiast naliczać opłatę za kolejną.

Działanie poszczególnych akcji WHMCS

| Akcja WHMCS | Co dzieje się po naszej stronie | | --------------------------- | ---------------------------------------------------------------------------------------- | | Utwórz (Create) | Tworzy konto Zinn® klienta (lub używa ponowne tego, które już posiada) i inicjuje jego stronę. | | Zawieszaj (Suspend) | Umieszcza stronę w stanie blokady z powodu braku płatności. Treść jest zachowana; nic nie jest usuwane. | | Odwieś (Unsuspend) | Zdejmuje blokadę nałożoną przez Ciebie. | | Zlikwiduj (Terminate) | Planuje usunięcie strony z uwzględnieniem okresu wypowiedzenia. Data jest widoczna w strefie klienta. | | Aktualizacja zużycia (Usage update) | Odświeża wykorzystanie dysku i przepustowości dla każdej usługi, raz dziennie. | | Zaloguj się do panelu hostingu (Log in to hosting panel) | Otwiera jednorazowy, jednorazowy link logowania prowadzący bezpośrednio do panelu klienta. | | Zmień pakiet (Change Package) | Uaktualnia lub obniża wersję usługi. Przenosi pakiet oraz wersję PHP, jeśli nowy produkt ją określa. | | Zmień hasło (Change Password) | Ustawia hasło administratora WordPressa. Pole nie pojawia się w strukturach, które nie posiadają takiego konta. | | Odnowienie (Renew) | Potwierdza, że usługa nadal istnieje. Hosting Zinn® ma charakter ciągły, więc nie ma zdalnego okresu do przedłużenia. | | Synchronizuj zużycie / Wyczyść pamięć podręczną / Utwórz kopię zapasową (Sync Usage / Purge Cache / Take Backup) | Przyciski na stronie usługi administratora. Twój klient otrzymuje opcje czyszczenia pamięci podręcznej i tworzenia kopii zapasowej w swojej strefie klienta. | | Karta usługi (Service tab) | Status, plan, dysk, przepustowość, ewentualne zaplanowane usunięcie oraz informacja o tym, kto dokonał zawieszenia. | | Importuj (Import) | Funkcja ListAccounts odczytuje każdą stronę, dzięki czemu import nie może potajemnie zatrzymać się na pierwszej z nich. |

Uaktualnienia: kto kogo obciąża kosztami

Klient nigdy nie otrzymuje faktury od Zinn® z tytułu zamówienia lub uaktualnienia. Rozliczasz go za pośrednictwem WHMCS; my obciążamy Ciebie na Twoim zestawieniu hurtowym. Z tego powodu funkcja Zmień pakiet przenosi uprawnienia klienta oraz pozycję na Twoim kolejnym zestawieniu, nie dotykając żadnej karty płatniczej – WHMCS pobrał już środki od Twojego klienta i obliczył własne proporcjonalne rozliczenie (proration).

Druga usługa klienta. W ramach tego samego planu jest to kolejna strona w ramach przydziału stron tego planu, i żadne dodatkowe zasoby nie są przyznawane. W przypadku innego planu żądanie zostaje odrzucone: zastąpienie aktywnego planu pozostawiłoby jedną z dwóch usług nierozliczoną. Sprzedaj obie usługi w ramach tego samego planu lub skonfiguruj klienta jako oddzielny rekord klienta w WHMCS.

Zmiana hasła istnieje tylko dla WordPressa. Hosting Zinn® nie posiada pojedynczego „hasła usługi” – klient uzyskuje dostęp do panelu za pomocą przycisku logowania – a strona oparta na strukturze php lub static nie posiada konta aplikacji, dla którego można zmienić hasło. WHMCS całkowicie ukrywa to pole, zamiast wyświetlać takie, które nie może działać.

Trzy odpowiedzi, których nie wolno sprowadzać do dwóch

• Odwieszenie może zakończyć się odmową. Oznacza to, że strona została zawieszona przez nasz

zespół ds. nadużyć (abuse), a nie przez Ciebie, i żaden panel rozliczeniowy nie może jej odblokować. Informuje o tym stosowny komunikat; pokaż go administratorowi zamiast ponawiać próbę.

• Likwidacja planuje usunięcie, a nie je przeprowadza. Data powraca jako

pending_deletion_at i jest widoczna w strefie klienta. Informowanie klienta, że jego dane zostały już skasowane, podczas gdy tak nie jest, jest gorsze niż nieinformowanie go o niczym.

• Wykorzystanie dysku i przepustowości może być nieznane, a stan nieznany nie oznacza zera. Gdy odczyt nie powiódł się,

moduł pozostawia wartość bez zmian zamiast wpisywać 0 – w przeciwnym razie WHMCS wyświetliłby klientowi uspokajający, pusty pasek użycia dla strony, dla której nie posiadamy żadnego odczytu.

Rozwiązywanie problemów

Test połączenia przechodzi pomyślnie, a pierwsze zamówienie kończy się błędem uprawnień. W kluczu API brakuje uprawnienia org.create. Moduł musi otworzyć konto klienta, zanim będzie mógł utworzyć jego stronę.

Zamówienie kończy się błędem informującym, że organizacja nie posiada planu hostingu. Twój plan resellerki nie ma już wolnego przydziału stron lub jeszcze takiego planu nie posiadasz. Zobacz sekcję Zanim zaczniesz powyżej.

Zamówienie kończy się błędem wspominającym o strukturze (stack). Pole Struktura (Stack) w produkcie jest puste lub wskazuje strukturę, której nie obsługujemy. Ustaw je na wartość wordpress, chyba że sprzedajesz coś innego.

Anulowania kończą się niepowodzeniem. Upewnij się, że korzystasz z modułu w wersji 1.0.0 lub nowszej. Wcześniejsze wersje nie wysyłały potwierdzenia usunięcia i każda likwidacja była odrzucana, co powodowało, że usługa nadal działała i generowała koszty.

Odrzucenie zawierające nazwę pola. Nasze komunikaty o błędach walidacji zawierają nazwę pola i powód w nawiasach kwadratowych po komunikacie, np. (php_version: 7.2 is not offered on this product line). To jest ta część, na którą można zareagować – zdanie znajdujące się przed nią ma z założenia charakter ogólny.

Weryfikacja pobranego pliku

Każde archiwum jest przesyłane za pośrednictwem protokołu TLS z naszej własnej nazwy hosta i nigdy nie jest przekierowywane do hosta zewnętrznego. Suma kontrolna SHA-256 jest wydrukowana obok linku do pobrania na stronie pobierania. Porównaj ją po pobraniu:

• macOS lub Linux: shasum -a 256 zinn-whmcs-1.0.0.zip
• Windows: certutil -hashfile zinn-whmcs-1.0.0.zip SHA256

Nie korzystasz z WHMCS?

Dostępny jest moduł HostBill oraz jednoplikowy klient PHP dla każdego innego rozwiązania – oba są bezpłatne i znajdują się na tej samej stronie pobierania. Każdy punkt końcowy używany przez moduły jest opisany w dokumentacji API.