使用开放 API

开放 API 供外部系统查询数据、管理配置、控制设备或创建数据导出任务。调用前准备访问令牌、组织标识和目标资源 ID。

选择集成方式

需求	方式
按需读取实时值、历史数据或资源列表	开放 API
管理项目、设备、点位或下发控制	开放 API
持续接收设备新数据	数据转发
临时下载一段历史记录	数据导出

准备认证与资源标识

1. 由组织所有者创建访问令牌，设置所需角色及项目范围。
2. 从组织基本设置复制组织标识。
3. 从平台或 API 获取项目 ID、设备主键和点位标识，按接口要求选择，详见标识符说明。

发起第一个只读请求

用自己的值替换占位内容，读取项目列表：

curl 'https://dl.yengear.com/api/v2/projects/' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'X-Organization-Slug: your-org-slug'

检查 HTTP 状态、响应中的项目名称和项目 ID。列表未包含某个项目时，核对组织及令牌范围，不要直接提高权限绕过检查。

接口入口

任务	文档
认证、请求头、响应约定	开放 API 概述
组织与令牌管理	组织、组织令牌
项目管理	项目
设备列表、绑定与维护	设备管理
点位配置、阈值与控制	设备数据点
实时数据与上报	设备数据
历史数据文件	数据下载任务

处理失败

• 401：检查认证头、令牌启用状态及有效期。
• 403：检查角色、项目范围及套餐限制。
• 404：核对资源 ID、归属及接口路径。

控制请求超时后，先查状态或记录，避免无条件重复下发。外部系统应记录请求对象、时间和结果，同时兼容新增响应字段；日志不要保存完整令牌。