下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/org-nznpea4p--jiandaoyun-integration-guide.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md，安装 @org-nznpea4p/jiandaoyun-integration-guide。简道云对接/集成配置指南。只要问题同时涉及「简道云」和「对外打通」就应使用本技能，包括开放 API 读写数据、API Key 与鉴权、接口参数与错误码、Webhook 数据推送与回调验签、表单事件/流程推送、单点登录 SSO 与免登、前端事件调用第三方接口、自建插件开发、AI 连接（MCP），以及与 ERP、MES、WMS、CRM、数据库、企业微信、钉钉、飞书、金蝶、用友、九数云、FineReport、BI、自研系统等系统打通。
提供方案选型、逐步配置指导、参数速查、排错清单与官方文档链接。触发词举例：简道云对接、简道云集成、简道云接口、开放平台、开放接口、怎么把数据同步到简道云、从简道云取数、数据怎么写入简道云、简道云 API 怎么调、API Key 在哪创建、app_id/entry_id/字段ID/_widget 怎么查、接口报错、对接失败、联调、Webhook、数据推送、回调地址、回调验签、X-JDY-Signature、单点登录、SSO、SAML、CAS、免登录、统一身份认证、前端事件、自定义请求、自建插件、MCP、AI 连接、开放平台权限没开通。
英文 JianDaoYun API integration, open API, API key authentication, webhook callback, SSO SAML CAS, frontend event, custom plugin, MCP server, data sync.
阅读全文 （展开查看完整说明）
概述
用于指导客户/实施方完成「简道云 ↔ 外部系统」的对接配置。输出的是可执行的配置步骤，不是泛泛的方案介绍。
触发条件（命中任一即应使用本技能）
- 问题里出现「简道云 / JianDaoYun / JDY」且涉及对外打通：对接、集成、接口、API、取数、写入、同步、推送、回调、联调、报错。
- 问配置在哪、怎么配：API Key、app_id、entry_id、字段 ID、服务器地址、Secret、回调地址、白名单、授权范围。
- 问某系统怎么和简道云连起来：ERP / 数据库 / 自研系统 / 企微 / 钉钉 / 飞书 / 金蝶 / 用友 / BI。
- 问登录打通：单点登录、SSO、SAML、CAS、免登、统一身份认证。
- 问扩展开发：前端事件、自定义请求、自建插件、MCP、AI 连接。
只要沾第 1 条，即使表述模糊（"这个能接吗""客户想打通"）也先按本技能走，用「一、先问清 5 件事」收敛需求。
何时使用
- 客户要把 ERP / 数据库 / 自建系统的数据写进简道云，或从简道云取数
- 客户要实时感知简道云数据变更（Webhook）
- 客户要让员工用自家系统账号登录简道云（SSO）
- 客户要在简道云表单里调用第三方接口（前端事件 / 自建插件）
- 客户要让 AI 助手直接读写简道云（AI 连接 MCP）
与本技能无关的，转交
| 需求 | 转交技能 |
|---|---|
| 表单/流程/仪表盘/权限怎么用 | jiandaoyun-support |
| 某个 AI 场景在简道云能不能做 | jiandaoyun-ai-verdict |
| 自建 SSO IdP 服务的代码落地 | jiandaoyun-sso |
| 流程条件回退自建插件 | jiandaoyun-condition-rollback-plugin |
一、先问清 5 件事（不要跳过）
对接方式选错，后面全部返工。开口先确认：
- 方向：外部 → 简道云（写入）、简道云 → 外部（读取/推送）、双向？
- 时机：实时（事件触发）、定时（T+1/每小时）、人工触发？
- 对象：哪个应用/表单/流程？涉及哪些字段（含子表单？附件？）
- 环境：对方系统是什么（数据库/ERP/自研 API/企微/钉钉）？有无公网 IP / 域名 / HTTPS？
- 版本与权限：简道云是什么版本？是否已增购 API / Webhook / SSO？（决定方案可行性，见下表）
版本门槛（官方口径，2026-09 取证）：
| 能力 | 版本要求 | 备注 |
|---|---|---|
| 前端事件 | 所有版本免费 | 表单设计页配置，浏览器端执行 |
| API 接口 | 企业版及以上可增购 | 「开放平台 >> 密钥管理」可见才代表已开通 |
| Webhook 推送 | 企业版及以上可增购 | 表单「扩展功能 >> 数据推送」 |
| 单点登录 SSO | 企业版及以上可增购 | 企业设置 >> 企业安全 |
| 自建插件 | 企业版/旗舰版可用，独享版可增购 | 每次触发扣 0.0001 云币 |
| AI 连接（MCP） | 企业版及以上，Beta 阶段 | 需在「企业安全」先开启 |
判断技巧：让客户截图「开放平台」左侧菜单。看不到「开发文档」「密钥管理」= 没开通 API，先走商务增购，不要再往下配。
二、选型决策
| 场景 | 首选方案 | 备选 | 关键约束 |
|---|---|---|---|
| 外部系统定时/事件写入简道云 | 开放 API（新建数据接口） | 自建插件 | API 写入默认不发起流程、不触发智能助手，需显式传 is_start_workflow / is_start_trigger |
| 外部系统拉简道云数据 | 开放 API（查询多条 + 分页） | 数据工厂输出表 / 九数云 | 分页用 data_id 游标，limit 最大 100 |
| 简道云数据变更实时通知外部 | Webhook 数据推送 | 插件「表单数据推送至数据库」 | 接收端 2 秒内返回 2xx，否则重试 |
| 用自家账号登录简道云 | 单点登录（SAML2.0 / 自定义接口 / CAS） | 企微/钉钉/飞书集成模式 | 需开发能力，无代码能力走定制需求 |
| 表单填写时实时查外部接口 | 前端事件（自定义请求） | 自建插件 | 前端事件在浏览器执行，密钥会暴露给客户端 |
| 复杂逻辑/复用/多表单调用 | 自建插件 | 外部中间件 | 有后端事件，可隐藏密钥，按次扣云币 |
| 让 AI 助手直接读写简道云 | AI 连接（MCP） | 开放 API 自建服务 | MCP 限 3 次/秒，写能力受限 |
组合建议：需要「实时 + 双向 + 有业务逻辑」时，标准架构是 Webhook（进）+ 开放 API（出）+ 中间件做业务编排，而不是在简道云里硬塞。
三、按路径执行
选定方案后，读取对应 reference 拿到原文级细节，再给用户步骤。不要凭记忆写接口路径和参数。
| 路径 | 必读文件 |
|---|---|
| 开放 API | references/02-api-core.md + 对应接口文件（03 数据 / 04 流程 / 05 通讯录 / 06 用量审计） |
| Webhook | references/07-webhook.md |
| 单点登录 | references/08-sso.md（深度实现转 jiandaoyun-sso） |
| 前端事件 | references/09-frontend-event.md |
| 自建插件 | references/10-selfbuilt-plugin.md |
| AI 连接 MCP | references/11-ai-connect-mcp.md |
| 版本/能力全景 | references/01-overview-and-capability.md |
| 找某篇官方文档 | references/12-doc-index.md |
3.1 开放 API 最小跑通流程（最常用）
- 建密钥：开放平台 >> 密钥管理 >> API Key >> 创建 API Key。设置「应用授权范围」「接口授权范围」（最小够用原则），生产环境务必配 IP 白名单（上限 50 个，不支持 IPv6）。
- 拿 ID：开放平台 >> 开发文档 >> 参数说明，选应用和表单，抄
app_id、entry_id、字段 ID（_widget_xxx）。也可调「用户应用查询接口」+「表单字段查询接口 V5」程序化获取。 - 先调试：开放平台 >> API 调试台，填
Authorization: Bearer <APIKEY>和请求体，点开始调试；调试台能一键生成多语言示例代码。 - 再落地：用
scripts/jdy_api.py改造，或把调试台生成的代码贴进项目。
技术要点（写死，别改）：
- 统一地址
https://api.jiandaoyun.com/api，全部 POST（文件上传接口用 form_data），UTF-8 - 鉴权：
Authorization: Bearer <YOUR_APIKEY>（Bearer 后有一个空格） - 全局限频 50 次/秒；查询多条 30 次/秒、新建单条 20 次/秒（各接口不同，见接口文档）
- 错误统一 HTTP 400 +
{"code":8303,"msg":"超出请求频率限制"}，错误码对照见 02 文件 - v5 路由把
app_id/entry_id放在 body 里；老版本 v1/v2 放 URL path，新对接一律用 v5 - 分页：
data_id传上一次返回的最后一条 ID，limit1~100 - API 写入不会触发重复值校验和必填校验，也不支持写入：分割线、手写签名、选择数据/查询、流水号
3.2 Webhook 最小跑通流程
- 表单 >> 扩展功能 >> 数据推送 >> 新建数据推送，选「自定义服务器」
- 填服务器地址（HTTPS）→ 生成 Secret → 点「服务器连接测试」必须显示连接成功
- 勾选推送事件（新增/修改/删除/恢复）。注意：批量修改/删除/恢复、导入数据不触发推送
- 接收端实现：
- 只接受 POST，
Content-Type: application/json - 验签：把请求体原文字符串与
nonce、secret、timestamp拼成{nonce}:{payload}:{secret}:{timestamp}，UTF-8 编码后取 sha1 十六进制，与 HeaderX-JDY-Signature比对 - 2 秒内返回 2xx，业务逻辑放异步线程
- 用
X-JDY-DeliverId做去重 - 未知
op类型也要返回成功，否则会被判失败
- 只接受 POST，
- 失败重试 5 次/次；连续失败 100 条推送会自动关闭该功能并通知管理员
四、不可妥协的 5 条
- 每个结论带官方链接。本技能所有事实来自 hc.jiandaoyun.com，回答时给出文档 URL。文档可能变动，参数以官方页面为准。
- 字段 ID 不许猜。
_widget_xxx必须来自「参数说明」页面或「表单字段查询接口」，编造字段 ID 是最常见的低级事故。 - 先确认版本权限再动手。没开通 API 就配接口，等于浪费客户时间。
- 密钥安全：API Key 只放服务端；前端事件里不要放真正的业务密钥（会在浏览器暴露），需要隐藏密钥就改用自建插件或中间件。严禁把客户 API Key 上传到任何云端/第三方服务，只在本地使用。
- 不编造报价与限制数字。涉及价格、配额、SLA，一律引官方文档或让客户联系商务（400-111-0890 转 2）。
五、排错速查
| 现象 | 原因 | 处理 |
|---|---|---|
| 返回 400 / code 8303 | 超频 | 降频 + 加退避重试；注意各接口限频不同 |
| 返回 401/权限类错误码 | API Key 授权范围不含该应用/接口，或 IP 不在白名单 | 密钥管理里检查应用范围、接口范围、IP 白名单 |
| 数据写进去了但流程没发起 | is_start_workflow 默认 false | 显式传 true |
| 数据写进去了但智能助手没触发 | is_start_trigger 默认 false | 显式传 true |
| 分页死循环/漏数据 | 用 page 分页 | 改用 data_id 游标 |
| Webhook 收不到 | 未在 2 秒内返回 2xx / 验签失败 / 连续失败被关闭 | 查推送失败记录；确认批量修改和导入本身不触发 |
| 子表单数据写不进 | 子表单结构需逐条子记录，且字段 ID 是子字段的 | 查 03 文件示例 |
| 附件/图片写不进 | 需先调文件上传接口拿凭证并传 transaction_id | 查 03 文件「文件接口」 |
| 通讯录接口报不支持 | 集成模式（企微/钉钉/飞书）部分接口受限 | 接口文档标注「仅支持公共模式」的，集成模式下不可用 |
查不到时：开放平台 >> 密钥管理 >> API 调用日志（保留近 7 天，含失败原因）是第一手证据，优先让客户提供。
六、交付形态建议
给客户的对接说明至少包含：① 方案选型结论与理由；② 前置条件（版本/权限/网络/IP 白名单）；③ 分步配置截图位；④ 接口清单（路径 + 关键参数 + 示例）；⑤ 联调与验收方式；⑥ 排错表。
附：维护
- 官方文档内容会更新。用
scripts/fetch_doc.py <文档ID>可拉取指定文档最新原文，用于刷新references/。 scripts/jdy_api.py是可直接运行的 API 客户端模板（查询/新建/修改/删除/字段/通讯录），改造后即可用于客户环境。
