자체 시스템에서 Zinn® 호스팅 판매하기

귀하는 당사의 호스팅을 재판매합니다. 고객은 귀하의 고객이며, 가격, 청구서, 결제 대행사 모두 귀하의 것입니다. 빌링 패널, 자체 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"}'

잘못 구현하면 비용이 발생하는 두 가지 규칙

1. 계정은 고객(CUSTOMER)을 기준으로, 사이트는 서비스(SERVICE)를 기준으로 키를 지정하십시오. 고객의 두 번째 주문은 기존에 보유한 계정에 등록되어야 합니다. 둘 다 서비스 기준으로 키를 지정하면 한 명의 고객이 연관 없는 3개의 계정과 3개의 별도 패널을 갖게 됩니다.
2. 모든 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>에서 확인할 수 있습니다.