电传机 HTTP API

电传机用于在用户网页与外部设备之间收发纯文本。设备 ID 全局唯一，首次注册后归属当前 OAuth2 用户，其他用户不能使用或重新注册该 ID。

公共前缀：

https://ydzx.panretro.com/external/api/v1/teleprinter/

所有接口要求 OAuth2 access token 含有 chat scope。可通过 Authorization: Bearer {accessToken} 或 access_token 请求参数传入。

除 poll 外，请求体均为 JSON；成功响应统一为：

{ "code": 200, "msg": "success", "data": {} }

注册电传机

POST /external/api/v1/teleprinter/register
Content-Type: application/json

{ "deviceId": "paper-01", "name": "书房电传机" }

字段	规则
`deviceId`	必填；1–64 位，仅允许字母、数字、`_`、`-`
`name`	必填；1–128 个字符

注册成功后设备立即在线，并更新 lastSeen。同一用户重复注册会更新名称和心跳；已被其他用户注册的 ID 会被拒绝。

心跳与下线

POST /external/api/v1/teleprinter/heartbeat
POST /external/api/v1/teleprinter/offline

{ "deviceId": "paper-01" }

设备应至少每 60 秒调用一次 heartbeat。服务端在最后心跳超过 90 秒时将设备视为离线。正常退出时可调用 offline，使网页立即显示离线。

获取待收文本（设备轮询）

GET /external/api/v1/teleprinter/poll?deviceId=paper-01&limit=50

参数	默认值	说明
`deviceId`	—	已注册且属于当前用户的设备 ID
`limit`	`50`	本次最多取回的消息数，范围 1–100

轮询也会刷新心跳。返回的内容都是从网页发往设备、尚未投递的文本；服务端会在本次返回后标记为已投递。

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1950000000000000001,
      "deviceId": "paper-01",
      "direction": "to_device",
      "content": "测试电文",
      "delivered": 1,
      "createdAt": "2026-08-11T03:00:00.000+00:00"
    }
  ]
}

同步设备发出的文本

POST /external/api/v1/teleprinter/sync
Content-Type: application/json

{ "deviceId": "paper-01", "content": "收到，天气晴朗。" }

该接口保存一条 from_device 消息，同时刷新设备心跳。文本不能为空，最大 2000 字符。

向设备发送文本

POST /external/api/v1/teleprinter/send
Content-Type: application/json

{ "deviceId": "paper-01", "content": "请回传状态。" }

服务端优先通过已连接的电传机 WebSocket 推送；没有可用 WebSocket 时保留在待收队列中，设备可通过 poll 获取。该接口同样只允许向当前用户拥有的设备发送。

注册电传机​

心跳与下线​

获取待收文本（设备轮询）​

同步设备发出的文本​

向设备发送文本​

注册电传机

心跳与下线

获取待收文本（设备轮询）

同步设备发出的文本

向设备发送文本