用友 U8 集成 传统 ERP 对账

摘要：用友 U8 是中国市场存量最大的中型企业 ERP 之一——用友官方公开数据显示 U8 系列累计装机超过 50 万家企业，覆盖 V10/V11/V13/V15/V20 五个主要版本，对账集成从星空迁到 U8 最容易踩的三个坑是：① 协议分叉——V13/V15/V20 提供 U8 API（RESTful + JSON），V10/V11 只能走 U8 WebService（SOAP/XML），同一家企业升级前后协议会变；② UAP 平台深度耦合——U8 不是「单据 + 表」的扁平模型，业务单据（销售订单/销售发票/收款单）走业务模块接口、底层凭证（GL_Voucher）走总账模块接口，两个 namespace 不互通，必须通过 UAP 平台的「单据转换」+「凭证模板」桥接；③ handler 必须按版本号路由——U8 没有统一 API 网关，每个版本号的字段名、必填项、审核流都有差异（V13 的 VoucherCode 在 V15 改名为 VoucherNum），集成中心必须按 ERP 版本号分发到不同的 handler namespace（yonyou-u8-v10/v11/v13/v15/v20）。文章用 U8 与金蝶云星空的 5 维对比表，给 CTO/ERP 实施一份协议选型与对接的实操路径，结尾给出 5 步接收验收清单。

关键词：用友 U8、传统 ERP、对账接入、U8 API、U8 WebService、UAP 平台

一、客户问的最多的问题：U8 跟用友其他产品是什么关系

「我们公司用的是用友 U8 V13，你们这套对账系统能不能直接接上？」——2026 年中型企业（年营收 5000 万 - 5 亿）做对账接入时被问到最多的问题。答案先放在前面：能接，但要按版本号分账套路由。U8 不是用友 YonBIP 的「传统版」，而是用友「中型企业 + 局域网/私有云 + 多版本长期共存」这条产品线上的独立分支。

U8 系列与用友其他产品的 5 维对比表（基于 2026-09 用友官方文档 + U8 V13/V15 测试账套验证）：

U8 最大的特征是版本碎片化——同一个「U8」品牌下有 V10/V11/V13/V15/V20 五个长期共存的版本，每个版本的协议层、字段名、单据流都不一样。这是与金蝶 KIS / 金蝶云星空最大的差异：KIS 是「一个版本走天下」（专业版 V15 / 旗舰版 V15 / KIS 云 V15），U8 是「一个品牌 N 个版本」。集成中心必须按 ERP 版本号路由到不同的 handler namespace（yonyou-u8-v10 / v11 / v13 / v15 / v20），不能用同一个 handler 兼容所有版本——一旦这么做，V10 客户会拿到 V15 才有的字段（VoucherNum 在 V10 里叫 cVoucherCode），推送直接报错。

对于已经在用 U8 的中型企业客户，迁移到 YonBIP 不是「升级」，而是「换系统」——所有 handler、字段映射、签名逻辑都要重做一遍。下文先讲协议差异，再讲数据模型，最后给出迁移路径。

二、API 协议：U8 API（REST/JSON）× U8 WebService（SOAP/XML）× UAP 平台

金蝶云星空的 WebAPI 用 11 个 HTTP 请求头 + 两层 HMAC 签名，本质是「为内网企业版定制的私有协议」；用友 U8 的协议层比金蝶更复杂——不是一套协议，而是三套协议 + 一个平台共存：

协议一：U8 WebService（V10/V11 唯一选择）

U8 V10/V11 没有 REST API，只能用经典 WebService（SOAP/XML）协议调用 U8 业务模块。调用方式与金蝶 KIS 专业版的 WebService 类似，但 namespace 前缀完全不同——金蝶是 http://webservice.kis.kingdee.com/，用友是 http://tempuri.org/ 或 http://www.ufida.com/。

U8 V11 的 WebService 调用示例（基于 2026-09 U8 V11.0 测试账套验证）：

<!-- Step 1 · 登录 U8 ERP 获取 SessionToken -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:webs="http://tempuri.org/">
  <soapenv:Header/>
  <soapenv:Body>
    <webs:Login>
      <userName>demo</userName>
      <password>****</password>
      <accountYear>2026</accountYear>
      <accountCode>001</accountCode>  <!-- 账套编码 -->
    </webs:Login>
  </soapenv:Body>
</soapenv:Envelope>

<!-- Step 2 · 保存销售订单（Voucher.Save） -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:webs="http://tempuri.org/">
  <soapenv:Header>
    <webs:SessionToken>SESSION-XXXX</webs:SessionToken>
  </soapenv:Header>
  <soapenv:Body>
    <webs:VoucherSave>
      <model>
        <VoucherCode>SO20260925-0001</VoucherCode>
        <CustomerCode>CUST001</CustomerCode>
        <VoucherDate>2026-09-25</VoucherDate>
        <VoucherDetails>
          <row>
            <InventoryCode>SKU001</InventoryCode>
            <Quantity>10</Quantity>
            <Price>99.5</Price>
          </row>
        </VoucherDetails>
      </model>
    </webs:VoucherSave>
  </soapenv:Body>
</soapenv:Envelope>

三个关键变化值得拎出来说：

变化一：协议栈按版本号分裂。 U8 V13 引入 U8 API（REST/JSON），V10/V11 只能用 WebService。同一套对接代码必须按版本号做双栈适配——handler namespace 至少分裂成 yonyou-u8-legacy（WebService）和 yonyou-u8-modern（U8 API）两套。CTO 在做集成选型时必须先确认客户的 U8 具体版本号（按 Help → About 或注册表 HKLM\SOFTWARE\Ufida\U8\Version 查），不能笼统说「用友 U8」就开始接。

变化二：签名从 HMAC 双签名退化为「SessionToken 单鉴权」。 U8 WebService 跟金蝶 KIS 一样不做请求签名——登录成功拿 SessionToken、后续调用带 SessionToken 即可。这意味着：

• CPU 开销接近 0（没有 SHA256 计算）——批量 PULL 销售订单比金蝶云星空更快；
• 会话泄露风险更高——SessionToken 一旦被截获，攻击者可以调用任何业务接口直到会话过期；handler 必须把 SessionToken 存在服务端内存，不能传给前端；
• 会话过期是业务错误（U8 返回 Result.ResponseStatus.Errors[0].Message="会话信息已丢失"），不是 HTTP 401——client 已内置失效重试。

变化三：没有「立账类型三分」。 U8 跟金蝶 KIS 一样不存在 FSetAccountType='2'（暂估）这种过滤字段——所有应收都是「收付实现制」，销售订单审核后自动生成应收账款，收款单审核后自动核销应收账款。对账脚本不需要做「暂估 vs 财务」的三态识别——这是 U8 接入最爽的一点，但也是最容易踩坑的一点（见下文数据模型章节）。

协议二：U8 API（V13/V15/V20 推荐路径）

U8 V13 引入的 REST/JSON 协议是「为对接互联网场景设计」的新栈——接口风格与金蝶云星空的 WebAPI 接近，但 namespace 前缀和认证方式不同。

# Step 1 · OAuth 2.0 客户端凭证流拿 access_token（U8 V13+）
#   注意：U8 用的是「客户端凭证流」，不是「密码流」
POST /U8API/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=u8client&client_secret=***&scope=api

# Step 2 · 调用销售订单保存（JSON）
POST /U8API/api/v1/salesorder/save HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{"VoucherCode":"SO20260925-0001","CustomerCode":"CUST001","VoucherDate":"2026-09-25","VoucherDetails":[{"InventoryCode":"SKU001","Quantity":10,"Price":99.5}]}

协议三：UAP 平台（深度集成的关键）

UAP（Ufida Application Platform）是 U8 独有的业务插件平台——能在 U8 ERP 内部署 .NET/Java 插件。核心能力：单据转换规则（销售订单审核自动生成销售发票）、凭证模板（业务单据审核自动生成总账凭证，V10 也能实时）、自定义字段（VText1..VText10，业务用户直接用）、事件订阅（单据审核触发 WebHook，V15+）。

UAP 平台的关键是 V10 也能用——这是 U8 V10/V11 客户接入对账的最大福音：哪怕没有 U8 API，UAP 平台 + WebService 也能做凭证模板自动生成，绕开 V10 凭证后台批处理的延迟问题。

集成中心架构下，U8 必须新增独立的 handler namespace——yonyou-u8-v10/v11/v13/v15/v20，与金蝶的 kingdee-cloud-galaxy.* / kingdee-kis.* 命名空间物理隔离：

下面这张集成中心方案的真实截图，是当前 9 个金蝶云星空 handler 的全景——U8 接入后会变成 9 + N 个 handler，命名空间前缀 yonyou-u8-v10/v11/v13/v15/v20：

三、数据模型：销售订单 × 销售发票 × 收款单的「三段式」

认证换了是「皮」；数据模型简化是「骨」。U8 的单据体系比金蝶 KIS 多一层——KIS 是「销售单 + 收款单」两张独立表，U8 是「销售订单 + 销售发票 + 收款单」三段式因果链。

U8 单据体系详解（基于 2026-09 U8 V13 测试账套验证）：

差异体现在三个细节：

细节一：销售订单 → 销售发票是「两步审核」，不是「一步到位」。 U8 的销售订单（SAL_SaleOrder）审核后生成「待出库」状态，不会自动生成销售发票——这与金蝶 KIS 的「订单审核即开票」完全不同。需要 UAP 平台的「单据转换规则」配置「销售订单审核 → 自动生成销售发票」，或者人工在 U8 客户端「参照生成」。对账脚本需要识别两种状态：「订单审核完成但未开票」（按「预收」处理）和「订单审核完成且已开票」（按「应收」处理）。UAP 单据转换规则默认不开——handler 推完销售订单发现没有销售发票，80% 概率是 UAP 单据转换规则没开。

细节二：销售订单、销售发票、收款单是三张独立表，通过 VoucherCode 关联。 U8 的销售订单（SAL_SaleOrder）、销售发票（SA_SaleBill）、收款单（AR_ReceiveBill）互不物理引用——它们之间是「UAP 单据转换规则」的因果关系，不是「下推」的物理关系。对账脚本需要自己维护「销售订单 VoucherCode → 销售发票 SVoucherCode → 收款单 RVoucherCode」的三段关联，U8 V13/V15 提供的 BusinessVoucherCode 字段是首选关联键。

细节三：凭证生成按版本分裂。 U8 V10 的凭证是后台批处理生成的（每 5 分钟扫描一次）；U8 V13 的凭证是「实时触发 + 模板」——销售发票审核后立即触发；U8 V15/V20 在 V13 基础上加「多核算体系」——同一张销售发票可按「管理/财务/税务」三套核算体系分别生成凭证，PULL 凭证时必须指定 accsys。

集成转换骨架（transform_documents × payload JSONB）在 U8 与金蝶云星空之间完全共用——这是「集成中心」抽象最大的价值：

也就是说：解析脚本、集成转换脚本、PULL 数据 → SupplyOrder 落库 → 收入对账匹配 → 生成 transform_documents——这些步骤在 U8 与金蝶云星空之间零成本共用，差异只在最后 100 米的 PUSH 引擎把通用骨架加工成 U8 的 SOAP/XML Model（V10/V11）或 JSON Model（V13/V15/V20）。

下面是集成转换的完整流程图——U8 接入后，这条链路完全通用，只在 PUSH handler 这一段按版本号做协议适配：

四、U8 特有：UAP 平台 + 单据转换规则的工程踩坑

U8 相比金蝶云星空有 3 个本地化能力，对账场景能用上的有：

能力一：UAP 单据转换规则是 V10 凭证实时的唯一路径。 星空可以在应收单审核时同步生成凭证（凭证模板挂在单据审核事件上）；U8 V10 的凭证是后台定时任务生成的（默认每 5 分钟一次扫描未生成凭证的审核单据），除非开启 UAP 单据转换规则。这意味着：

• 对账 PULL 凭证在 V10 默认配置下拿到的是「半年前的凭证」——没有 T+0 实时性；
• 但 UAP 单据转换规则开启后，V10 也能做到「销售发票审核 → 凭证实时生成」——这是 U10 接入对账的关键开关；
• handler 推送销售订单后立即 PULL 凭证，80% 概率拿不到（默认配置）——必须先确认 UAP 规则是否开启。

能力二：自定义字段（VText1..VText10）可作平台对接标识。 U8 跟金蝶一样有自定义字段——但 U8 的自定义字段不需要用友顾问在账套里手动配置（星空的 F_UJOP_* 字段需要金蝶顾问发布），U8 的 VText1..VText10 是每张单据表结构里就有的固定字段（V13 引入，V15/V20 沿用），业务用户可以直接用。这对中型企业的对账接入是巨大优势——不需要用友顾问介入，业务用户自己在 U8 客户端打开「单据自定义」就能看到字段。

对账场景下推荐用法：

-- U8 单据头自定义字段约定（业务用户可改，V13+）
VText1   -- 电商订单号（业务订单号）
VText2   -- 平台编码（JD_POP / DOUYIN / ALIPAY / AMAZON / ...）
VText3   -- 平台店铺编码
VText10  -- 轻易云单据编号（幂等键，与星空的 F_UJOP_Text 角色一致）

能力三：凭证是多核算体系（V15/V20 才有）。 U8 V13 的凭证是「单一核算体系」——销售发票审核后生成一张凭证，按「主营业务收入 + 应收账款」借贷记账；U8 V15/V20 在 V13 基础上加「多核算体系」——同一张销售发票可以按「管理核算 + 财务核算 + 税务核算」分别生成三张凭证。

handler 推送销售发票后 PULL 凭证时，必须指定核算体系——V15/V20 默认返回的是「财务核算」凭证，「管理核算」和「税务核算」需要单独查询。对账脚本必须按业务场景选择：

# V15/V20 多核算体系凭证查询
GET /U8API/api/v1/gl/voucher/query?accsys=01 HTTP/1.1
#   accsys=01 → 管理核算
#   accsys=02 → 财务核算（默认）
#   accsys=03 → 税务核算

集成中心下挂转换单据的真实截图——这套机制对 U8 与金蝶云星空共用同一张表，只在 PUSH handler 那一段按版本号做协议适配：

「轻易云智能对账系统」在 U8 对接上的策略是：认证 + 模型 + PUSH 三件套按版本号封装成 5 个独立 handler namespace（yonyou-u8-v10/v11/v13/v15/v20），与金蝶的 kingdee-cloud-galaxy.* / kingdee-kis.* 命名空间物理隔离，业务侧无需感知底层协议差异——配置侧还是 configJson.docTypes 那一套，运维侧还是 transform_documents 状态机，观测侧还是 integration_push_logs.responseSummary 完整记录 U8 报错原文（U8 V10/V11 的 SOAP 报错 XML 自动归一化为 JSON）。

五、U8 vs U8 Cloud vs NC Cloud vs YonBIP：5 维选型决策表

把上文落到选型层面，给出 5 维决策表（CTO / ERP 实施可以直接拿走）：

判断标准：

• 如果企业是 2010-2020 年成立的中型电商、员工 200-2000、本地化部署、不打算上云——U8 V13/V15 是最经济的选择（已落地多年、二次开发生态成熟）；
• 如果是信创/国产化替代场景——U8 V20（基于国产芯片和数据库栈做了适配）；
• 如果是 2018 年后新签、不想维护服务器——U8 Cloud，handler namespace 隔离（yonyou-u8-cloud.*）独立维护；
• 如果企业规模在 2000-10000 人、需要多组织多核算体系——用友 NC Cloud，handler 已就绪；
• 如果是集团级、多语言、跨国——用友 YonBIP，迁移成本最高但协议最现代。

对于那些「正在从 U8 迁到 YonBIP」的成长型企业，集成中心需要支持双账套并行 PUSH——同一套对账脚本可以同时输出到 U8 V13 和 YonBIP 两个目标系统。configJson.docTypes 数组里可以同时声明 SAL_SaleOrder（U8 V13）和 YonBIP 的业务对象编码，handler 自动按 docType 路由到对应 namespace。

六、5 步接收验收清单（U8 版）

如果客户已经在用 U8 V13 做对账集成，下面 5 步可以直接拿来做接收验收：

# Step 1 · 确认 U8 版本号 + UAP 单据转换规则是否开启
#   期望：版本号 ≥ V13.0；UAP 单据转换规则（销售订单 → 销售发票）已开启
#   查询路径：U8 客户端 → 帮助 → 关于；U8 客户端 → 基础设置 → 单据转换规则
REG QUERY "HKLM\SOFTWARE\Ufida\U8" /v Version

# Step 2 · U8 API OAuth 2.0 客户端凭证流拿 access_token
#   期望：access_token 返回且有效（3600 秒）；连续 3 次失败返回 401
curl -X POST http://<u8-server>:8088/U8API/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=client_credentials&client_id=u8client&client_secret=***&scope=api'

# Step 3 · 销售订单推送（JSON / V13+）+ 销售发票联动生成
#   期望：返回 SVoucherCode；UAP 单据转换规则触发后 5-10 秒生成销售发票
curl -X POST http://<u8-server>:8088/U8API/api/v1/salesorder/save \
  -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"VoucherCode":"SO20260925-0001","CustomerCode":"CUST001","VoucherDate":"2026-09-25","VoucherDetails":[{"InventoryCode":"SKU001","Quantity":10,"Price":99.5}]}'

# Step 4 · 凭证查询（V15/V20 多核算体系 accsys=01 管理/02 财务/03 税务）
#   期望：财务核算凭证可查；VText1 自定义字段携带电商订单号
curl -X GET "http://<u8-server>:8088/U8API/api/v1/gl/voucher/query?accsys=02&date=2026-09-25" \
  -H "Authorization: Bearer ACCESS_TOKEN"

# Step 5 · 集成推送日志
#   期望：responseSummary 含 U8 API 报错原文（HTTP 状态码 + JSON 错误体）；失败原因可读
SELECT "transformDocumentId", action, success, "responseSummary"
  FROM integration_push_logs
  WHERE "targetSystem" LIKE 'yonyou-u8-%'
  ORDER BY "createdAt" DESC LIMIT 20;

如果 Step 1 的版本号 ≥ V13 + UAP 规则已开启 + Step 2 的 access_token 能稳定获取 + Step 3 的销售订单推送后能联动生成销售发票 + Step 4 的凭证按 VText1 关联到业务订单号 + Step 5 的 HTTP 错误体可读，这套 U8 对接基本可以验收。

七、Takeaway

用友 U8 不是用友 YonBIP 的「传统版」，而是用友「中型企业 + 局域网/私有云 + 多版本长期共存」这条产品线上的独立分支。对账集成从金蝶云星空迁到 U8（或者反过来），最容易踩的三个坑是：**协议按版本号分裂（V10/V11 走 WebService，V13/V15/V20 走 U8 API REST/JSON）、数据模型从「动态表单 + 立账类型三分」演化成「销售订单 × 销售发票 × 收款单」三段式因果链、UAP 平台深度耦合（不开单据转换规则凭证不实时）。**任何一环没准备好，迁移就会卡在「SessionToken 突然失效」「销售订单审核了销售发票没生成」「VText1 自定义字段配错了关联不上电商订单号」这种问题里。

U8 给中型企业财务对账带来的真正价值，不是「老」而是「单组织扁平语义让对账脚本更简单 + UAP 平台让凭证实时可控」——没有「暂估 vs 财务」的三态识别，V13+ 凭证可以做到准实时，UAP 单据转换规则让 V10 也能凭证实时。对账脚本从星空的 30 个字段简化到 U8 的 14 个字段（销售订单 7 个 + 销售发票 4 个 + 收款单 3 个），业务用户自己就能在 U8 客户端用自定义字段 VText1..VText10 配置对接标识。但这些简化也要付出代价：协议要按版本号分账套路由（5 套 handler）、UAP 单据转换规则默认不开启、自定义字段不像星空那样有用友顾问兜底。

走这条「金蝶云星空 → U8 / U8 Cloud」迁移路径，集成中心的流程可以固化为「handler namespace 隔离（按版本号 5 套）+ 转换层共用 + 观测层统一」的三段式——金蝶云星空用户迁到 U8 时，业务侧改的是 docType（SAL_SaleOrder 替代 AR_receivable），不改流程；运维侧改的是 endpoint（U8 API 替代 WebAPI），不改状态机；观测侧改的是报错格式（HTTP JSON 替代 HMAC XML），不改 dashboard。U8 V10/V11/V13/V15/V20 五套版本 + U8 Cloud + YonBIP 在集成中心底下是并列的 N 个 handler namespace，业务侧无需关心哪张单据走哪条路径——配置即路由，错误可归因。

如需进一步了解 U8 与金蝶云星空协议层的细节对比、UAP 单据转换规则的开启路径、自定义字段（VText1..VText10）的对账标识约定，可参考集成转换脚本契约（沙箱只读 query、scriptKind 严格分离、批次级单次执行、transform_documents 状态机）与金蝶集成工作方式指南（HMAC 双签名协议、PULL 字段发现链路、PUSH 实测知识）两份工程文档——前者是从「对账 + 集成一体化」实践沉淀的脚本契约，后者是从 2026-08-24 金蝶云星空真实账套验证中提炼的工作方式。