unis-oa/docs/node-open-approve-examples.md

23 KiB
Raw Permalink Blame History

外部审批对接样例:照着发就行

这一份是复制出去发给对接方的那一份——每一步都是真接口跑出来的请求与响应,不是手写的 示意图。设计理由、环节上能配什么,看 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. 联调自检清单

  1. 拿一个错结论词发一次,确认你们对 EMBED_DECISION_UNKNOWN 有告警——这个词表错在 上线当天最容易集体爆;
  2. 同一 bizKey 连发两次,确认你们这边只留一条记录、OA 那边只办一次;
  3. 先在 confirm 模式下跑通,再让 OA 改 auto:两种模式回的是 staged 与 handled 两个不同字段,你们的分支要按这个判,不要按 HTTP 200 判;
  4. 让 OA 把令牌 TTL 调短(或等它自然过期),确认你们会重取而不是把 401 当终态;
  5. 拿一张已办结的单发一次,确认你们对 400 NODE_WORK_NOT_RUNNING(message 里带「归档」) 不重试——这张单永远不会因为我们多试几次就回到待办;
  6. 你们那边的重试请带退避,且永远复用同一个 bizKey——这样最坏结果也只是重复拿到 一份旧回包,不会重复表态。
  7. 要提交开始环节的话,先故意只发 decide 不建单跑一次,确认你们对 400 NODE_LOCATE_NOT_FOUND 走的是"去建单"这条分支,而不是把它当成可重试的网络故障—— 这张单不会因为你们多试几次就自己冒出来(§2.8)。