HTTP API

juhe-sync 数据同步服务 HTTP API 端点文档

概述

juhe-sync 提供 RESTful API 用于查询联系人、消息、群聊等数据。默认服务端口为 8070，所有 API 路径以 /api/ 开头。

API 端点

POST /callback

接收 SAAS 平台的回调通知

参数	类型	必填	说明
body	object	是	SAAS 回调数据（JSON 格式）

响应示例

json

{
  "success": true,
  "message": "Callback processed"
}

GET /api/contacts

查询联系人列表

参数	类型	必填	说明
`guid`	string	是	设备 GUID
`page`	number	否	页码，默认 1
`limit`	number	否	每页数量，默认 20
`keyword`	string	否	搜索关键词（姓名/备注）

请求示例

bash

curl "http://localhost:8070/api/contacts?guid=xxx&page=1&limit=10"

响应示例

json

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "user_123",
        "name": "张三",
        "remark": "产品经理",
        "avatar": "https://...",
        "type": "external"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 10
  }
}

GET /api/messages

查询消息记录

参数	类型	必填	说明
`guid`	string	是	设备 GUID
`conversation_id`	string	否	会话 ID（私聊 S:user_id，群聊 R:room_id）
`keyword`	string	否	消息内容关键词
`start_time`	string	否	开始时间（ISO 8601）
`end_time`	string	否	结束时间（ISO 8601）
`page`	number	否	页码，默认 1
`limit`	number	否	每页数量，默认 20

请求示例

bash

curl "http://localhost:8070/api/messages?guid=xxx&conversation_id=S:user_123&page=1&limit=10"

响应示例

json

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg_456",
        "conversation_id": "S:user_123",
        "from": "user_123",
        "content": "你好",
        "timestamp": "2024-01-15T10:30:00Z",
        "type": "text"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 10
  }
}

GET /api/rooms

查询群聊列表

参数	类型	必填	说明
`guid`	string	是	设备 GUID
`page`	number	否	页码，默认 1
`limit`	number	否	每页数量，默认 20

请求示例

bash

curl "http://localhost:8070/api/rooms?guid=xxx&page=1&limit=10"

响应示例

json

{
  "success": true,
  "data": {
    "rooms": [
      {
        "id": "R:room_789",
        "name": "产品讨论群",
        "owner": "user_456",
        "member_count": 128,
        "avatar": "https://..."
      }
    ],
    "total": 20,
    "page": 1,
    "limit": 10
  }
}

GET /api/sync-status

查询数据同步状态

参数	类型	必填	说明
`guid`	string	是	设备 GUID

请求示例

bash

curl "http://localhost:8070/api/sync-status?guid=xxx"

响应示例

json

{
  "success": true,
  "data": {
    "guid": "xxx",
    "status": "syncing",
    "last_sync_time": "2024-01-15T10:30:00Z",
    "contacts_count": 1250,
    "messages_count": 45680,
    "rooms_count": 32
  }
}

错误响应

所有 API 在出错时返回统一格式的错误响应：

json

{
  "success": false,
  "error": "Invalid GUID",
  "code": "INVALID_PARAMS"
}

状态码

200：请求成功
400：请求参数错误
404：资源不存在
500：服务器内部错误