构建你自己的控制界面

拟议的第一版合同将目录资源与账户资源分开。位置和套餐支持配置。服务代表已接受的配置和履行状态。计费包含发票和付款状态。工单支持可追溯的支持对话。网站实现自己的表单和工作区；以下示例是设计合同，不是通往公共 API 的路由。

准备好的身份验证模型在 Authorization 标头中使用 Bearer 令牌。只读目录或服务范围不应能够创建、重建或取消服务。写入范围需要单独的决定和撤销路径。将凭据保存在私有服务器环境中，切勿将秘密令牌嵌入页面或浏览器包中。

GET /v1/services
Authorization: Bearer <private-token>
Accept: application/json

# Proposed scope: services:read

为每个资源使用稳定的标识符，并为支持使用请求 ID。变更调用应使用幂等键，以便重试时可以对账，而不是创建另一个订单。

POST /v1/services
Idempotency-Key: <one-key-per-request>

{
  "plan_id": "umbra-1",
  "location": "iceland",
  "billing_cycle": "monthly",
  "image": "Ubuntu"
}

拟议的账户级速率限制为每分钟 60 次读取和每分钟 20 次写入，突发允许量为这些值的两倍。被拒绝的请求返回 HTTP 429 并带有 Retry-After；自动化应按照指示等待并应用退避。错误应包含稳定的代码、人类可读的消息和 request_id，并移除敏感细节。

{
  "error": {
    "code": "unsupported_location",
    "message": "This plan is not listed in that region.",
    "request_id": "req_example"
  }
}

准备好的 webhook 模型涵盖发票付款、服务就绪、暂停和工单更新。投递应带有事件 ID 和时间戳，并使用私有签名密钥对原始请求正文检查 HMAC-SHA256 签名。拒绝过期或无效签名，对事件 ID 去重，并仅在事件被持久接受后确认。消费者必须容忍乱序和重复投递。

提议的 API 路径包含其主版本。增量更改应保留现有客户端；不兼容的更改需要新版本，并为旧版本提供六个月的退役通知。可用性、SDK 和生产 API 主机只能在集成和安全审查后发布。

账户应用程序具有固定地址支付请求和会过期的服务器 USD 报价。交易观察是仅限服务器的可信集成；没有公共确认端点、已连接的区块链监控或配置工作进程。浏览器轮询读取已登录客户现有的支付状态，无法证明交易。上面说明性的公共 API 和 webhook 契约仍属于未来设计工作。

• 在服务器上保护速率与观测逻辑。
• 将重复使用的收款目的地与经过验证的交易和明确的订单参考关联起来。
• 将已支付和已配置分开；经过验证的交易不得创建虚构的硬件。