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 所指嘅工作流程狀態 endpoint（端點），直到工作流程去到終端狀態（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。