​
平台 API 概览

本节为开放平台 API 的总览。完整的接入指南拆为两类：
  • 概念：鉴权、Scope、错误模型、异步回调配置 — 调用前必读
  • 接口文档：每个 endpoint 的字段、请求示例、响应示例 — 编写代码时查阅

​
环境域名

  • 开发环境：https://dev.utmos.dev
  • 生产环境：https://prod.utmos.dev
  • 文档示例默认使用开发环境域名，正式发布时替换为生产域名

​
入门顺序

  1. 鉴权与签名 — 申请 API Key，了解签名计算
  2. Scope 目录 — 确认你的 Key 拥有调用所需的 scope
  3. 错误模型 — 提前掌握错误码与重试策略
  4. 异步回调 — 明确 001 当前实现 callback 配置，不执行 webhook 投递
  5. 进入 接口文档 调试具体 endpoint

​
端到端流程示例

下行命令的典型生命周期：
  1. POST /api/v1/open/downlink/commands 提交命令，返回 command_id
  2. 平台写入 command fact 和 dispatch event，HTTP 202 只表示平台已受理
  3. 平台在事务提交后尝试发布 NATS 事件 tenant.<tenant_id>.command.accepted
  4. 接入方可用 GET /api/v1/open/downlink/commands/{command_id} 查询已受理命令事实和 dispatch 发布状态
  5. 接入方可使用 POST /api/v1/open/objects/presign 为授权对象申请上传或下载预签名 URL

​
接入要求

  • 必备凭据：API ID / API Key
  • 必备字段：vendor、device_id、command_type、payload、idempotency_key
  • 必备能力：处理异步最终一致；受理成功不等于设备执行成功。001 不执行厂商适配器和 webhook 投递 worker。