23 KiB
外部审批对接样例:照着发就行
这一份是复制出去发给对接方的那一份——每一步都是真接口跑出来的请求与响应,不是手写的 示意图。设计理由、环节上能配什么,看 node-open-approve-design.md。
样例里的写法按你们那边的替换:BX-2026-0091 是单子上印的那个流程编号(job 号也认),
cr_finance_manager 是环节 id(可以不出现,见 §2.3),APPROVED 是你们那边的结论词。
0. OA 侧要先给你们的三样
| 给什么 | 你们拿它干什么 |
|---|---|
接口根地址(下面统一写 {BASE}) |
拼所有地址 |
app_key / app_secret |
换访问令牌(§2.1)。app_secret 只在创建/重置那一次给,OA 只存哈希 |
| 这一环的配置回执 | 认哪些结论词(decisions)、哪几个字段能随表态写进表单(fields)、哪几个字段能拿来定位(lookup)、谁来按确认键(confirm / auto)、哪些应用能使(apps 白名单) |
这个应用还得勾上 task:write(开放平台界面上那档叫「代某个待办处理人办理(含环节审批接口与撤回已办)」)。没勾上,
调 decide 会回 403 并点名缺哪一档——这不是配错了,是 OA 不让你顺手拿到一把宽钥匙。
1. 调用顺序
| # | 接口 | 权限 | 必发吗 |
|---|---|---|---|
| 1 | POST {BASE}/open/token |
免令牌 | 必发;令牌临期就重取(有效期看响应 expiresIn) |
| 2 | POST {BASE}/open/nodes/locate |
task:read |
订阅了 task.arrived 事件就可省;不订阅就靠它问参数 |
| 3 | POST {BASE}/open/nodes/{流程编号}/{环节id}/decide |
task:write |
这一趟的主活:按那颗审批钮 |
| 4 | GET {BASE}/open/works/{job} |
work:read |
收尾对账 |
| 5 | POST {BASE}/open/tasks/completed/{已办id}/recall |
task:write |
只在你们要收回结论时发 |
第 2 步订阅了 task.arrived 事件就可跳过——信封里那份 openApprove.interface 已经把单号与
环节 id 都填好了。地址里环节那一段是每次现取的参数,别把它当常量抄进配置(§2.3);
嫌这一段麻烦的,看 §2.5 那条省掉它的写法。
那张表是人工环节(替处理人按同意 / 驳回)的走法。要按的那颗钮在开始环节——也就是 这张单在 OA 里还没有、你们要替发起人提交——那是另一条顺序:先建单再表态,见 §2.8。
2. 逐步请求与响应
统一响应信封:成功是 {"code": 0, "message": "", "data": {…}};失败时 code 就是 HTTP 状态码,
并多带一个 reason。分支请按 reason 判,别比对那句中文(措辞会改,码不会)。
2.1 换访问令牌
POST {BASE}/open/token
Content-Type: application/json
{ "app_key": "oa_1e589bb67695f04e321d73a8",
"app_secret": "HmTmP7id…" }
{ "code": 0, "message": "", "data": {
"accessToken": "oat_Wfpf-L1fMUwUshOWIp7SExyZ3yKeEJYcnfjTD2MgAbw",
"tokenType": "Bearer",
"expiresAt": "2026-10-24 14:51:38",
"expiresIn": 7200, // 秒。到点前重取即可,旧令牌活到 expiresAt,可提前吊销
"scopes": ["process:read", "work:read", "work:write", "task:read", "task:write"] } }
之后每条都带:Authorization: Bearer {accessToken}。密钥错与 app_key 不存在回同一句话
(401 app_key 或 app_secret 不正确),免得这条接口被人拿来枚举有哪些 app_key。
2.2 定位:这张单现在停在哪个环节(可选)
有一种情况这一条不再报错:号是 OA 在发起页上占下的、那张单还没发起,而这一环勾了 「没有单据时代为发起」(§2.8)。这时它回
200:work.status是not_started、pending: true、activity.id是那条流程的开始环节,openApprove.interface就是可以直接发的 那条 decide。照它发一句过去,这张单就替发起人发起并提交了,单号不变。没勾这一档才回 400。
POST {BASE}/open/nodes/locate
Authorization: Bearer {accessToken}
{ "work": "BX-2026-0091" } // 也可不带 work,改带查找字段:{"keys": {"erpNo": "…"}}
默认这一份是瘦的,每次表态前来一次也不心疼:
{ "code": 0, "message": "", "data": {
"found": true,
"work": { "job": "7fc31b8f…", "serial": "BX-2026-0091", "status": "running" },
"process": { "id": "91d42378…", "name": "费用报销流程" },
"activity": { "id": "cr_finance_manager", "name": "财务经理" },
"pending": true } }
work.serial 与 activity.id 拼起来就是 §2.3 那条地址。pending: false + 一句 note
说明这张单已经办结 / 终止 / 作废——那种情况下不用再表态了,你们的机器人该靠这句话停手。
要那张填好号的现成端点和这一环的配置回执,带 "detail": "full":
POST {BASE}/open/nodes/locate
Authorization: Bearer {accessToken}
{ "work": "BX-2026-0091", "detail": "full" }
// 上面那几块之外,再多这两块:
"task": { "id": "14e8b36b…", "identity": "zhangsan", "identityName": "张三",
"dueAt": "2026-10-24 18:00:00", "routes": ["退回修改", "通过"] },
"openApprove": {
// 照抄这一条就行:单号与当前环节 id 都替你们填好了
"interface": "POST /api/v1/open/nodes/BX-2026-0091/cr_finance_manager/decide",
// 省掉环节那一段的写法:环节由 OA 认当前停着的那一环(§2.5)
"interfaceCurrent": "POST /api/v1/open/nodes/BX-2026-0091/decide",
"confirm": "confirm", // 谁来按确认键
"decisions": { "APPROVED": "agree", "REJECTED": "refuse" }, // 你们那儿的词 → OA 的结论
"fields": ["payAmount"], // 表态时能写进表单的格子
"apis": [ …全套对接接口,含每条要哪一档权限… ] }
decisions / fields / apis 这几样是配一次看一次的东西,所以不跟着每次定位跑;
真要点名替哪一条待办办(会签、加签),full 回的是 tasks 数组并提示带 identity 说清是哪条。
2.3 表态:按下那颗钮(主用这条)
POST {BASE}/open/nodes/BX-2026-0091/cr_finance_manager/decide
Authorization: Bearer {accessToken}
{ "result": "APPROVED",
"bizKey": "ERP-2026-0091-A" } // 幂等键:同一趟只算一次
地址两段:前一段是单子上印的那个号(job 号也认),后一段是这一环的环节 id。
环节 id 从 §2.2 那份 interface 或 activity.id 里取,订阅了事件就从信封里取——
每次调用现取,别存进配置,环节在设计器里删掉重拖就会换号。result 填你们那边那个
结论词(APPROVED / REJECTED / 提交……),OA 按这一环配的决策词表翻成同意 / 不同意 /
提交,大小写与首尾空格都不计较,直接发 agree / refuse / submit 也认。报文里不需要
work(地址里已经写了这张单),identity 只在同一环节有多条待办时才需要。这一格早前叫过
status 与 decision,三个名字 OA 都收,同时出现时认 result——它故意不叫 status,因为
回包里 work.status 说的是这张单还在不在跑,一个词不该在一个响应里指两件事。
confirm 模式(默认,人来确认)的回包:
{ "code": 0, "message": "", "data": {
"staged": true, // 停着等处理人点头,还没真的办
"decisionId": "c05c68ed…",
// 这条表态的台账:result 是你们发来的原话,state 是它自己走到哪一步
"decision": { "result": "APPROVED", "kind": "agree", "kindLabel": "同意", "route": "通过",
"opinion": "经 ERP 对账核验一致,同意。BX-2026-0091", // 意见模板已渲染
"state": "staged", "expireTime": "2026-10-25 12:51:42", "…": "…" },
"route": "通过", "activity": "财务复核",
"work": { "serial": "BX-2026-0091", "status": "running", "activity": "财务复核", "…": "…" },
"note": "表态已备好,等这条待办的处理人确认后才真正办理" } }
auto 模式(环节上配了自动办理)的回包——当场办完,直接给你办完之后的状态:
{ "code": 0, "message": "", "data": {
"handled": true, "route": "通过", "activity": "财务复核",
"status": "running", "done": false, // done=true 表示这张单办结了
"work": { "serial": "BX-2026-0091", "activity": "总监审批", "status": "running", "…": "…" },
"tasks": [ { "id": "1856b2cf…", "activity": "总监审批", "identity": "lisi" } ],
"note": "已按环节「财务复核」的外部审批配置自动办理" } }
staged 与 handled 是这一路唯一要看的两个字段:staged 说明这张单还等人点头,
handled 说明已经走了。别把 HTTP 200 当成"审批过了"。
2.4 网络重试:同一个 bizKey 放心重发
POST {BASE}/open/nodes/BX-2026-0091/cr_finance_manager/decide
Authorization: Bearer {accessToken}
{ "result": "APPROVED", "bizKey": "ERP-2026-0091-A" } // 与 §2.3 一模一样
{ "code": 0, "message": "", "data": {
"staged": true, "alreadyStaged": true, "decisionId": "c05c68ed…", // 还是第一次那一份
"note": "这个 bizKey 的表态已经在等处理人确认,本次调用没有另起一份" } }
幂等记在 (应用, 这张单, 这一环, bizKey) 上,同一条链路换用 §2.5 那条省掉环节的地址重发也认得
是同一份;反过来,换了环节就不算重复——所以重试请照 §2.3 点名原来那一环,别拿短地址
赌它还在原地。每次新表态换一个新 bizKey,重试才复用旧的。已经办过的那一趟重发回
handled: true + alreadyHandled: true;被处理人驳回过的回一句人话(400,含"驳回"),
不静默重办。
2.5 不想传环节 id 时可以省那一段(备选写法)
POST {BASE}/open/nodes/BX-2026-0091/decide
Authorization: Bearer {accessToken}
{ "result": "REJECTED", "bizKey": "ERP-2026-0091-B" }
少写一段,环节由 OA 按这张单此刻停着的那一环认,判据与 §2.3 一字不差:只有一环开着
外部审批接口且对你们这个应用开口,就替它按那颗钮;认不出唯一一环就不猜(并行分支停在两环上
回 400 NODE_ACTIVITY_AMBIGUOUS,两条完整地址在 message 里)。
代价是"哪一环"由调用那一刻决定。报文晚到时单子可能已经流到下一个同样开了接口的环节, 这一次表态就落在那一环上,而幂等按环节记,换个环节不算重复。所以这一条只推荐给「一条流程 里只有这一环开外部审批、且你们收到信号就立刻调用」的场合;会晚到、会补发、流程里有多环开了 接口的,请照 §2.3 点名环节。
2.6 会签:这一环有好几条待办
POST {BASE}/open/nodes/BX-2026-0091/cr_finance_manager/decide
Authorization: Bearer {accessToken}
{ "result": "APPROVED", "bizKey": "ERP-2026-0091-C", "identity": "zhangsan" }
identity 填 OA 里的身份(登录账号最稳,姓名一般也认得出),且必须真是那条待办的处理人。
不点名而这一环又有多条待办时,回 400 把候选的人名念给你,不会替你们挑一个。
2.7 收尾:对账、终止、撤回
GET {BASE}/open/works/{job} // 流转 + 已办台账,两边对账
POST {BASE}/open/works/{job}/terminate { "identity": "…", "opinion": "ERP 那边作废了" }
POST {BASE}/open/tasks/completed/{已办id}/recall { "identity": "…" }
GET {BASE}/open/works/{job} 里那个 handled 就是已办台账,撤回要点名的 已办id 取它的 id:
{ "code": 0, "message": "", "data": {
"work": { "serial": "BX-2026-0091", "status": "running", "activity": "总监审批", "…": "…" },
"flow": [ { "fromActivity": "财务复核", "toActivity": "总监审批", "route": "通过",
"operator": "张三", "opinion": "经 ERP 对账核验一致,同意。BX-2026-0091",
"arrivedAt": "2026-10-24 12:51:46" } ],
"handled": [ { "id": "7f74c86c…", // ← recall 那个地址里填它
"activity": "财务复核", "identity": "zhangsan", "identityName": "张三",
"route": "通过", "opinion": "经 ERP 对账核验一致,同意。BX-2026-0091",
"completedAt": "2026-10-24 12:51:46" } ] } }
handled 是当前还成立的已办:撤回成功之后那一条就从这里消失了,flow 里仍留着
「撤回」那一笔。recall 只能撤你们自己办过的那一步(以那条待办处理人的身份),后续环节
已有别人办过就撤不动,会说明为什么;已经办结归档的单也撤不动——那是引擎的边界,
不是这条接口的毛病。
2.8 开始环节:这张单在 OA 里还没有(两种一步到位的走法)
上面几条都默认一件事:OA 里已经有这张单了。开始环节(发起人那一环)不是这样—— 这一环的表态只有一颗钮:提交,而提交要有张停着的单才按得动。
有两种走法,你们挑一种,OA 侧配一下就行:
| 走法 | 你们要发的请求 | OA 侧要配的 |
|---|---|---|
一句 decide 就发起并提交 |
只发 §2.3 那一条(要带 bizKey) |
环节上勾「没有单据时代为发起」;identity 可以不带——号是 OA 给过你们的那个号时,OA 按号认得出替谁发起 |
| 先建单再表态 | POST /open/works(带 hold)+ 一条 decide |
什么都不用勾 |
勾了代发之后,你们原来那句回写就是全部:result: "AGREE" 加 bizKey,OA 认不出这张单时
就地把它发起、并按这一环的确认模式提交(auto 当场走,confirm 仍等发起人在单据页点头)。
OA 认人是按「报文 identity → bizKey 是预受理号 → 地址里那个号是 OA 占下的」这个顺序来的,所以你们照今天这样回写(地址填 OA 的号、bizKey 填自己那套流水号)也不用补参数。回包里 startedFromDecision: true 与 work.serial 会告诉你们这张单的号——它和你们记的那个
号是同一个,只要 bizKey 填的是 OA 发起页给过的那趟预受理号(PRE…)。这一档为什么默认关、
幂等怎么算,见设计文档 §4.6.2。
没勾(或者你们想把两步分开)就走两步,两步之间那张单停在开始环节(表单校验、编号、闸门都 已经过完,就是不流转):
POST {BASE}/open/works
{ "process": "{流程定义id}", "identity": "{发起人身份}", "title": "…", "data": {…},
"hold": true }
→ data.work = { "job": "…", "serial": "FYBX202610260009", "status": "running" }
POST {BASE}/open/nodes/{上面回包的 serial 或 job}/{开始环节id}/decide
{ "result": "AGREE", "bizKey": "RE-20261026-010" }
三处容易踩的,都踩过:
-
号要用 OA 给的那个,并且用
bizKey把它保住。发起页每开一页,OA 就替这一趟占一个 正式号(PRE…那个预受理号是同一趟的另一半身份),你们按它建自己的记录;补发时带上bizKey,建出来的单就是这个号,不会另排一个新的。反过来,自己按格式排的号 OA 认不出 ——前缀日期位数长得一模一样也没用(要按自己那套号定位,就让 OA 把那一格配成查找字段, 走 §2.2 的keys)。 -
hold决定要不要第二步。带hold才是"停着等提交",也就才有那条"第三方替发起人 提交"的表态记录;不带就是当场提交,那就到此为止,不用再发 decide。 -
结论词照这一环的卡片发。卡片(
locate带"detail": "full")里sample.result填的就是 这一环认得的那个词,decisions是这一环那张对照表。你们那边只会回AGREE而不打算改, 就让 OA 在决策词表里加一行AGREE → 提交——表里配的词排在内置那几个前面,这样就开始环节 也能提交。什么表都没配就直接发SUBMITTED。 -
第一步也要带幂等号。你们那趟嵌页面拿到的预受理号(
PRE…那个)就填在bizKey里: 这一趟已经发起过,OA 不再新建第二张,而是把原来那张连alreadyStarted: true回给你。 建单这一步一样会网络重试,不带它就是造出两张报销单。
环节上是 confirm 模式时,第二步只把表态停着(回 staged),发起人在单据页点头才真提交;
auto 模式当场提交(回 handled)。另外注意:这一环若开了 OA 按钮锁定并且锁了 start,
OA 界面里发起人自己也按不动那颗提交钮,第三方没回调就得靠流程监控的干预面板救场。
3. 一条龙 curl
BASE=https://oa.example.com/api/v1
TOKEN=$(curl -s -X POST "$BASE/open/token" -H 'Content-Type: application/json' \
-d '{"app_key":"oa_xxx","app_secret":"xxx"}' | jq -r .data.accessToken)
# 环节 id 取现号:curl 一次 locate,从 data.openApprove.interface 里读,别硬抄
curl -s -X POST "$BASE/open/nodes/BX-2026-0091/cr_finance_manager/decide" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"result":"APPROVED","bizKey":"ERP-2026-0091-A"}'
4. 错误:按 reason 分支
{ "code": 400, "message": "…给人看的一句话…", "reason": "NODE_WORK_NOT_FOUND", "data": null }
HTTP / reason |
什么意思 | 你们该怎么做 |
|---|---|---|
401 UNAUTHORIZED |
没带令牌 / 令牌过期 / 应用被停用 | 重取令牌再发一次;还是 401 就是这把钥匙被吊销了 |
403 FORBIDDEN("没有被授予…") |
这个应用没勾 task:write |
找 OA 管理员开权限,重试没有用 |
403 FORBIDDEN("这一环没对当前应用开审批接口") |
环节开了,但白名单里没有这个应用 | 同上,加白名单 |
404 NOT_FOUND("这一环没开审批接口") |
这张单当前停着的环节不接外部表态 | 别重试;这是"不归这条通道管",不是故障 |
400 NODE_WORK_NOT_FOUND |
地址里那一段既不是流程编号也不是 job 号,也没有这么一张已归档的单 | 检查你们传的是单子上那个号(或 job 号) |
400 NODE_WORK_AMBIGUOUS |
这个编号撞在不止一张单上 | 改用 job 号 |
400 NODE_PATH_WORK_MISMATCH |
地址与报文里的 work 各说了一张单 |
两处填同一张,或报文里省掉 work |
400 NODE_WORK_NOT_RUNNING |
这张单已办结 / 终止 / 作废,message 里写明是哪一种 |
别再发,去查台账;这是终态,不会因为我们重试就变 |
400 NODE_ACTIVITY_AMBIGUOUS |
你们用了 §2.5 那条省掉环节的地址,而这张单同时停在两环上 | 改用 §2.3 那条带环节 id 的主写法,两条完整地址就在 message 里 |
400 NODE_TASK_AMBIGUOUS |
这一环有多条待办没点名 | 报文补 identity(候选的人名在 message 里) |
400 NODE_NOT_PENDING |
这一环此刻没有未办待办 | 还没轮到或已经过了;查 §2.7 的台账 |
200 + alreadyHandled |
这一环已经有人办掉了(人或另一个入口先办的) | 正常结局,记一笔就行,别当失败重试 |
400 NODE_LOCATE_NOT_FOUND |
这个号 OA 从没用过(message 里会写"先建单再来") |
别重试,这是单子还没建:走 §2.8 先 POST /open/works;或让 OA 勾上「没有单据时代为发起」,你们这一句 decide 直接把它发起来;或改用查找字段 keys 定位 |
400 NODE_BEGIN_SUBMIT_ONLY |
开始环节只认「提交」,你们那个词翻成了同意 / 不同意 | 按 message 里念出的那一行让 OA 补决策词表(如 AGREE → 提交),或改发提交那个词 |
400 NODE_WORK_NOT_STARTED |
这个号是 OA 在发起页上占下的(或还挂在草稿上),那一趟还没提交 | 别重试,先发起:按 message 里那句带上 bizKey 调 POST /open/works,或等本人提交那一页。这一环勾了「没有单据时代为发起」时这一条根本不会回 400——定位直接回 pending 并把 decide 地址给你 |
400 NODE_WORK_PAST_BEGIN |
这张单已经离开开始环节(在流转或已办结) | 别再提交,去看 §2.7 的台账 |
400 NODE_START_BIZ_KEY_REQUIRED |
环节勾了代发,但你们这一句没带 bizKey |
带上你们那趟的幂等号重发;少了它一次重试就是两张单 |
400 NODE_START_IDENTITY_REQUIRED |
环节勾了代发,但 OA 不知道该替谁发起 | 报文补 identity,或把 bizKey 填成 OA 发起页给过的那趟预受理号(PRE…) |
400 NODE_START_DATA_INCOMPLETE |
代发要把整张单发起来就得过发起那一步的必填校验,而 OA 把这一趟已有的值(打开那一页时带进来的参数 + 攒着的回填 + 挂着的草稿 + 发起页那一屏此刻的整份表单值)垫完之后仍缺那几格 | 先回 OA 看那一屏:那几格人在发起页上填了吗(form 那一份是从屏幕上攒的,没填进去 OA 就没有)、或那一格是不是回源格而那条源查不到这个人(开户行名称 那类要 SQL 真回得出值)。都行不通再照 message 点名的格名把值随这次表态放进 data(键名用表单字段名);这一趟库里没留半张单、也没另排号,补齐原样再发一次就行。注意 data 盖不过 OA 自己有的值:那几格以 OA 表单里的为准,data 只补 OA 手里没有的 |
400 NODE_PROCESS_NOT_STARTABLE |
环节勾了代发,但这条流程没启用 / 没发布 | 找 OA 管理员,重试没有用 |
400 EMBED_DECISION_UNKNOWN |
这个结论词 OA 不认 | 你们的词得进环节决策词表,或直接发 agree / refuse / submit |
429 RATE_LIMITED |
超过这个应用的每分钟限额 | 按 message 里的秒数退避再来 |
一句话:能被重试救的只有 401(重取令牌)和 429(退避),其余都是配置或单据状态的事, 闷头重试只会把限流打满。
5. 联调自检清单
- 拿一个错结论词发一次,确认你们对
EMBED_DECISION_UNKNOWN有告警——这个词表错在 上线当天最容易集体爆; - 同一
bizKey连发两次,确认你们这边只留一条记录、OA 那边只办一次; - 先在
confirm模式下跑通,再让 OA 改auto:两种模式回的是staged与handled两个不同字段,你们的分支要按这个判,不要按 HTTP 200 判; - 让 OA 把令牌 TTL 调短(或等它自然过期),确认你们会重取而不是把 401 当终态;
- 拿一张已办结的单发一次,确认你们对 400
NODE_WORK_NOT_RUNNING(message里带「归档」) 不重试——这张单永远不会因为我们多试几次就回到待办; - 你们那边的重试请带退避,且永远复用同一个
bizKey——这样最坏结果也只是重复拿到 一份旧回包,不会重复表态。 - 要提交开始环节的话,先故意只发 decide 不建单跑一次,确认你们对 400
NODE_LOCATE_NOT_FOUND走的是"去建单"这条分支,而不是把它当成可重试的网络故障—— 这张单不会因为你们多试几次就自己冒出来(§2.8)。