通用 API 对接指南

本指南适用于任何需要自动查询 Lumio 商品与库存、使用钱包购买、读取服务状态和凭据、续费或执行生命周期操作的外部系统。Lumio 只提供统一的通用 API；商品映射、终端客户订单、前端展示和你向终端客户提供的退款政策由你的系统负责。


1. 接入前准备


API 基础地址固定为 https://lumio.sh/api/v1/integration。

在“账户设置 → API 对接”创建 API Key。完整 Key 只显示一次，请保存在服务端密钥管理系统中。

不要把 Key 写进浏览器、移动 App、公开仓库、日志或发给终端客户。

只授予实际需要的 Scope。具有购买、续费权限的调用会直接扣除当前 Lumio 钱包余额。

所有金额均以最小货币单位表示，例如 12900 表示 USD 129.00；时间使用 ISO 8601。



2. Scope 与能力


catalog:read：读取商品、周期价格和准确库存。

wallet:read：读取钱包可用余额。

purchase:write：报价并购买商品。

service:read：读取购买结果、异步操作和服务状态。

credentials:read：读取已就绪服务的登录凭据。

renewal:write：用 Lumio 钱包续费。

lifecycle:write：暂停、恢复、终止、重启、重置密码和重装。



3. 鉴权与连接测试

每次请求发送 Authorization: Bearer <Lumio API Key>、Accept: application/json 和你生成的唯一 X-Request-Id。有 JSON 请求体时再发送 Content-Type: application/json。

curl -sS https://lumio.sh/api/v1/integration/account \
-H "Authorization: Bearer lumio_live_example.secret" \
-H "Accept: application/json" \
-H "X-Request-Id: partner-connection-0001"
HTTP 200 且响应中的 code=200 表示连接成功。保存返回的 Scope 并确认包含后续流程所需权限。响应外层统一为 {"code":200,"message":"...","data":{...}}；程序应按 HTTP 状态和 data.error 分支，不要匹配可能变化的 message 文案。


4. 商品、库存与钱包


调用 GET /catalog/products 获取 SKU、周期、价格、固定配置和当前库存。

需要详情时调用 GET /catalog/products/{sku}。只能使用接口返回的 SKU、周期、配置和附加项，不要在外部系统中猜测。

购买前调用 GET /wallet 检查 available_cents。页面显示的余额或历史缓存不能代替购买时的实时校验。



5. 报价与购买闭环

先调用 POST /purchases/quote 做只读试算。报价请求不发送 Idempotency-Key：

{
"product_sku": "MAC-MINI-M4-ESSENTIAL",
"billing_cycle": "month",
"quantity": 1,
"configuration": {},
"addon_ids": []
}
向终端客户确认价格后，为这次购买生成并持久保存一个稳定的 external_reference 和一个稳定的 Idempotency-Key。把报价返回的 total_cents 作为 expected_total_cents 回传，它是防止价格变化后意外多扣款的成本上限。

POST /purchases
Idempotency-Key: partner-order-9001-create-v1

{
"external_reference": "partner-order-9001:create:1",
"product_sku": "MAC-MINI-M4-ESSENTIAL",
"billing_cycle": "month",
"quantity": 1,
"configuration": {},
"addon_ids": [],
"expected_total_cents": 12900
}
成功后立即保存 operation_id、Lumio 订单号、账单号和服务编号。若响应时服务仍在开通，轮询 GET /operations/{operation_id}，直到 status=succeeded、needs_attention 或出现明确失败。也可用 GET /purchases/by-reference/{external_reference} 找回原购买。

网络超时不等于购买失败。超时后先按外部单号查找；找不到时必须使用完全相同的请求体、external_reference 和 Idempotency-Key 重发。不要更换编号绕过幂等保护，否则可能造成重复购买或重复扣款。


6. 服务状态与凭据


GET /services/by-reference/{external_reference}：按你的外部购买编号找服务。

GET /services/{serviceId}：读取当前状态、账期、到期时间和凭据是否就绪。

GET /services/{serviceId}/credentials：仅在 credentials_ready=true 后读取。未就绪时等待并重试，不要制造本地假凭据。


凭据属于敏感数据，只能展示给有权访问该服务的终端客户或运维人员。不要写入普通业务日志。服务终止或删除后，凭据不再可用，next_due_at 也会为空。


7. 续费闭环


调用 GET /services/{serviceId}/renewal-quote，保存 current_next_due_at 和 total_cents。

调用 POST /services/{serviceId}/renew，发送稳定的外部续费编号和幂等键，并把报价值作为 expected_next_due_at、expected_total_cents 回传。

保存并轮询返回的 operation_id。只有操作成功且服务的新到期时间已经更新，才把外部订单标记为续费完成。


{
"external_reference": "partner-service-1001:renew:2026-09-02",
"expected_next_due_at": "2026-09-02T00:00:00+00:00",
"expected_total_cents": 9900
}

8. 生命周期与设备操作

以下写操作都必须发送稳定的 external_reference 和 Idempotency-Key，保存返回的 operation_id 并轮询：


POST /services/{serviceId}/suspend：暂停服务。

POST /services/{serviceId}/resume：释放当前 API Key 建立的暂停；若仍有欠费或管理员限制，服务可能继续保持暂停。

POST /services/{serviceId}/actions/reboot：重启设备。

POST /services/{serviceId}/actions/reset-password：请求 Lumio 生成新密码。请求体禁止传入密码；完成后重新读取凭据。

POST /services/{serviceId}/actions/reinstall：请求体必须包含 "confirmation":true。重装会清除设备数据。

POST /services/{serviceId}/terminate：请求体必须包含 "immediate":true。


终止不可逆。终止成功会永久回收服务资源和凭据并放弃本期剩余使用时间，Lumio 不会自动退款或补回钱包。你的系统给终端客户退款也不会反向触发 Lumio 退款；例外只能提交 Lumio 支持人工核对。


9. 错误、限流与安全重试


400/422：修正请求参数或选择；不要原样无限重试。

401/403：停止调用，检查 Key、账户状态和 Scope。

404：核对资源是否属于当前 Key 对应的 Lumio 账户。

409：处理价格、状态、外部编号或幂等冲突；不要换编号强行提交。

429 或带 Retry-After 的 503：等待指定秒数并使用指数退避。

异步操作进入 needs_attention 时停止自动重试，保存 operation_id、X-Request-Id、外部编号和安全错误码供人工排查。



10. 上线检查清单


生产环境只使用服务端密钥存储，并准备 Key 轮换流程。

SKU、周期和固定配置来自实时目录；价格提交带成本上限。

每个写操作先持久化外部编号和幂等键，再发送请求。

购买、续费和生命周期操作都能在进程重启后继续轮询原 operation。

已覆盖连接失败、余额不足、缺货、价格变化、限流、超时、凭据未就绪和 needs_attention。

终端客户界面明确展示扣款、重装清除数据和立即终止不退款的后果。



11. 契约文件与支持

登录 Lumio 后，前往“API 对接”页面下载 OpenAPI 契约和 Postman 集合。正式开发以 OpenAPI 为字段与状态契约，本文用于说明业务闭环。

提交工单时请提供发生时间、接口路径、HTTP 状态、data.error、X-Request-Id、operation_id 和外部编号；不要发送完整 API Key、密码或服务凭据。