VAO PUSH / 使用指南
开发者 / API
事件走消息接口，持续变化的数据走状态接口。
发送一条消息
在 Web 保存默认接收设备，复制统一自动推送地址；或者使用设备专属地址。手动临时选择设备不会改变默认接收列表。
shell
curl -X POST 'https://push.example.com/v1/push/YOUR_SEND_KEY' \
-H 'Content-Type: application/json' \
--data '{"title":"Album ready","body":"Your weekend photos are ready to view."}'消息独立保存到历史。202 表示已保存并排队，不表示设备已经显示通知。自动消息凭据不能通过正文扩大接收范围，也不能写入卡片数据。
更新数据源的最新状态
在卡片工作台复制外部上报源的专属地址。源写入凭据只更新该数据源，不能读取历史或管理设备。
shell
curl -X PUT 'https://push.example.com/v1/card-data/YOUR_SOURCE_KEY' \
-H 'Content-Type: application/json' \
--data '{"fields":{"progress":{"type":"percent","value":"68"},"status":{"type":"text","value":"In progress"}}}'每次请求整份替换最新状态，不追加普通消息历史，不改变卡片设计。需要完成提醒时，再独立发送一条消息。已有设备状态接口继续兼容，新功能卡片使用工作台的数据源地址。
端点与权限
| 端点 | 用途 |
|---|---|
POST /v1/push/{key} | 消息通知，按凭据限定设备或默认列表 |
PUT /v1/card-data/{source_key} | 更新一个固定数据源 |
PUT /v1/state/{key}/{data_id} | 已有设备数据卡片的兼容接口 |
订阅码用于设备导入已发布卡片，不是写入凭据。Web 管理、消息发送、数据上报与设备读取分别使用各自授权。
集成时请留意
- 发送地址包含秘密，避免出现在公开日志、前端源码或截图中。
- 消息重试建议为同一逻辑请求复用 Idempotency-Key。
- 数值按协议使用十进制字符串，状态请求包含你想保留的全部字段。
- 采集、入队、推送被接受与设备实际显示是不同阶段。
源码与完整协议
公开仓库提供完整 API 协议、卡片描述与接入说明。以上请求仅作格式示例，域名与凭据均为占位内容；使用时请从自己的工作台复制实际地址。