用友 YonBIP 旗舰版 · API接口调用（api-ult）
一、技能维护边界（最高优先级）
本技能定位是「调用」——在用户提供应用凭证（appKey / appSecret）与接口信息的前提下，完成旗舰版开放平台业务接口的 access_token 获取与业务调用联调。
不沉淀以下内容（铁律）：
- 应用凭证（appKey、appSecret、租户 ID 等）——一律由用户提供，走命令行参数 / 环境变量，绝不写进技能知识或脚本常量、绝不随包外发。
- 接口清单实体数据（请求路径 / 参数 / 返回结构）——由接口清单获取类能力产出或用户直接提供，本技能不内嵌。
- 客户具体信息（客户名、集团编码、业务单元 code、数据量等）。
> 本技能只覆盖「开放平台业务接口调用」这一环节。接口清单本身如何抓取、接口的路径 / 参数结构从哪来，不在本技能范围。
> 本规则优先级高于下方所有章节。红线只在此声明一次。
二、何时使用
- 用户说「调一下旗舰版开放平台的 XX 接口」「获取 access_token」「对接开放平台业务接口」
- 用户给出形如
/yonbip/xxx/yyy的开放平台接口 path，并要求实际发起调用 - 用户遇到开放平台鉴权报错（签名不正确、API 未被授权、token 失效等）需要排查
三、获取 access_token
3.1 令牌端点
GET https://{host}/iuap-api-auth/open-auth/selfAppAuth/getAccessToken
{host}随租户所在数据中心变化（如c1/c3等），由用户提供，不猜测。- 老地址
getAccessToken仍可用；新地址/base/v1/getAccessToken返回的 token 更长、含特殊字符。两地址签名 / 参数完全一致，脚本会依次尝试。
3.2 请求参数（GET query）
| 参数 | 类型 | 说明 |
|---|---|---|
appKey |
string | 开放平台应用 appKey |
timestamp |
long | Unix 毫秒时间戳 |
signature |
string | HmacSHA256 签名（见 3.3） |
> 租户 ID 不在令牌端点参数内，不需要传。
3.3 签名算法（最关键）
signature = URLEncode( Base64( HmacSHA256( parameterMap, key=appSecret ) ) )
parameterMap：把所有待签参数（即appKey、timestamp，排除 signature 本身）按「参数名 ASCII 升序」排列，依次拼接参数名 + 参数值（无分隔符、无 URL 编码）。HmacSHA256的 key =appSecret。- 算出二进制签名 → Base64 → URLEncode（即交给
urllib.parse.urlencode统一编码一次）。
官方示例：appKey=0a1b2c3d4e5f60718293a4b5c6d7e8f9、timestamp=1000000000000、appSecret=xxxx
→ 待签串 = appKey0a1b2c3d4e5f60718293a4b5c6d7e8f9timestamp1000000000000
→ HmacSHA256(待签串, key=appSecret) → Base64 → URLEncode。
3.4 返回
{
"code": "00000",
"message": "成功！",
"data": {
"access_token": "b8743244...",
"expire": 7200
}
}
code="00000"为成功；data.access_token即令牌；data.expire为有效期（秒，7200 = 2 小时），过期需重取。- 调用顺序铁律：先取 token，后用 token。每次业务调用前重取一次 token 属规范做法（避免过期）。脚本入口已自动执行此顺序。
四、调用业务接口
4.1 网关地址拼接
https://{host}/iuap-api-gateway{path}?access_token={token}
{host}与令牌端点同域名（同一数据中心）。{path}为开放平台业务接口路径（如/yonbip/ssc/img/invoice/ocr/ocr）。access_token以 query 参数形式拼接（不是 header、不是 Bearer）。
4.2 关键调用约定（必须遵循）
- 签名只算到 Base64 再统一编码一次：
signature = URLEncode( Base64( HmacSHA256( parameterMap, key=appSecret ) ) )，交给urlencode统一编码一次，不要先 URLEncode 再被编码（双重编码会返回「签名不正确」）。 - token 必须 URL 编码：拼
?access_token=时必须urllib.parse.quote(token, safe="")（java 用URLEncoder.encode、go 请求库自动、php 用urlencode）。 - Content-Type 必须是
application/json;charset=UTF-8，编码 UTF-8。 - host 随租户变：不同租户数据中心域名不同（c1 / c3 …），以用户给的为准，不臆测。
- 业务接口需在开放平台控制台对该 appKey 「接口授权」后才能调，否则鉴权层放过后会被业务层拒。
4.3 报错排查
- 签名算法详解与报错码速查见
references/token_notes.md。 - 常见调用报错与排查见
references/faq.md（技能问题题库）。
五、脚本使用
凭据一律走参数或环境变量，不落盘明文：
# 仅获取 token（打印到 stdout，便于管道复用）
python scripts/get_qjb_token.py --appkey <AK> --appsecret <AS> --host c3.yonyoucloud.com
# 获取 token 并直接调业务接口
python scripts/qjb_call.py --appkey <AK> --appsecret <AS> --host c3.yonyoucloud.com \
--path /yonbip/ssc/img/invoice/ocr/ocr \
--method POST --body '{"key":"value"}'
# body 读自文件
python scripts/qjb_call.py --appkey <AK> --appsecret <AS> --host c3.yonyoucloud.com \
--path /yonbip/xxx/yyy --body file:req.json
# 环境变量兜底（避免命令行暴露密钥）
export QJB_APPKEY=<AK>; export QJB_APPSECRET=<AS>; export QJB_HOST=c3.yonyoucloud.com
python scripts/qjb_call.py --path /yonbip/xxx/yyy --body file:req.json
--host默认c3.yonyoucloud.com（仅缺省兜底，仍以用户实际数据中心为准）。get_qjb_token.py会依次尝试老 / 新令牌地址，自动选用可用的一个。qjb_call.py内部先取 token 再拼网关调用，HTTP 错误（含 4xx / 5xx）会打印状态码与响应体便于排查。
5.1 出包前自检
本技能含 .package_allowlist.txt（本机凭据相关文件不进包）。出包前须按打包治理规范跑双检（结构自洽 + 发布合规）——自带白名单在打包与目录核对两种模式下均自动生效、无需显式传入；零 FAIL 才放行。
文件清单
yonyou-js-djw-api-ult/
├── SKILL.md 本技能说明：维护边界、token 获取、签名算法、调用约定、报错速查、脚本用法
├── scripts/
│ ├── get_qjb_token.py 获取 access_token（签名 + 换 token，凭据走参数 / 环境变量）
│ └── qjb_call.py 获取 token 并调用业务接口（凭据走参数 / 环境变量）
├── references/
│ ├── token_notes.md 签名算法详解与报错码速查
│ └── faq.md 技能问题题库（试错归此，正文不重述）
├── .gitignore 忽略临时文件；本机治理产物，不进包
└── .package_allowlist.txt 打包白名单；本机治理产物，不进包
