지식 베이스
자체 시스템에서 Zinn® 호스팅 판매하기
자체 빌링 패널, WordPress 사이트 또는 스크립트에서 Zinn 호스팅을 관리하세요. API 키를 발급받고 첫 번째 호출을 실행한 뒤, 전체 연동을 구성하는 나머지 6개의 호출을 진행해 보세요.
귀하는 당사의 호스팅을 재판매합니다. 고객은 귀하의 고객이며, 가격, 청구서, 결제 대행사 모두 귀하의 것입니다. 빌링 패널, 자체 WordPress 사이트, 또는 스크립트 등 이미 운영 중인 어떤 시스템에서든 당사 플랫폼을 구동하는 방식입니다.
고객이 실제로 보게 되는 화면
작동 메커니즘을 살펴보기 전에 알아둘 점은 고객은 Zinn을 전혀 볼 일이 없다는 것입니다. 세 가지 인터페이스가 있으며, 이 중 사용할 방식을 선택할 수 있습니다.
| 인터페이스 | 소유 주체 | |---|---| | 자사 호스팅 패널 (자체 도메인) | 리셀러(Reselling) → 브랜드(Your brand)에서 패널 호스트명을 설정하면 고객이 panel.yourcompany.com에 접속하여 귀하의 로고와 색상을 보게 됩니다. 동일한 패널이지만 주소는 귀하의 것입니다. | | 자사 웹사이트 | WordPress 플러그인을 통해 사이트에 도메인 검색 기능과 원클릭 로그인 링크를 추가하고, 자체 WooCommerce 결제 창을 통해 주문을 처리할 수 있습니다. | | 자사 빌링 패널 | WHMCS 또는 HostBill이 프론트엔드 역할을 유지하며, 그 뒤에서 모듈이 프로비저닝을 수행하고 클라이언트 영역의 버튼을 통해 호스팅에 즉시 로그인됩니다. |
⛔ 어떤 방식을 선택하든 고객에 대한 거래 당사자는 귀하입니다. 가격, 청구서, 부가세 번호, 결제 대행사 모두 귀하의 것입니다. 당사는 월 1회 도매가로 귀하에게 청구합니다.
패널 호스트명을 설정한 후에는 WordPress 플러그인의 패널 주소(Panel address) 필드에만 입력해야 하며, 다른 곳에는 입력하지 마십시오. 이 API가 생성하는 로그인 링크는 해당 주소를 자동으로 따릅니다.
4가지 연동 방식
연동에는 4가지 방식이 있으며, 내부적으로는 모두 동일한 작업을 수행합니다.
| | 용도 | |---|---| | WHMCS 모듈 | WHMCS 쇼핑몰 | | HostBill 모듈 | HostBill 쇼핑몰 | | WordPress 플러그인 | 자체 WordPress 또는 WooCommerce 사이트에서 판매 | | API | 기타 모든 방식 (Blesta, 자체 시스템, 크론 스크립트) |
1. API 키 발급받기
대시보드에서 API 키(API keys)로 이동하여 키를 생성하십시오. 필요한 권한만 부여해야 합니다.
| 권한 | 용도 | |---|---| | org.read | 고객 계정 읽기 | | sites.create | 사이트 프로비저닝 | | sites.view | 서비스 읽기 | | sites.delete | 해지 | | reseller.view | 서비스 목록 및 사용량 읽기 | | reseller.provision | 클라이언트 일시 중지, 해제 및 로그인 |
⛔ 통합 시스템에 reseller.manage 권한을 부여하지 마십시오. 이 권한은 가격표와 자체 결제 게이트웨이 자격 증명을 수정합니다. 빌링 패널이나 웹사이트에 입력하는 API 키에 이 권한이 필요하지 않도록 reseller.provision이 존재합니다.
API 키는 한 번만 표시됩니다. 웹 서버가 제공하는 파일에는 절대 저장하지 말고, 다른 자격 증명을 안전하게 보관하는 곳에 저장하십시오.
2. 첫 번째 API 호출하기
curl https://api.zinndigital.com/v1/reseller/services \
-H "Authorization: Bearer zdk_live_…"이 요청은 프로비저닝한 모든 서비스를 사이트당 한 행씩 반환하며, 소속된 고객, 상태, 청구 금액 정보를 포함합니다. 신규 계정의 경우 빈 목록이 반환되며, 이는 오류가 아닌 정상적인 응답입니다.
3. 6번의 호출로 완료하는 전체 연동
WHEN CALL
주문이 결제됨 POST /v1/orgs 고객당 1회
POST /v1/sites 서비스당 1회
미결제 상태 POST /v1/reseller/services/{siteId}/suspend
결제 완료 POST /v1/reseller/services/{siteId}/unsuspend
취소됨 DELETE /v1/sites/{siteId}
"호스팅 로그인" POST /v1/reseller/services/{siteId}/sso프로비저닝은 두 번의 호출로 이루어지며, 키 값이 중요합니다.
# 1. 고객 계정 — 귀하의 고객 ID(YOUR customer 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(YOUR service 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"}'잘못 구현하면 비용이 발생하는 두 가지 규칙
- 계정은 고객(CUSTOMER)을 기준으로, 사이트는 서비스(SERVICE)를 기준으로 키를 지정하십시오. 고객의 두 번째 주문은 기존에 보유한 계정에 등록되어야 합니다. 둘 다 서비스 기준으로 키를 지정하면 한 명의 고객이 연관 없는 3개의 계정과 3개의 별도 패널을 갖게 됩니다.
- 모든
POST요청에 해당 항목에 대한 귀하의 ID로 생성된Idempotency-Key를 전송하십시오. 모든 빌링 시스템은 재시도를 수행합니다. 게이트웨이 콜백이 두 번 도착하거나, 관리자가 실패한 프로비저닝을 다시 실행하거나, 고객이 더블 클릭을 할 수 있습니다. 키가 없으면 두 번째 시도에서 두 번째 사이트가 생성되며 이에 대한 비용이 청구됩니다.
단순화해서는 안 되는 세 가지 응답
unsuspend가409를 반환할 수 있습니다. 이는 당사 어뷰징 전담팀이 해당 사이트를 보류 중임을 의미하며, 귀하의 문제가 아닙니다. 메시지를 그대로 표시하고 재시도하지 마십시오.- **해지(Terminating)는 삭제를 예약하는 것이며 즉시 실행되지 않습니다.** 날짜는
pending_deletion_at으로 반환됩니다. 데이터가 아직 삭제되지 않았는데 고객에게 이미 삭제되었다고 알리는 것은 아무 말도 하지 않는 것보다 못합니다. disk_used_bytes는null일 수 있으며, null은 0이 아닙니다. 측정할 수 없었다는 의미이며 사용량이 없다는 뜻이 아닙니다. 이 값은 건너뛰고 자체 기록에0으로 기록하지 마십시오. 측정값이 없는 사이트에 대해 고객에게 초록색 사용량 바가 표시되는 오류를 방지할 수 있습니다.
4. 클라이언트 로그인 처리
POST /v1/reseller/services/{siteId}/sso는 클라이언트가 별도의 로그인 과정 없이 자신의 계정으로 바로 접속할 수 있는 일회용 URL을 반환합니다.
⛔ 페이지를 렌더링할 때가 아니라 사용자가 클릭할 때 생성하십시오. 해당 링크는 일회용이며 몇 분 내에 만료되므로, 페이지에 하드코딩된 링크는 첫 번째 페이지 조회 시 소모되어 귀하와 브라우저 사이의 모든 캐시에 남게 됩니다.
5. 대신 모듈 설치하기
- WHMCS — 모듈을
modules/servers/zinn/에 복사하고, 비밀번호(Password)가 API 키인 서버를 추가한 후 제품에서 제품 라인을 설정합니다. 연결 테스트(Test Connection)를 누르면 실제 API 호출이 수행되고 플랫폼의 응답 결과가 표시됩니다. - 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>에서 확인할 수 있습니다.