022coze-pos API 接口文档

POS收银软件与服务网站对接接口

基础URL: https://www.022coze.cn

POST/api/version/publish

POS发版推送新版本信息

请求参数:

参数名	必填	类型	说明
version_number	必填	string	版本号
changelog	必填	string	更新日志
download_url	必填	string	下载地址
publish_type	可选	string	版本类型: stable/dev
publisher	可选	string	发布者

返回示例:

{ success: true, data: { id, version_number, changelog, download_url, is_active, publish_type, created_at } }

GET/api/version/latest

获取最新发布的版本信息

返回示例:

{ data: { id, version_number, changelog, download_url, is_active, created_at } }

GET/api/version

获取所有版本历史列表

返回示例:

{ data: [{ id, version_number, changelog, download_url, is_active, created_at }] }

POST/api/heartbeat

POS服务端定时心跳上报，监控软件运行状态

请求参数:

参数名	必填	类型	说明
client_id	必填	string	客户端唯一标识
software_version	必填	string	软件版本
os_info	可选	string	操作系统信息
run_status	可选	string	运行状态: running/stopped/error
memory_usage	可选	string	内存使用情况
database_status	可选	string	数据库状态
api_connection	可选	string	API连接状态
extra_info	可选	string	其他信息

返回示例:

{ success: true, data: { id, client_id, software_version, os_info, run_status, created_at } }

POST/api/feedback

POS客户端提交Bug或需求反馈

请求参数:

参数名	必填	类型	说明
client_id	必填	string	客户端唯一标识
type	必填	string	类型: bug/feature
title	必填	string	反馈标题
description	可选	string	详细描述
priority	可选	string	优先级: high/medium/low
contact_info	可选	string	联系方式
attachment_url	可选	string	附件链接

返回示例:

{ success: true, data: { id, client_id, feedback_type, title, description, status, created_at } }

GET/api/feedback

获取所有反馈列表

返回示例:

{ data: [{ id, client_id, feedback_type, title, status, priority, created_at }] }

GET/api/feedback/{id}

查询指定反馈的处理状态

请求参数:

参数名	必填	类型	说明
id	必填	number	反馈ID（URL路径参数）

返回示例:

{ data: { id, feedback_type, title, status, admin_reply, resolved_at } }

GET/api/clients

获取所有客户端及心跳状态

返回示例:

{ data: [{ id, client_id, software_version, last_active_at, run_status, total_heartbeats }] }

完整接口JSON（可直接复制）

{
  "baseUrl": "https://www.022coze.cn",
  "interfaces": [
    {
      "name": "版本发布",
      "path": "/api/version/publish",
      "method": "POST",
      "description": "POS发版推送新版本信息",
      "params": [
        {
          "name": "version_number",
          "required": true,
          "type": "string",
          "desc": "版本号"
        },
        {
          "name": "changelog",
          "required": true,
          "type": "string",
          "desc": "更新日志"
        },
        {
          "name": "download_url",
          "required": true,
          "type": "string",
          "desc": "下载地址"
        },
        {
          "name": "publish_type",
          "required": false,
          "type": "string",
          "desc": "版本类型: stable/dev"
        },
        {
          "name": "publisher",
          "required": false,
          "type": "string",
          "desc": "发布者"
        }
      ],
      "returns": "{ success: true, data: { id, version_number, changelog, download_url, is_active, publish_type, created_at } }"
    },
    {
      "name": "获取最新版本",
      "path": "/api/version/latest",
      "method": "GET",
      "description": "获取最新发布的版本信息",
      "params": [],
      "returns": "{ data: { id, version_number, changelog, download_url, is_active, created_at } }"
    },
    {
      "name": "获取版本列表",
      "path": "/api/version",
      "method": "GET",
      "description": "获取所有版本历史列表",
      "params": [],
      "returns": "{ data: [{ id, version_number, changelog, download_url, is_active, created_at }] }"
    },
    {
      "name": "心跳上报",
      "path": "/api/heartbeat",
      "method": "POST",
      "description": "POS服务端定时心跳上报，监控软件运行状态",
      "params": [
        {
          "name": "client_id",
          "required": true,
          "type": "string",
          "desc": "客户端唯一标识"
        },
        {
          "name": "software_version",
          "required": true,
          "type": "string",
          "desc": "软件版本"
        },
        {
          "name": "os_info",
          "required": false,
          "type": "string",
          "desc": "操作系统信息"
        },
        {
          "name": "run_status",
          "required": false,
          "type": "string",
          "desc": "运行状态: running/stopped/error"
        },
        {
          "name": "memory_usage",
          "required": false,
          "type": "string",
          "desc": "内存使用情况"
        },
        {
          "name": "database_status",
          "required": false,
          "type": "string",
          "desc": "数据库状态"
        },
        {
          "name": "api_connection",
          "required": false,
          "type": "string",
          "desc": "API连接状态"
        },
        {
          "name": "extra_info",
          "required": false,
          "type": "string",
          "desc": "其他信息"
        }
      ],
      "returns": "{ success: true, data: { id, client_id, software_version, os_info, run_status, created_at } }"
    },
    {
      "name": "提交反馈",
      "path": "/api/feedback",
      "method": "POST",
      "description": "POS客户端提交Bug或需求反馈",
      "params": [
        {
          "name": "client_id",
          "required": true,
          "type": "string",
          "desc": "客户端唯一标识"
        },
        {
          "name": "type",
          "required": true,
          "type": "string",
          "desc": "类型: bug/feature"
        },
        {
          "name": "title",
          "required": true,
          "type": "string",
          "desc": "反馈标题"
        },
        {
          "name": "description",
          "required": false,
          "type": "string",
          "desc": "详细描述"
        },
        {
          "name": "priority",
          "required": false,
          "type": "string",
          "desc": "优先级: high/medium/low"
        },
        {
          "name": "contact_info",
          "required": false,
          "type": "string",
          "desc": "联系方式"
        },
        {
          "name": "attachment_url",
          "required": false,
          "type": "string",
          "desc": "附件链接"
        }
      ],
      "returns": "{ success: true, data: { id, client_id, feedback_type, title, description, status, created_at } }"
    },
    {
      "name": "获取反馈列表",
      "path": "/api/feedback",
      "method": "GET",
      "description": "获取所有反馈列表",
      "params": [],
      "returns": "{ data: [{ id, client_id, feedback_type, title, status, priority, created_at }] }"
    },
    {
      "name": "查询反馈状态",
      "path": "/api/feedback/{id}",
      "method": "GET",
      "description": "查询指定反馈的处理状态",
      "params": [
        {
          "name": "id",
          "required": true,
          "type": "number",
          "desc": "反馈ID（URL路径参数）"
        }
      ],
      "returns": "{ data: { id, feedback_type, title, status, admin_reply, resolved_at } }"
    },
    {
      "name": "获取客户端列表",
      "path": "/api/clients",
      "method": "GET",
      "description": "获取所有客户端及心跳状态",
      "params": [],
      "returns": "{ data: [{ id, client_id, software_version, last_active_at, run_status, total_heartbeats }] }"
    }
  ]
}

使用说明

• 所有POST请求需设置 Content-Type: application/json
• client_id 建议使用设备唯一标识（如MAC地址+时间戳）
• 心跳上报建议每5分钟调用一次
• 反馈提交后可通过 GET /api/feedback/[id] 查询处理状态