第三方对接指南

权威：本目录以当前代码为准（OpenMatterController / OpenMatterHmacFilter、OpenNoticeController / OpenNoticeHmacFilter、OpenKbDocumentController / OpenKbHmacFilter、OpenNotifyController / OpenNotifyHmacFilter、OpenTaskController、sp-auth IdP 端点、出向推送接收约定）。
设计背景（非对接逐步手册）：doc/06 安全、doc/04 数据对接、doc/07 SSO 方案、doc/14 出向同步、doc/16 待办与站内通知。
Knife4j：运行时字段级文档见 /doc.html；本目录面向集成方联调与落地。

快速选型

你要做的事	鉴权	文档
待办 + 公告推送（选型与联调手册）	HMAC	08-待办与通知公告-集成手册.md
向门户推送待办 / 流程知会等事项	HMAC	02-事项推送-HMAC.md
向门户推送平台通知公告（广播）	HMAC	07-通知公告推送-HMAC.md
向门户推送知识库文档	HMAC（同上）	06-知识库-HMAC.md
委托平台按模板代发短信/微信/邮件	HMAC	10-模板消息代发-HMAC.md
在门户任务中心创建任务、汇报进度、完成	OAuth2 Bearer + `api:write` / `api:read`	03-任务中心-OAuth2.md
用门户账号登录你的系统（门户作 IdP）	OAuth2 / OIDC / CAS / SAML	04-SSO接入-IdP.md
接收门户推过来的组织 / 用户变更	你方 HTTP 接口 + 约定鉴权/加密	05-接收出向同步.md
按门户配置查询第三方库视图映射 JSON	HMAC	09-数据服务-JDBC视图-HMAC.md

接入前先读 01-接入准备.md（Client 注册、system_code、统一响应）。

SDK / Demo 下载

可下载样例（Java JDK17+ 标准库 / Bash），源码亦在 sdk/：

包	说明	下载
HMAC Java	签名 + 事项/公告/知识库/数据/模板消息	/downloads/hmac-java.zip
任务 OAuth2 Java	授权码换票 + `/api/open/tasks`	/downloads/oauth2-tasks-java.zip
SSO OAuth2 客户端 Java	精简 SP（authorize→userinfo）	/downloads/sso-oauth2-client-java.zip
Bash HMAC	curl 联调脚本	/downloads/bash-hmac-scripts.zip

说明见 sdk/README.md。不含完整 ssoDemo；无 client_credentials。

文件	内容
01-接入准备.md	Client、`system_code`、ApiResult、公共约束
08-待办与通知公告-集成手册.md	推荐：待办/公告选型、签名、双管道示例与检查清单
02-事项推送-HMAC.md	`/api/open/matters/**` 字段级
07-通知公告推送-HMAC.md	`/api/open/notices/**` 字段级
03-任务中心-OAuth2.md	`/api/open/tasks/**` 与 scope
04-SSO接入-IdP.md	门户作 IdP 的端点清单（细节链 `doc/07`）
05-接收出向同步.md	接收方须实现什么（细节链 `doc/14`）
06-知识库-HMAC.md	`/api/open/kb/documents/**` 签名与 upsert/status/delete
09-数据服务-JDBC视图-HMAC.md	`/api/open/data/query` 视图映射 JSON
10-模板消息代发-HMAC.md	`/api/open/notify/**` 模板代发短信/微信/邮件

非目标（勿当作第三方入站面）

路径 / 能力	说明
`/api/system/`、`/api/portal/`、`/api/tasks`（非 open）	门户会话（Sa-Token），OAuth2 Token 不可访问
`/api/sync/`（含 `/api/sync/jdbc/`）、`/api/notify/**`、`/api/sso/clients`	管理端配置/运维，需门户登录与权限码；不是第三方入站面
`grant_type=client_credentials`	未开通；Discovery 仅声明 `authorization_code`、`refresh_token`

能力总览

mermaid

flowchart LR
  TP[第三方系统]
  HMAC["/api/open/matters HMAC"]
  NoticeHmac["/api/open/notices HMAC"]
  KbHmac["/api/open/kb HMAC"]
  DataHmac["/api/open/data HMAC"]
  NotifyHmac["/api/open/notify HMAC"]
  OAuth["/api/open/tasks OAuth2"]
  IdP["门户 IdP SSO"]
  Push["出向 HTTP 推送"]
  TP --> HMAC
  TP --> NoticeHmac
  TP --> KbHmac
  TP --> DataHmac
  TP --> NotifyHmac
  TP --> OAuth
  TP --> IdP
  Push --> TP

能力	路径前缀	鉴权
事项推送	`POST /api/open/matters/{upsert,status,reopen,delete}`	HMAC
通知公告推送	`POST /api/open/notices/{publish,recall}`	HMAC
知识库文档	`POST /api/open/kb/documents/{upsert,status,delete}`	HMAC
数据服务（JDBC 视图）	`POST /api/open/data/query`	HMAC
模板消息代发	`POST /api/open/notify/send`；`GET /api/open/notify/records`	HMAC
任务中心	`/api/open/tasks/**`	OAuth2 Bearer + scope
门户作 IdP	`/oauth2/`、`/cas/`、`/saml/idp/**`、OIDC discovery	Client + 用户授权
出向同步	门户 → 你方 URL	管理端配置；见 05

第三方对接指南 ​

快速选型 ​

SDK / Demo 下载 ​

目录 ​

非目标（勿当作第三方入站面） ​

能力总览 ​

第三方对接指南

快速选型

SDK / Demo 下载

目录

非目标（勿当作第三方入站面）

能力总览