Registrar
透過 Cloudflare Registrar 搜尋、檢查、註冊及管理網域的 Registrar API。
先決條件（Prerequisites）
使用此 API 之前，請確保：
- Cloudflare 帳戶 — 呼叫端必須擁有有效的 Cloudflare 帳戶。
- 帳單資料（billing profile）— 帳戶必須具備帳單資料，並設有有效且現行的預設付款方式（信用卡或其他受支援的方式）。此項目無法透過 API 設定 — 帳戶擁有者必須先前往 https://dash.cloudflare.com/{account_id}/billing/payment-info 設定帳單，然後才能呼叫 POST /registrations。
- API 驗證 — 使用具備適當 Registrar 權限的 API token 或 API key，以執行您要呼叫的操作。
術語：網域後綴（domain extension）
在本 API 中，「extension」指的是完整網域名稱（fully qualified domain name）中的網域後綴部分 — 即可註冊標籤（registrable label）之後的部分。例如，在 example.co.uk 中，後綴是 co.uk（而非僅 uk）。這涵蓋 com 等頂級網域（top-level domain），以及 co.uk 等多層後綴。此用法與「extension」一詞的其他用法（例如 EPP extensions）有所不同。
支援的後綴（Supported extensions）
此 API 支援以程式化方式註冊 dashboard 體驗所支援的所有後綴，但以下情況除外：
giving, mom, inc, lol, sh, link, cc, new
Cloudflare Registrar 在 dashboard 中支援 400 多種後綴。上述列出的後綴可在 https://dash.cloudflare.com/{account_id}/domains/registrations 註冊。
典型工作流程（Typical workflow）
- 搜尋 — 呼叫 GET /domain-search?q={keyword} 以探索可用的網域。
- 檢查 — 呼叫 POST /domain-check，並傳入候選網域，以確認即時可用性與價格。
- 檢視回應 — 若 registrable 為 false，請檢查 reason，以了解網域是否無法使用、此 API 是否不支援該後綴、Cloudflare Registrar 是否完全不支援該後綴，或該後綴的註冊局（registry）是否已凍結新註冊。
- 處理 premium（溢價）網域 — 若 tier 為 premium，此 API 目前不支援 premium 註冊。請向使用者顯示 premium 價格，但不要針對該網域繼續呼叫 POST /registrations。
- 檢視註冊 schema — 呼叫 GET /extensions/:extension_name，以了解註冊此後綴所需的欄位值。
- 註冊 — 針對受支援且非 premium 的註冊，以所選網域名稱呼叫 POST /registrations。
- 確認完成 — 若回應為 201 Created，表示註冊已在預設逾時內完成，無需輪詢（polling）。
- 需要時進行輪詢 — 若回應為 202 Accepted，請輪詢工作流程回應中的 links.self。
- 因需使用者操作而停止 — 若 state 為 action_required，請停止輪詢，並將 context.action 呈現給使用者。工作流程不會自行完成。
- 受阻時繼續 — 若 state 為 blocked，請繼續輪詢，並告知使用者有第三方（例如後綴的註冊局或轉出註冊商（losing registrar））正在延遲進度。
- 重試前檢視失敗原因 — 若 state 為 failed，請檢視 error.code 與 error.message，然後判斷是否需要使用者操作或重新呼叫 Check。
所有成功的網域註冊均不可退款。一旦註冊工作流程以 state: succeeded 完成，即無法撤銷收費。在呼叫 POST /registrations 之前，請先與使用者確認價格與網域選擇。
變更操作（mutating operations）的預設行為
預設情況下，create 與 update 等變更操作會在操作完成期間，於有界限的伺服器定義時間內保持連線。在大多數情況下，回應會包含已完成的工作流程狀態，無需輪詢。
- 在同步等待視窗內完成：傳回 201（create）或 200（update），並帶有 workflow_status，其中 state 為 succeeded 且 completed 為 true。
- 同步等待視窗後仍在處理中：傳回 202 Accepted，並帶有 completed 為 false 的 workflow_status。請使用 links.self URL 輪詢以確認完成。
非阻塞模式（Non-blocking mode）
若要立即收到 202 Accepted 回應而無需等待，請傳送 Prefer: respond-async 請求標頭（RFC 7240）。伺服器會以 Preference-Applied: respond-async 回應標頭確認。
輪詢（Polling）
當回應為 202 時，請輪詢回應主體中 links.self 所指出的工作流程狀態端點，直到工作流程達到終端狀態（terminal state）或需要使用者操作為止。
代表已註冊網域目前狀態的網域註冊資源（resource）。
網域是否會在到期前自動續約（auto-renew）。
網域註冊的時間。當註冊資源存在時顯示。
包含後綴的完整網域名稱（fully qualified domain name，FQDN）（例如 example.com、mybrand.app）。網域名稱可唯一識別一筆註冊 — 同一個網域不能註冊兩次，因此可自然作為註冊請求的冪等鍵（idempotency key）。
網域註冊到期的時間。當註冊就緒時顯示；僅在 status 為 registration_pending 時可能為 null。
網域是否已鎖定而無法轉移（transfer）。
該註冊目前的 WHOIS 隱私模式。
目前的註冊狀態。
- active：網域已註冊且正常運作
- registration_pending：註冊進行中
- expired：網域已到期
- suspended：網域已被註冊局暫停
- redemption_period：網域處於贖回寬限期（redemption grace period）
- pending_delete：網域正待註冊局刪除
非同步註冊工作流程的狀態。
工作流程是否已達到終端狀態。當 state 為 succeeded 或 failed 時為 true；pending、in_progress、action_required 與 blocked 則為 false。
此狀態資源的 URL。
網域資源的 URL。
工作流程生命週期狀態。
- pending：工作流程已建立，但尚未開始處理。
- in_progress：正在積極處理中。請繼續輪詢 links.self。工作流程設有內部期限，不會無限期待在此狀態。
- action_required：已暫停 — 需要使用者（而非系統）採取行動。請參閱 context.action 了解所需操作。自動輪詢迴圈必須在此狀態時中斷；若無使用者介入，此狀態不會自行解決。
- blocked：由於第三方（例如網域後綴的註冊局或轉出註冊商）的緣故，工作流程無法取得進展。使用者的任何操作都無濟於事。請繼續輪詢 — 當第三方回應時，阻塞狀態可能會解除。
- succeeded：終端狀態。操作已成功完成。completed 將為 true。對於註冊而言，context.registration 包含產生的註冊資源。
- failed：終端狀態。操作失敗。completed 將為 true。原因請參閱 error.code 與 error.message。未經使用者檢視，請勿自動重試。
此工作流程特有的資料。
對於以網域為中心的工作流程，工作流程主體以 context.domain_name 識別。
工作流程進入 failed 狀態時的錯誤詳細資料。具體的錯誤碼與錯誤訊息取決於工作流程類型（registration、update 等）以及底層註冊局的回應。這些工作流程錯誤碼不同於非 2xx 回應所傳回的即時 HTTP 錯誤 errors[].code 值。請將 error.message 呈現給使用者作為參考。
用於識別失敗原因的機器可讀錯誤碼。
人類可讀的失敗說明。可能包含註冊局特有的詳細資料。
包含搜尋結果。
依相關性排序的網域建議陣列。若沒有網域符合搜尋條件，可能為空。
國際化網域名稱（internationalized domain name，IDN）以 punycode 格式表示的完整網域名稱（FQDN）。
根據搜尋資料指出此網域是否看似可用。搜尋結果不具權威性，且可能過時。 - true：網域看似可用。註冊前請使用 POST /domain-check 確認。
- false：搜尋結果中該網域看似不可用。
可註冊網域的年度價格資訊。此物件僅在 registrable 為 true 時存在。所有價格均以每年計算，並以字串形式傳回以保留小數精確度。
registration_cost 與 renewal_cost 通常為相同值，但也可能不同 — 尤其是 premium 網域，註冊局對初次註冊與續約會設定不同的費率。對於多年期註冊（例如 4 年），第一年按 registration_cost 收費，之後每年按 renewal_cost 收費。註冊局價格可能隨時間變動；此處傳回的值反映目前註冊局的費率。Search 與 Check 可能顯示 premium 價格，但此 API 目前不支援 premium 註冊。
價格的 ISO-4217 貨幣代碼（例如「USD」、「EUR」、「GBP」）。
註冊此網域的第一年費用。對於 premium 網域（tier: premium），此價格由註冊局設定，且可能明顯高於標準價格。對於多年期註冊，此費用僅適用於第一年；其後各年按 renewal_cost 收費。
此網域的每年續約費用。適用於多年期註冊第一年之後的每一年，以及其後每年的自動續約。可能與 registration_cost 不同，尤其是 premium 網域，其初次註冊費用通常高於續約費用。
僅在搜尋結果中 registrable 為 false 時顯示。說明為何此網域無法透過此 API 註冊。這些值僅供參考；請使用 POST /domain-check 取得權威狀態。
- extension_not_supported_via_api：Cloudflare Registrar 在 dashboard 中支援此後綴，但尚未開放透過此 API 進行程式化註冊。
- extension_not_supported：Cloudflare Registrar 完全不支援此後綴。
- extension_disallows_registration：該後綴的註冊局已暫時或永久凍結新註冊。
- domain_premium：該網域為 premium 定價。此 API 目前不支援 premium 註冊。
- domain_unavailable：該網域看似無法使用。
此網域的定價等級（pricing tier）。當 registrable 為 true 時必定存在；對大多數網域預設為 standard。當 registrable 為 false 時可能不存在。
- standard：標準註冊局定價
- premium：由註冊局設定較高定價的 premium 網域
包含可用性檢查結果。
網域可用性結果陣列。不支援之後綴上的網域會以 registrable: false 及 reason 欄位包含在內。格式錯誤的網域名稱可能被省略。
國際化網域名稱（IDN）以 punycode 格式表示的完整網域名稱（FQDN）。
根據即時註冊局檢查，指出此網域是否可以透過此 API 以程式化方式註冊。
- true：網域可註冊。將包含 pricing 物件。
- false：網域不可用。原因請參閱 reason 欄位。在某些不可註冊的結果（例如 premium 網域）上，tier 仍可能存在。
可註冊網域的年度價格資訊。此物件僅在 registrable 為 true 時存在。所有價格均以每年計算，並以字串形式傳回以保留小數精確度。
registration_cost 與 renewal_cost 通常為相同值，但也可能不同 — 尤其是 premium 網域，註冊局對初次註冊與續約會設定不同的費率。對於多年期註冊（例如 4 年），第一年按 registration_cost 收費，之後每年按 renewal_cost 收費。註冊局價格可能隨時間變動；此處傳回的值反映目前註冊局的費率。Search 與 Check 可能顯示 premium 價格，但此 API 目前不支援 premium 註冊。
價格的 ISO-4217 貨幣代碼（例如「USD」、「EUR」、「GBP」）。
註冊此網域的第一年費用。對於 premium 網域（tier: premium），此價格由註冊局設定，且可能明顯高於標準價格。對於多年期註冊，此費用僅適用於第一年；其後各年按 renewal_cost 收費。
此網域的每年續約費用。適用於多年期註冊第一年之後的每一年，以及其後每年的自動續約。可能與 registration_cost 不同，尤其是 premium 網域，其初次註冊費用通常高於續約費用。
僅在 registrable 為 false 時顯示。說明為何無法透過此 API 註冊該網域。
- extension_not_supported_via_api：Cloudflare Registrar 在 dashboard 中支援此後綴，但尚未開放透過此 API 進行程式化註冊。使用者可透過 https://dash.cloudflare.com/{account_id}/domains/registrations 註冊。
- extension_not_supported：Cloudflare Registrar 完全不支援此後綴。
- extension_disallows_registration：該後綴的註冊局已暫時或永久凍結新註冊。目前沒有任何註冊商可以在此後綴上註冊網域。
- domain_premium：該網域為 premium 定價。此 API 目前不支援 premium 註冊。
- domain_unavailable：該網域已註冊、已被保留，或因其他原因在受支援的後綴上無法使用。
此網域的定價等級（pricing tier）。當 registrable 為 true 時必定存在；對大多數網域預設為 standard。當 registrable 為 false 時可能不存在。
- standard：標準註冊局定價
- premium：由註冊局設定較高定價的 premium 網域
RegistrarDomains
網域識別碼（identifier）。
顯示網域是否可以轉入 Cloudflare Registrar。
指出該網域是否可以作為新網域註冊。
顯示建立時間。
顯示目前註冊商的名稱。
顯示網域名稱註冊到期的時間。
顯示網域是否已設定 registrar lock（註冊商鎖定）。
顯示網域註冊人（registrant）的聯絡資訊。
地址。
城市。
使用者居住的國家。
使用者的名字（first name）
使用者的姓氏（last name）
組織名稱。
使用者的電話號碼
州／省份。
使用者居住地的郵遞區號或郵政編碼。
聯絡人識別碼。
選填地址行，用於單元、樓層、套房等。
使用者的聯絡電子郵件地址。
聯絡人傳真號碼。
以逗號分隔的註冊局狀態碼清單。完整的狀態碼清單可在 EPP Status Codes 找到。
特定 TLD 目前是否受 Cloudflare Registrar 支援。受支援的 TLD 清單請參閱 TLD Policies。
網域轉入 Cloudflare Registrar 的狀態。
授權表單已由註冊人接受。
顯示與註冊局之間的轉移狀態。
指出是否仍可取消。
隱私防護已在原註冊商（foreign registrar）處停用。
授權碼（auth code）已輸入並驗證。
網域已在原註冊商處解鎖。
最後更新時間。
RegistrarRegistrations
RegistrarRegistration 狀態
RegistrarUpdate 狀態
RegistrarExtensions
包含中繼資料（metadata）與 JSON Schema 文件的後綴條目，用於註冊操作。
後綴中繼資料
後綴的完整名稱。例如「co.uk」或「uk」
後綴的 tld。例如，「co.uk」的 tld 是「uk」；「uk」的 tld 是「uk」
描述此後綴註冊操作預期輸入結構的 JSON Schema。
包含中繼資料（metadata）與 JSON Schema 文件的後綴條目，用於註冊操作。
後綴中繼資料
後綴的完整名稱。例如「co.uk」或「uk」
後綴的 tld。例如，「co.uk」的 tld 是「uk」；「uk」的 tld 是「uk」
描述此後綴註冊操作預期輸入結構的 JSON Schema。