前言

本文档为互联平台API对接的快速指引，旨在帮助开发者快速完成从环境准备到首次设备/系统对接的全流程操作。本平台以人脸识别技术为核心，支持门禁、访客、会议、梯控、可视对讲、食堂消费、信息发布、智能锁、储物柜等多类人脸识别应用设备/系统对接，核心对接协议采用MQTT协议，数据传输格式统一为JSON。建议开发者结合本文档与《互联平台API文档》核心接口详情，高效完成对接工作。

一、对接前准备

1.1 账号与权限申请

对接前需完成平台开发者账号注册及对接权限申请，步骤如下：

访问互联平台官方管理后台，完成开发者账号注册（需提供企业主体信息、联系人及联系方式）；

登录账号后，进入【开发者中心】-【对接权限申请】模块，选择需对接的应用类型（如门禁、访客、会议、梯控、可视对讲、食堂消费等），提交对接需求说明；

平台审核通过后，将通过邮件发送MQTT连接核心信息（含MQTT服务器地址、端口、产品key、产品secret、用户名、密码）及对接权限范围，请注意妥善保管用户名/密码等敏感信息。

1.2 环境与工具准备

推荐使用以下环境与工具提升对接效率：

开发环境：支持MQTT协议的开发语言及客户端库（如Java-MQTT、C++-mqtt_cpp、Go-eclipse/paho.mqtt.golang等）；

调试工具：MQTT X、EMQ X Dashboard、MQTT.fx等（用于快速测试MQTT连接、主题订阅/发布功能）；

辅助工具：JSON格式化工具（如JSON.cn）、MQTT日志分析工具、网络抓包工具（如Wireshark）。

注意：平台MQTT服务器支持TCP（端口1883）和SSL/TLS加密连接（端口8883），生产环境强烈建议使用SSL/TLS加密连接，避免数据传输泄露。

1.3 核心概念认知

对接前需明确以下核心概念，避免对接异常：

客户端ID（Client ID）：接入平台的设备唯一标识（将设备的MAC地址去掉冒号，作为唯一标识)；

用户名/密码：MQTT连接的认证凭证，用于身份校验，请勿泄露给第三方；

产品key/产品secret：平台为开发者分配的产品接入key和密钥，每个模块一个；

MQTT主题（Topic）：平台与设备/系统数据交互的通道，不同业务场景对应不同主题（如设备状态上报、指令下发等），主题格式详见《互联平台API文档》；

QoS等级：消息传输质量等级，平台支持QoS 0（最多一次）、QoS 1（至少一次），建议信息传输使用QoS 1；

二、核心对接步骤（以门禁设备状态上报为例）

步骤1：建立MQTT连接

设备/系统需先与平台MQTT服务器建立连接，连接参数配置如下：

核心连接参数：
MQTT服务器地址：{平台分配的MQTT服务器域名/IP}

端口：TCP连接用1883，SSL/TLS连接用8883

客户端ID（Client ID）：{去掉冒号的设备MAC地址}

用户名：{平台分配的用户名}

密码：{平台分配的密码}

连接超时时间：建议设置为30秒

心跳包（Keep Alive）：建议设置为60秒

连接示例（C++，基于mqtt_cpp客户端库）：

连接状态校验：
若连接成功，调试工具（如MQTT X）会显示“已连接”状态，平台【开发者中心】-【连接日志】会记录连接成功信息；

10.

若连接失败，可查看错误码Return Code（如rc=4代表用户名/密码错误，rc=5代表Client ID重复），参考“常见问题”模块排查。

步骤2：订阅/发布MQTT主题（设备状态上报）

以门禁设备实时状态上报为例，演示主题订阅/发布流程（主题格式由平台统一定义，需严格遵循）：

核心主题信息：设备状态上报主题：device/设备ID/status/report（需将设备ID替换为实际设备标识，如“device/DOOR_20250601001/status/report”）

平台指令下发主题：device/设备ID/command/receive（设备需订阅此主题，接收平台下发的控制指令，如开门、锁定等）

设备状态上报（发布主题）：

上报数据格式（JSON）：

{
    "app_version": "V1.0.0.0",       // 设备软件版本号
    "device_ip": "192.168.100.100",  // 设备IP地址
    "device_name": "sy_device",     // 设备名称,此项以平台为主
    "device_type": 1,                // 门禁机,
    "device_version": "1108",          // 设备型号
    "mac_address": "AA5056C00001",   // 设备mac地址
    "online": 1,                     // 上下线通知，1=上线，0=离线
    "product_key": "f62f907debbb43e5", // 平台Key标识,平台分配
    "web_proxy_port": 8080,          // 设备本地web代理端口
    "device_factory": "XX厂商",      // 设备厂商
    "brand_name": "XX品牌",          // 品牌名称
    "time": 1594282082123            // 毫秒时间戳
}

发布示例（C++，基于mqtt_cpp客户端库）：

订阅平台指令主题（接收控制指令）：

订阅示例（C++，基于mqtt_cpp客户端库）：

步骤3：对接调试与问题排查

首次对接若出现异常，可按以下步骤排查：

连接异常排查：
检查连接参数：确认MQTT服务器地址、端口、Client ID、用户名/密码是否正确；

检查网络环境：确保设备/系统可正常访问MQTT服务器地址（可通过ping、telnet命令测试网络连通性）；

检查Client ID：若提示“Client ID已存在”，需确认是否有其他设备使用同一Client ID，或联系平台重新分配。

主题订阅/发布异常排查：
检查主题格式：确保主题严格遵循平台定义（如设备ID替换正确、层级分隔符使用“/”）；

检查数据格式：确认上报/接收的JSON数据格式正确（无语法错误、字段完整）；

检查QoS等级：若消息丢失，可尝试将QoS等级从0提升至1。

查看日志：通过平台【开发者中心】-【MQTT日志】模块，查看连接状态、主题交互、数据详情及错误原因。

三、其他重要说明

3.1 消息限流与重试机制

平台对单Client ID的消息发布频率设置限流策略（默认每秒最多发布20条消息），若超过阈值，服务器会暂时屏蔽该Client ID的消息发布。建议设备/系统实现消息重试机制（重试间隔建议设为1-3秒），避免消息拥堵。

3.2 数据格式规范

所有MQTT消息 payload 均为JSON格式，需遵循以下规范：

字段命名：采用下划线命名法（如device_id、report_time），不得使用特殊字符；

日期时间格式：统一为“yyyy-MM-dd HH:mm:ss”（UTC+8时区）；

数值类型：状态码、数值等字段需使用数值类型（如1、0），不得使用字符串类型（如"1"、"0"）。

3.3 版本迭代

平台MQTT对接规则会持续迭代优化，若有重大变更（如主题格式调整、数据字段新增/删除），将提前通过邮件通知开发者，并在文档中标注“变更说明”。建议开发者定期查看《互联平台API文档》更新日志，避免因版本更新导致对接异常。

3.4 技术支持

对接过程中若遇到问题，可通过以下方式获取支持：

查看文档：《互联平台API文档》-【MQTT对接常见问题】模块；

提交工单：通过平台【开发者中心】-【工单管理】提交问题工单（需附上连接参数、日志截图等信息）；

联系客服：发送邮件至luyixing@dingtalk.com（工作日9:00-18:00回复）。

完成以上步骤后，即可基于MQTT协议实现各类设备/系统的对接开发。如需对接门禁、访客、会议等具体业务场景（如访客登记数据上报、会议设备指令交互、食堂消费记录同步等），可参考《互联平台API文档》对应模块的主题定义及数据格式说明。

快速上手

前言#

一、对接前准备#

1.1 账号与权限申请#

1.2 环境与工具准备#

1.3 核心概念认知#

二、核心对接步骤（以门禁设备状态上报为例）#

步骤1：建立MQTT连接#

步骤2：订阅/发布MQTT主题（设备状态上报）#

步骤3：对接调试与问题排查#

三、其他重要说明#

3.1 消息限流与重试机制#

3.2 数据格式规范#

3.3 版本迭代#

3.4 技术支持#

前言