飞创 Fitron

主题

IPC 云端通信：API 清单与报文示例 ​

API 总清单 ​

IPC → FCC（中心寻址） ​

方法路径说明
POSThttps://fcc-api.fitron.vip/device/locate首启寻址：获取 CPC baseUrl

IPC → CPC（客户私有云） ​

方法路径阶段说明
POST{cpc_url}/v1/ipc/activation/check-in注册设备报到并获取 MQTT 参数
POST{cpc_url}/v1/ipc/report信息上报 / 配置更新 / 日常运行 / 断网补偿统一接收 IPC 上行消息，通过 Body type 区分
GET{cpc_url}/v1/ipc/config配置更新下载最新配置

上行消息 type 取值 ​

type阶段说明
report:device:discovery信息上报上报控制器/传感器发现结果
result:config:acceptance配置更新回传配置校验结果
report:device:heartbeat日常运行心跳上报
report:device:state日常运行状态快照上报
report:face:scan日常运行扫脸等事件上报
result:{target}:{action}日常运行控制/人脸等指令执行结果
report:device:compensate断网补偿断网期间缓存记录批量补传

下行消息 type 取值（MQTT） ​

type说明
control:{target}:{action}控制指令（如 control:door:open）
control:config:update配置更新通知
control:face:download / delete / update人脸管理指令

CPC → FCC（跨云同步） ​

方法路径说明
POSThttps://fcc-api.fitron.vip/cpc/sn-secrets按 SN 跨云拉取 SN_Secret
POSThttps://fcc-api.fitron.vip/cpc/store-revenue-reports门店收入上报

报文示例 ​

HTTP 请求格式约定 ​

IPC 的 HTTP 请求统一拆成两部分：

  • Header：X-SN、X-Request-ID、X-Timestamp、X-Nonce、X-Signature
  • Body：消息通用格式 JSON（见 Topic 与消息体规范）

签名原文格式：uppercase(SN) + ":" + TIMESTAMP + ":" + NONCE + ":" + BODY

约束：

  • BODY 不允许包含换行；参与签名前去除首尾空格
  • Header 已带的字段，Body 可以省略（推荐省略）
  • 若 Body 仍包含 sn / timestamp，必须与 Header 一致

中心寻址（IPC → FCC） ​

请求 Header（示例）：

http
POST https://fcc-api.fitron.vip/device/locate HTTP/1.1
Content-Type: application/json
X-SN: FT-A1B2C3D4-9F2E
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Timestamp: 1768617000
X-Nonce: a1b2c3d4e5f67890a1b2c3d4e5f67890
X-Signature: 7f8e9d6c5b4a3210fedcba9876543210abcdef0123456789abcdef0123456789

请求 Body（示例）：

json
{
  "sn": "FT-A1B2C3D4-9F2E"
}

响应：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "base_url": "https://cpc.example.com"
  }
}

设备报到（IPC → CPC） ​

请求 Header（示例）：

http
X-SN: FT-A1B2C3D4-9F2E
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Timestamp: 1768617010
X-Nonce: a1b2c3d4e5f67890a1b2c3d4e5f67890
X-Signature: 7f8e9d6c5b4a3210fedcba9876543210abcdef0123456789abcdef0123456789

请求 Body（示例）：

json
{
  "hardware": {
    "cpu_serial": "RK3576-001",
    "mac": "AA:BB:CC:DD:EE:FF",
    "fw_version": "2.0.0"
  }
}

响应：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "device_name": "FT-A1B2C3D4-9F2E",
    "product_id": "PROD_xxx",
    "device_secret": "xxxx",
    "mqtt_host": "PROD_xxx.iotcloud.tencentdevices.com",
    "mqtt_port": 8883
  }
}

配置下载（IPC → CPC） ​

请求：

http
GET {cpc_url}/v1/ipc/config?sn=FT-A1B2C3D4-9F2E&version=13

X-SN: FT-A1B2C3D4-9F2E
X-Request-ID: d2e3f4a5-b6c7-8901-defa-012345678901
X-Timestamp: 1768617100
X-Nonce: 1234abcd5678ef901234abcd5678ef90
X-Signature: <签名值，GET 请求 BODY 为空字符串>

响应：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "config_version": 13,
    "config_hash": "sha256:abc123...",
    "config_data": {
      "heartbeat_interval": 30,
      "offline_buffer_size": 1000
    }
  }
}

心跳上报（IPC → CPC） ​

请求 Header（示例）：

http
X-SN: FT-A1B2C3D4-9F2E
X-Request-ID: b4c5d6e7-f8a9-0123-bcde-234567890123
X-Timestamp: 1768617100
X-Nonce: 1234abcd5678ef901234abcd5678ef90
X-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

请求 Body（示例）：

json
{
  "type": "report:device:heartbeat",
  "msg_id": "b4c5d6e7-f8a9-0123-bcde-234567890123",
  "timestamp": 1768617100,
  "sn": "FT-A1B2C3D4-9F2E",
  "data": {
    "status": "online",
    "software_version": "2.0.0",
    "config_version": 13
  }
}

控制结果上报（IPC → CPC） ​

请求 Header（示例）：

http
X-SN: FT-A1B2C3D4-9F2E
X-Request-ID: b4c5d6e7-f8a9-0123-bcde-234567890123
X-Timestamp: 1768617101
X-Nonce: 5678ef901234abcd5678ef901234abcd
X-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

请求 Body（示例）：

json
{
  "type": "result:door:open",
  "msg_id": "b4c5d6e7-f8a9-0123-bcde-234567890123",
  "reply_msg_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "timestamp": 1768617101,
  "sn": "FT-A1B2C3D4-9F2E",
  "data": {
    "result": "success",
    "error_code": 0,
    "error_message": "",
    "door": "A",
    "state": "open",
    "locked": false
  }
}

断网补偿上报（IPC → CPC） ​

请求 Header（示例）：

http
X-SN: FT-A1B2C3D4-9F2E
X-Request-ID: e3f4a5b6-c7d8-9012-efab-123456789012
X-Timestamp: 1768617300
X-Nonce: abcd1234efab5678abcd1234efab5678
X-Signature: fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210

请求 Body（示例）：

json
{
  "type": "report:device:compensate",
  "msg_id": "e3f4a5b6-c7d8-9012-efab-123456789012",
  "timestamp": 1768617300,
  "sn": "FT-A1B2C3D4-9F2E",
  "data": {
    "offline_from": 1768617000,
    "offline_until": 1768617300,
    "record_count": 3,
    "records": []
  }
}

飞创 Fitron 内部规划文档