도메인 구매 및 갱신
domains 카테고리의 API 작업 10개를 다룹니다.
| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | /v1/orgs/{orgSlug}/domains | org의 도메인(runlot domains list) |
| POST | /v1/orgs/{orgSlug}/domains | 도메인 구매(runlot domains buy) |
| POST | /v1/orgs/{orgSlug}/domains/check | 도메인 이름 조회(runlot domains check) |
| POST | /v1/orgs/{orgSlug}/domains/import | 소유한 도메인 가져오기(runlot domains import) |
| GET | /v1/orgs/{orgSlug}/domains/{name} | 도메인 정보 및 최근 변경 이력(runlot domains show) |
| POST | /v1/orgs/{orgSlug}/domains/{name}/renew | 갱신합니다(runlot domains renew) |
| POST | /v1/orgs/{orgSlug}/domains/{name}/auto-renew | 자동 갱신 설정을 변경합니다 |
| POST | /v1/orgs/{orgSlug}/domains/{name}/lock | 이전 잠금을 켜고 끕니다(runlot domains lock|unlock) |
| POST | /v1/orgs/{orgSlug}/domains/{name}/auth-code | 이전 인증 코드를 확인합니다(runlot domains auth-code) |
| POST | /v1/orgs/{orgSlug}/domains/{name}/sync | 레지스트라가 지금 이 값을 다시 읽습니다 |
GET /v1/orgs/{orgSlug}/domains
viewer 이상이 필요합니다.
operationId listDomains
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 목록 조회 | DomainList |
| 403 | — | — |
| 404 | — | — |
| 503 | no_core — cp-public이 cp-core 없이 시작됨 | Error |
POST /v1/orgs/{orgSlug}/domains
admin 이상 — 이 작업은 비용이 발생합니다. domain.purchase로 감사 기록됩니다(연락처는 보관되지 않습니다: 감사 로그는 삭제할 수 없고, 연락처는 개인정보이기 때문입니다).
등록 직후 NS는 Runlot의 네임서버(ns1~3.runlot.app)로 설정됩니다. 따라서 소유권 확인 절차가 필요 없으며, 구매 직후 바로 앱을 연결할 수 있습니다. ICANN 확인 이메일은 contact 주소로 발송됩니다: 등록 전에 화면에서 이를 반드시 안내해야 합니다(§5.5).
동일한 요청을 다시 보내도 안전합니다. 완료된 도메인의 경우 200을 반환하며, 중간에 중단된 구매는 멈춘 단계부터 재개됩니다.
operationId purchaseDomain
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 이미 구매된 도메인(멱등) | Domain |
| 201 | 구매 완료 | Domain |
| 400 | — | — |
| 402 | payment_failed — 결제가 거부됨 | Error |
| 403 | — | — |
| 409 | domain_taken·domain_unavailable | Error |
| 422 | registrar_rejected — 레지스트라가 요청 값(연락처 정보 등)을 거부했습니다. 등록이 진행되지 않았으며, 재시도해도 소용없습니다. 입력을 수정한 요청은 새로운 행이어야 합니다. | Error |
| 502 | saga_incomplete, registrar_error — 재전송하면 멈춘 지점부터 이어집니다. 엣지(Cloudflare)가 502의 본문을 자체 HTML로 대체합니다 — 브라우저 클라이언트는 code를 받지 못합니다. 서버는 재시도로 해결되지 않는 실패는 여기서 보내지 않습니다. | Error |
| 503 | no_core·registrar_not_configured·dns_not_configured | Error |
POST /v1/orgs/{orgSlug}/domains/check
member 이상의 권한이 필요합니다. viewer는 불가한데, 이 호출 하나가 레지스트라 API를 호출하기 때문입니다 — 읽기처럼 보이지만 외부로 나갑니다.
priceCents는 등록 첫 해를 포함하고, renewalCents는 갱신 1년을 포함합니다. 첫 해 할인이 흔하기 때문에 이 둘은 분리되어 있습니다.
operationId checkDomains
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 이름별 사용 가능 여부 | object |
| 400 | — | — |
| 403 | — | — |
| 503 | no_core·registrar_not_configured | Error |
POST /v1/orgs/{orgSlug}/domains/import
admin 이상의 권한이 필요합니다. domain.import로 감사 기록됩니다. 이 작업은 레지스트라를 호출하지 않습니다 — 존을 생성하며, 고객이 자신의 레지스트라에서 NS 레코드를 ns1~3.runlot.app으로 변경하면 그 시점부터 전체 DNS 관리가 우리 쪽으로 넘어옵니다(§5.6).
operationId importDomain
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 이미 가져온 도메인(멱등) | Domain |
| 201 | 가져오기 완료 | Domain |
| 400 | — | — |
| 403 | — | — |
| 409 | domain_taken | Error |
| 503 | no_core·dns_not_configured | Error |
GET /v1/orgs/{orgSlug}/domains/{name}
viewer 이상의 권한이 필요합니다. 다른 org의 이름은 404를 반환합니다.
operationId getDomain
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 도메인 | DomainDetail |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/domains/{name}/renew
admin 이상의 권한이 필요합니다. domain.renew로 감사 기록됩니다.
operationId renewDomain
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 갱신된 도메인 | Domain |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/domains/{name}/auto-renew
관리자 이상 권한이 필요합니다. 등록기관 측 자동 갱신은 계속 켜져 있습니다 (§5.4) — 도메인은 하루만 늦어도 잃을 수 있는 자산이므로, 먼저 갱신한 뒤 나중에 청구합니다. UI는 이 사실을 함께 표시해야 합니다: 그렇지 않으면 고객이 여기서 이 기능을 끄고 "취소했다"고 믿게 됩니다.
operationId setDomainAutoRenew
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 변경된 도메인 | Domain |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/domains/{name}/lock
관리자 이상 권한이 필요합니다. domain.lock으로 감사 기록됩니다.
operationId setDomainLock
요청 본문: application/json · object
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 변경된 도메인 | Domain |
| 400 | — | — |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/domains/{name}/auth-code
관리자 이상 권한이 필요합니다. domain.auth_code로 감사 기록됩니다 — 코드 자체는 감사 로그에 저장되지 않습니다: 코드를 가진 사람이 누구든 도메인을 가져갈 수 있고, 감사 항목은 삭제할 수 없기 때문입니다.
나가는 길은 즉시 열려 있습니다 (§5.5). 이를 막을 수 있는 유일한 것은 ICANN의 60일 등록/이전 잠금이며, 이는 정보 제공용일 뿐입니다.
operationId getDomainAuthCode
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 코드 | object |
| 403 | — | — |
| 404 | — | — |
POST /v1/orgs/{orgSlug}/domains/{name}/sync
멤버 이상 권한이 필요합니다. 만료일, 잠금, NS의 기준 정보는 등록기관입니다. 등록기관이 해당 도메인이 우리 계정에 없다고 응답하면 이는 transferred_out이며, 이전이 완료되었음을 나타내는 유일한 신호입니다.
operationId syncDomain
| 상태 코드 | 설명 | 응답 본문 |
|---|---|---|
| 200 | 일치한 도메인 | Domain |
| 403 | — | — |
| 404 | — | — |