用友 BIP 集成指南:开放平台接入与主数据同步

接入准备

用友 BIP 的开放能力通过 YonBIP 开放平台提供,整体风格是标准 RESTful + token 鉴权,与金蝶云星空的"服务全名 + 会话 Cookie"风格差异很大。接入前的准备:

1. 在 YonBIP 租户后台创建自建应用,获得 AppKey 与 AppSecret;
2. 确认租户 ID(tenantId),多数接口需要;
3. 为应用开通所需 API 的调用权限(按 API 包授权)。

获取 access_token

自建应用通过 HmacSHA256 签名换取 access_token,典型请求:

GET https://open.yonyoucloud.com/open-auth/selfAppAuth/getAccessToken
  ?appKey={appKey}
  &timestamp={毫秒时间戳}
  &signature={签名}

签名算法:把参与参数(appKey、timestamp 等)按参数名排序拼接,用 AppSecret 作为密钥做 HmacSHA256,再转为十六进制(或按文档要求编码)。要点:

• timestamp 是毫秒级,且与服务器时间偏差不能太大,机器时钟要先校准;
• access_token 有有效期,过期前主动刷新,不要每次调用都重新获取——token 接口也有调用频率限制;
• 签名串的拼接顺序、编码方式严格按官方文档,大小写不一致是验签失败的第一大原因。

调用业务 API

业务接口统一走网关,典型形态:

GET/POST https://openapi.yonyoucloud.com/apiproxy/open/{API 路径}
  ?access_token={token}

以查询客户档案为例,通常需要带分页参数(页码、每页条数)与查询条件;写接口(如新增/修改档案)以 JSON body 提交。注意:

• 不同业务域(财务、供应链、营销)的 API 路径前缀不同,以 API 市场文档为准;
• 返回结构一般是统一的 code / message / data 包装,业务错误在 code 非成功值时给出;
• 开放平台对应用有调用配额,超限返回限流错误,客户端要有退避重试。

主数据同步方案设计

客户、物料、供应商等主数据从 YonBIP 下行到其他系统(或反向),推荐结构:

常见问题

1. 验签失败:检查参数排序、时间戳单位(毫秒)、AppSecret 是否复制完整;
2. token 过期处理缺失:拿到 401/鉴权类错误要自动刷新 token 重试一次,仍失败再告警;
3. 分页边界:最后一页返回条数小于每页条数即终止,不要依赖 total 字段(部分接口不返回);
4. 测试环境与生产环境分离:沙箱租户的 AppKey 不能用于生产,切换时连同 tenantId 一起换。