WHMCS에서 Zinn® 호스팅 판매하기

Zinn Digital® 모듈은 WHMCS 자체의 버튼을 당사 플랫폼의 실제 작업으로 전환합니다. 주문은 클라이언트의 호스팅을 프로비저닝합니다. WHMCS의 연체 인보이 S 자동화는 호스팅을 정지합니다. 인보이드를 유료로 표시하면 호스팅이 해제됩니다. 취소하면 삭제 일정이 예약됩니다. 그리고 클라이언트의 클라이언트 영역에는 클릭 한 번으로 곧바로 로그인할 수 있는 호스팅 패널에 로그인 버튼이 표시됩니다.

이 모듈은 무료이며 GPL-2.0-or-later 라이선스가 적용되고 당사 플랫폼으로 향하는 특권 경로가 없습니다. 이 모듈이 수행하는 모든 호출은 사용자가 자신의 API 키로 직접 수행할 수 있는 문서화된 엔드포인트입니다.

시작하기 전에

두 가지가 필요하며, 두 번째 항목에서 많은 분들이 실수를 하십니다.

활성 프로그램이 있는 Zinn® 리셀러 계정. zinndigital.com에 가입하고 리셀링을 활성화하세요.
사이트 허용량이 포함된 리셀러 플랜. 클라이언트가 주문한 사이트는 사용자의 플랜에 포함되므로 여유 공간이 있는 플랜이 필요합니다.

⚠️ 테스트 연결은 주문의 성공 여부를 알려드릴 수 없습니다. 이 기능은 프로그램을 읽고 프로비저닝을 수행하지 않으므로, 아직 아무것도 판매할 수 없는 상태이더라도 정상적인 active 계정으로 보고합니다. 첫 번째 주문이 "이 조직에는 호스팅 플랜이 없으므로 아직 사이트를 호스팅할 수 없습니다."라는 오류와 함께 실패하는 경우 바로 이런 상황이 발생한 것입니다. 리셀러 플랜을 구매하거나 연장한 후 다시 주문하세요. 모듈에는 아무런 문제가 없습니다.

1. API 키 생성

Zinn® 대시보드에서 API 키를 열고 정확히 다음 11가지 권한을 가진 키를 생성하세요.

| 권한 | 필요한 이유 | | ---------------------- | ------------------------------------------------------------- | | org.create | 첫 주문 시 클라이언트의 Zinn® 계정을 엽니다. | | org.read | 클라이언트 계정을 읽습니다. | | sites.create | 사이트를 프로비저닝합니다. | | sites.view | 서비스 및 사용량을 읽습니다. | | sites.delete | 종료합니다. | | reseller.view | 판매 내역을 나열하고 디스크 및 대역폭을 읽습니다. | | reseller.provision | 정지, 해제, 클라이언트 로그인, 플랜 설정 및 패키지를 변경합니다. | | billing.view | 업그레이드 비용을 수행 전에 읽습니다. | | sites.manage | 버튼을 사용하여 캐시를 지우고 백업을 수행합니다. | | sites.panel_access | WordPress 관리자 비밀번호를 변경합니다. | | hosting.php.manage | 업그레이드 또는 다운그레이드 시 PHP 버전을 전환합니다. |

⛔ reseller.manage 권한을 부여하지 마세요. 결제 패널에 붙여넣은 키는 미납 시 클라이언트를 보류하고 로그인시키는 기능만 수행해야 합니다. 사용자의 결제 게이트웨이 자격 증명을 읽고 다시 작성할 수 있어서는 안 됩니다. 더 큰 권한을 부여할 필요가 없도록 reseller.provision이 존재합니다. ⛔ org.create는 선택 사항이 아닙니다. 이 권한이 없으면 모듈이 계정을 읽을 수는 있지만 열 수는 없으므로, 테스트 연결은 통과되지만 첫 번째 주문은 403을 반환합니다. ⛔⛔ 표 전체에 권한을 부여하고, 테스트 연결만으로는 권한 누락 여부를 알 수 없다는 점에 유의하세요. 이 기능은 리셀러 프로그램을 읽고 프로비저닝을 수행하지 않으므로 이러한 권한 중 일부가 누락된 키에 대해서도 녹색으로 표시됩니다. 대신 몇 달 후 고객으로부터 누락된 권한이 적용되는 단일 작업에 대해 403 오류가 발생하게 됩니다.

2. 모듈 설치

모듈 다운로드 후 압축을 풉니다.
zinn 디렉토리를 WHMCS 설치 폴더에 업로드하여 모듈 파일이 modules/servers/zinn/zinn.php에 위치하도록 합니다.

⛔ 디렉토리 이름은 반드시 zinn이어야 합니다. WHMCS는 디렉토리 이름에서 프로비저닝 모듈의 함수 이름을 유추하므로, 이름을 zinn-whmcs나 zinndigital로 변경하면 WHMCS에 모듈이 표시되고 선택할 수 있게 되더라도 아무런 오류 없이 실행되지 않습니다. zip 파일은 이미 올바른 이름으로 압축이 해제되므로 이름을 변경하지 마세요.

3. 서버 추가

WHMCS에서 Configuration → System Settings → Servers → Add New Server로 이동합니다.

이름: 임의 지정 (예: Zinn Digital®)
호스트 이름: api.zinndigital.com
유형: Zinn Digital®
비밀번호: 1단계에서 생성한 API 키

⛔ 키는 WHMCS가 암호화하여 저장하는 비밀번호(Password) 필드에 입력해야 합니다. 제품 구성 옵션에 입력하지 마세요. 해당 옵션은 데이터베이스에 일반 텍스트로 저장되어 모든 관리자가 볼 수 있으며, 이 자격 증명은 클라이언트의 호스팅을 생성하고 파괴할 수 있습니다.

테스트 연결(Test Connection)을 누릅니다. 필드가 채워져 있는지 확인하는 대신 실제 호출을 수행하여 당사 플랫폼의 응답을 보고합니다.

4. 제품 생성

Configuration → System Settings → Products/Services로 이동한 후 모듈 설정(Module Settings)을 방금 추가한 서버로 설정합니다. 필드는 다음과 같습니다.

| 필드 | 필수 여부 | 내용 | | ---------------- | --------- | -------------------------------------------------------------------------- | | Product line | 예 | 판매 중인 Zinn® 라인 — mainstream (관리형 WordPress), footprint_free, wordpress, linux, cloud, agency, app_hosting, ai_hosting, lms_hosting, managed_database, vector_hosting, zinn_compute, fleet_linux, fleet_enterprise, mail 또는 reseller. | | Stack | 예 | 빌드되는 항목: wordpress (기본값), woocommerce, php, static, node, one_click, headless_cms, nextcloud 또는 owncloud. | | Application | 아니요 | one_click 및 headless_cms 스택에만 해당 — 설치할 애플리케이션입니다. 다른 스택에서 이를 지정하면 해당 스택이 이미 설치될 항목을 결정하므로 거부됩니다. | | PHP version | 아니요 | 예: 8.3. 라인의 기본값을 사용하려면 비워 두세요. 라인에서 제공하지 않는 버전은 지원되는 버전 목록과 함께 거부됩니다. | | Plan code | 예 | 이 제품이 판매하는 Zinn® 플랜입니다. GET /v1/reseller/prices에서 본인의 플랜을 확인할 수 있습니다. 플랜 코드가 없는 주문은 거부됩니다 — 아래 경고를 참조하세요. | | Billing interval | 아니요 | monthly (기본값) 또는 annual — 이 클라이언트에 대해 귀하의 도매 라인이 청구되는 주기입니다. 자체 클라이언트에 청구하는 금액은 WHMCS 제품에서 설정되며 영향을 받지 않습니다. |

⛔⛔ 플랜 코드는 필수이며, 플랜 코드가 없는 주문은 의도적으로 거부됩니다. 2026-09-01 이전에는 이 필드가 장식용이었고 아무것도 읽지 않았기 때문에, 모듈은 어떠한 플랜도 포함되지 않은 호스팅을 주문했으며 그에 따른 모든 결과는 조용히 묻혔습니다. 도매 명세서는 클라이언트의 활성 구독을 기반으로 작성되므로 서비스에 대한 라인이 없고 실행되는 동안 청구된 금액이 없습니다. 클라이언트는 허용량을 상속받지 못하므로 사이트에 디스크나 파일 할당량이 적용되지 않았으며, 패키지 변경(Change Package)할 대상이 없어 판매한 업그레이드를 수행할 수 없었습니다. 사이트는 전체 과정에서 완벽하게 프로비저닝되고 서비스되었습니다.

이제 모듈은 대신 주문을 거부합니다. 모듈이 임의로 추측할 수 있는 안전한 플랜이 없기 때문입니다. 추측을 통해 프로비저닝하면 사용자가 선택하지 않았고 가격을 책정하지 않았을 수도 있는 플랜으로 호스팅이 설정되며, 즉시 확인할 수 있는 거부와 달리 명세서가 도착했을 때(그나마 확인하는 경우에만) 비로소 문제가 드러나게 됩니다.

자동 설정(Auto Setup)을 선호하는 설정으로 지정하세요. 모듈은 WHMCS 서비스 ID에 대해 멱등성(idempotent)을 가지므로, 재시도된 프로비저닝은 두 번째 요금을 청구하는 대신 동일한 사이트를 반환합니다.

각 WHMCS 작업의 기능

| WHMCS 작업 | 당사 측에서 발생하는 일 | | --------------------------- | ---------------------------------------------------------------------------------------- | | Create | 클라이언트의 Zinn® 계정을 생성(또는 이미 보유한 계정 재사용)하고 사이트를 프로비저닝합니다. | | Suspend | 미납 상태로 사이트를 보류합니다. 콘텐츠는 유지되며 아무것도 삭제되지 않습니다. | | Unsuspend | 귀하가 설정한 보류를 해제합니다. | | Terminate | 유예 기간을 두어 사이트 삭제를 예약합니다. 날짜는 클라이언트 영역에 표시됩니다. | | Usage update | 하루에 한 번 모든 서비스의 디스크 및 대역폭을 새로 고칩니다. | | Log in to hosting panel | 클라이언트 패널로 바로 이동하는 일회용 단일 사용 로그인 링크를 엽니다. | | Change Package | 서비스를 업그레이드하거나 다운그레이드합니다. 패키지를 이동하고, 새 제품에 지정된 경우 PHP 버전도 이동합니다. | | Change Password | WordPress 관리자 비밀번호를 설정합니다. 이러한 계정이 없는 스택에서는 상자가 표시되지 않습니다. | | Renew | 서비스가 여전히 존재하는지 확인합니다. Zinn® 호스팅은 연속적이므로 연장할 원격 기간이 없습니다. | | Sync Usage / Purge Cache / Take Backup | 관리자 서비스 페이지의 버튼입니다. 클라이언트는 클라이언트 영역에서 캐시 지우기 및 백업 수행을 이용할 수 있습니다. | | Service tab | 상태, 플랜, 디스크, 대역폭, 예약된 삭제 내역 및 정지를 실행한 주체를 표시합니다. | | Import | ListAccounts가 모든 페이지를 읽으므로 가져오기가 첫 번째 페이지에서 조용히 멈추지 않습니다. |

업그레이드: 청구 주체

클라이언트에게는 주문 시나 업그레이드 시 Zinn®에서 인보이스가 발급되지 않습니다. 귀하는 WHMCS를 통해 클라이언트에게 청구하고, 당사는 도매 명세서를 통해 귀하에게 청구합니다. 따라서 패키지 변경은 클라이언트의 권한과 다음 명세서의 라인을 이동시키며 카드 결제는 발생시키지 않습니다. WHMCS가 이미 클라이언트의 금액을 결제받고 자체적인 일할 계산을 처리했기 때문입니다.

클라이언트의 두 번째 서비스. 동일한 플랜에서는 해당 플랜의 자체 사이트 허용량에 속하는 또 다른 사이트이며 추가 권한이 부여되지 않습니다. 다른 플랜인 경우 거부됩니다. 라이브 플랜을 교체하면 두 서비스 중 하나가 미청구 상태로 남게 되기 때문입니다. 두 서비스를 모두 동일한 플랜으로 판매하거나, WHMCS에서 클라이언트를 별도의 클라이언트 레코드로 설정하세요.

비밀번호 변경(Change Password)은 WordPress에만 존재합니다. Zinn® 호스팅에는 단일 "서비스 비밀번호"가 없으며(클라이언트는 로그인 버튼으로 패널에 접속합니다), php 또는 static 사이트에는 변경할 애플리케이션 계정이 없습니다. 작동하지 않는 상자를 표시하는 대신 WHMCS가 상자를 완전히 숨깁니다.

두 가지로 단순화해서는 안 되는 세 가지 답변

Unsuspend는 거부로 응답할 수 있습니다. 이는 귀하가 아닌 당사의 어뷰즈 팀에 의해 사이트가 정지되었음을 의미하며, 어떠한 결제 패널도 이를 해제할 수 없습니다. 메시지에 그렇게 명시되어 있으므로 재시도하지 말고 관리자에게 보여주세요.
Terminate는 삭제를 예약하는 것이며 실행하는 것이 아닙니다. 날짜가 pending_deletion_at으로 반환되며 클라이언트 영역에 표시됩니다. 데이터가 아직 사라지지 않았는데 고객에게 이미 사라졌다고 말하는 것은 아무 말도 하지 않는 것보다 더 나쁩니다.
디스크와 대역폭은 알 수 없음 상태일 수 있으며, 알 수 없음은 0이 아닙니다. 측정값을 가져올 수 없는 경우 모듈은 0을 쓰는 대신 기존 수치를 그대로 둡니다. 그렇지 않으면 당사에서 측정값을 가져오지 못한 사이트에 대해 WHMCS가 고객에게 안심시키는 빈 사용량 바를 표시하게 되기 때문입니다.

문제 해결

테스트 연결이 통과되고 첫 번째 주문이 권한 오류로 실패합니다. API 키에 org.create 권한이 누락되었습니다. 모듈은 사이트를 생성하기 전에 클라이언트의 계정을 열어야 합니다.

조직에 호스팅 플랜이 없다는 오류와 함께 주문이 실패합니다. 리셀러 플랜의 사이트 허용량이 모두 소진되었거나 아직 플랜을 보유하고 있지 않습니다. 위의 시작하기 전에를 참조하세요.

스택을 언급하며 주문이 실패합니다. 제품의 Stack 필드가 비어 있거나 당사에서 빌드하지 않는 항목을 지정하고 있습니다. 다른 제품을 판매하는 경우가 아니라면 wordpress로 설정하세요.

취소가 실패합니다. 모듈 버전 1.0.0 이상을 사용하고 있는지 확인하세요. 이전 빌드는 삭제 확인을 전송하지 않아 모든 종료가 거부되었으며, 이로 인해 서비스가 계속 실행되고 요금이 청구되었습니다.

확인란을 지정하는 거부.

당사의 유효성 검사 오류는 메시지 뒤의 괄호 안에 필드와 이유를 명시합니다(예: (php_version: 7.2 is not offered on this product line)). 이것이 조치를 취할 수 있는 절반이며, 그 앞에 있는 문장은 의도적으로 일반적인 내용으로 작성되었습니다.

다운로드 확인

모든 아카이브는 당사 호스트 이름에서 TLS를 통해 제공되며 타사 호스트로 리디렉션되지 않습니다. SHA-256 체크섬은 다운로드 페이지의 다운로드 링크 옆에 인쇄되어 있습니다. 다운로드 후 비교하세요:

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

WHMCS를 사용하고 있지 않으신가요?

HostBill 모듈과 기타 용도의 단일 파일 PHP 클라이언트가 모두 제공되며, 둘 다 무료이고 동일한 다운로드 페이지에 있습니다. 모듈이 사용하는 모든 엔드포인트는 API 참조에 있습니다.