通知中心

查询站内通知列表、未读数、标记已读——覆盖系统公告、工单回复、内测结果等通知类型。

通知中心接口均属于管理接口：鉴权方式为登录会话（或用户 access token）+ Jimu-Api-User 请求头，不接受 sk- API 令牌本身，详见鉴权与令牌。错误响应为管理接口形态（success/message），见错误处理与请求追踪。

端点总览

方法	路径	说明
`GET`	`/api/notifications/`	分页查询通知列表
`GET`	`/api/notifications/unread-count`	查询未读通知数
`GET`	`/api/notifications/pending-count`	查询待处理事项数（仅对特定角色有意义）
`POST`	`/api/notifications/mark-read`	将全部（或某类）通知标记已读
`POST`	`/api/notifications/:id/read`	将单条通知标记已读

通知类型

systemstring

平台发布的系统公告

ticket_replystring

自己提交的工单收到新回复

ticket_statusstring

自己提交的工单状态发生变更

beta_resultstring

内测申请审批结果

除以上四类面向普通用户的通知外，平台内部还有面向管理员的通知类型（新工单待处理、新内测申请等）。普通用户账号不会看到这两类，但如果你的调用方账号同时具备管理员角色，默认查询会把管理员通知也混进来——用下文的 audience=user 参数明确排除。

查询通知列表

GET/api/notifications/

pageint

页码，从 1 开始

默认值: 1

page_sizeint

每页条数，上限 50（超过按 50 截断）

默认值: 20

statusstring

传 unread 只返回未读通知；不传返回全部

audiencestring

传 user 只返回面向普通用户的四类通知（见上文），排除管理员待办类；不传返回账号可见的全部类型

响应200

{
  "success": true,
  "data": [
    {
      "id": 1024,
      "user_id": 1001,
      "type": "ticket_reply",
      "title": "工单有新回复",
      "content": "你的工单「无法登录」收到了新回复",
      "target_url": "/tickets/abc123",
      "is_read": false,
      "related_id": 0,
      "created_at": 1753700000
    }
  ],
  "total": 12,
  "unread_count": 3,
  "has_more": true
}

idint

通知 ID

typestring

通知类型，见上文枚举

title / contentstring

标题与正文

target_urlstring

点击通知后的跳转路径（站内相对路径，如 /tickets/abc123），为空则不可跳转

is_readbool

是否已读

related_idint

关联对象 ID（如工单 ID），0 表示无关联对象；跳转应优先用 target_url，related_id 仅在 target_url 为空时作为兜底参考

created_atint64

创建时间（Unix 秒）

响应额外带出 total（总条数）、unread_count（未读数，随当前 audience 过滤条件计算）、 has_more（是否还有下一页），首次打开通知面板时无需再单独调未读数接口。

查询未读数

GET/api/notifications/unread-count

audiencestring

传 user 只统计面向普通用户的四类；不传统计账号可见的全部类型

响应200

{ "success": true, "data": 3 }

查询待处理事项数

GET/api/notifications/pending-count

无请求参数。返回值针对具备管理员角色的账号才有实际意义（未处理工单数 + 未处理内测申请数），普通用户账号调用恒返回 0。

响应200

{ "success": true, "data": 0 }

标记全部已读

POST/api/notifications/mark-read

audiencestring

传 user 只标记面向普通用户的四类为已读，不影响管理员待办类；不传标记账号可见的全部类型

无请求体。

响应200

{ "success": true, "message": "已全部标记为已读" }

不带 audience=user 调用时，若当前账号同时具备管理员角色，会把管理员待办类通知也一并标记已读。面向普通用户场景（如官网通知铃铛）务必带上 audience=user，避免误清管理员的未处理提醒。

标记单条已读

POST/api/notifications/{id}/read

{id} 为通知 ID。无请求体。

响应200

{ "success": true, "message": "已标记为已读" }

{id} 非正整数或不存在时返回：

{ "success": false, "message": "无效的通知 ID" }

请求示例

# 查询未读数（普通用户视角）
curl "https://api.jimu.chat/api/notifications/unread-count?audience=user" \
  -H "Cookie: session=..." -H "Jimu-Api-User: 1001"

# 查询列表第一页
curl "https://api.jimu.chat/api/notifications/?page=1&page_size=20&audience=user" \
  -H "Cookie: session=..." -H "Jimu-Api-User: 1001"

# 标记单条已读
curl -X POST "https://api.jimu.chat/api/notifications/1024/read" \
  -H "Cookie: session=..." -H "Jimu-Api-User: 1001"

# 全部标记已读
curl -X POST "https://api.jimu.chat/api/notifications/mark-read?audience=user" \
  -H "Cookie: session=..." -H "Jimu-Api-User: 1001"

import requests

s = requests.Session()
s.cookies.set("session", "...")
headers = {"Jimu-Api-User": "1001"}

unread = s.get(
    "https://api.jimu.chat/api/notifications/unread-count",
    params={"audience": "user"}, headers=headers,
).json()["data"]
print("未读数:", unread)

items = s.get(
    "https://api.jimu.chat/api/notifications/",
    params={"page": 1, "page_size": 20, "audience": "user"}, headers=headers,
).json()["data"]
for n in items:
    print(n["id"], n["title"], n["is_read"])

const headers = { Cookie: "session=...", "Jimu-Api-User": "1001" };

const unreadRes = await fetch(
  "https://api.jimu.chat/api/notifications/unread-count?audience=user",
  { headers },
).then((r) => r.json());
console.log("未读数:", unreadRes.data);

const listRes = await fetch(
  "https://api.jimu.chat/api/notifications/?page=1&page_size=20&audience=user",
  { headers },
).then((r) => r.json());
console.log(listRes.data);

额度查询（OpenAI 兼容）

OpenAI Dashboard Billing 兼容端点——第三方客户端探测账号额度与用量的标准接口。

钱包与套餐包

查询账号钱包余额与当前套餐状态、管理限时额度包（删除已耗尽的包、切换优先扣费）。