常见问题#

这是用友的官方项目吗？#

不是。本项目与用友网络科技股份有限公司没有关联，也未获其认可或赞助。「用友」「U8」「U8+」是用友网络科技股份有限公司的商标，文中提及仅为说明兼容对象。

许可上允许这样调用 U8 吗？#

本项目只调用你已安装的 U8 业务组件，不包含、也不分发 U8 的任何程序。本项目经 U8 业务组件登录，同样占用 U8 许可点数；是否允许此类集成以你的许可合同为准，能调通不等于许可允许。用友对二次开发和接口使用有自己的授权条款和收费模块（例如开放平台的 OpenAPI 模块）。使用前请核对你的 U8 许可合同，必要时咨询用友或你的实施服务商。是否使用由你自行决定并承担责任。

支持哪些 U8 版本？#

在 U8+ V18.0 上开发和测试，其他版本未经验证。在其他版本上使用时，先执行桥的签名自检（--check-signatures），再在测试账套上把要用的操作逐一验证（快速开始）。

能直接连桥，不用 API 服务吗？#

能。co/client 就是直接连桥的（桥协议见架构）。但桥只认共享密钥和来源 IP，没有调用方身份、读写分级、只读账套、写入策略和限流。面向多个业务系统时使用 API 服务。

口令存在哪里？#

哪里都不存。调用方每次请求带 U8 操作员编码和口令；API 服务加密后转给桥，桥解密后只用于这一次登录。口令不写日志、不写审计。桥在内存中缓存登录得到的数据库连接串（键为 HMAC，不含口令），最多 authCacheSeconds 秒，只供只读的 SQL 路由使用。

权限由谁判断？#

U8。每次请求都以调用方给出的操作员登录，U8 按该操作员的功能权限和数据权限决定；读取还会继承操作员的记录权限和字段权限，无权查看的字段返回 null 并列在 masked_fields 中。API 服务只判断令牌能否调用某条路由（读、写、经营管理）以及账套白名单、只读账套和写入策略。

为什么返回 504 `outcome_unknown`？#

请求已交给 U8 执行，但在时限内没有拿到确定的结果：桥等了 75 秒任务仍在执行，或 U8 自行提交后回读失败，或网络在请求送出后中断。写操作可能已经生效。带了幂等键的先用 idempotency/get 查询；否则用 vouchers/load、vouchers/list、gl/vouchers/load、archives/get 核对，再决定是否重试。

审核返回 409 `state_mismatch`，可以重试吗？#

先看 message。调用前单据已是目标状态，说明无需再做；提交后回读对不上，说明事务已提交，不要把同一次审核再发一遍，到 U8 中查看实际状态。

为什么返回 422 `login_failed`？#

U8 拒绝了登录。message 是 U8 的原文，常见原因：口令错误、操作员被停用、登录日期不在账套已建的年度内、year 不是账套库年度、u8Server 不是 U8 登记的应用服务器。

为什么返回 503 `com_unavailable`？#

U8 的 COM 组件未注册、创建失败，或所需程序集无法加载。用桥的 --check-signatures 检查组件注册和签名；检查 u8Home 是否指向 U8 安装目录、u8co-bridge.exe.config 是否在 exe 旁边；查看 <root>\unhandled.log。

为什么返回 503 `u8_unavailable`？#

U8 自身的服务或文件不可用，例如生产制造服务 U8MPool 未运行，或档案使用的 EAI 字段对照文件读不到。这不是单据的问题，需检查 U8 服务器。

为什么返回 403 `feature_disabled` 或 `test_account_only`？#

调用的是第二级写入（结账、存货核算、期初、坏账、汇兑损益、应付票据、总账取消记账、损益结转与自定义转账等）。它们缺省关闭：桥 config.json 未设 enableReplicatedWrites: true 时返回 feature_disabled；开启后只对 testAccounts 中的账套开放，其他账套返回 test_account_only。正式账套上请在 U8 客户端中完成这些操作（已知限制）。

为什么返回 403 `account_read_only`？#

账套在桥的 readOnlyAccounts 或 API 的 U8CO_READONLY_ACCOUNTS 中，只开放读取（配置参考）。

怎样放开一个新账套？#

在桥 config.json 的 allowedAccounts 和 API 服务的 U8CO_ACCOUNTS 中都加上，然后重启两端。只需读取的账套同时放进只读账套名单；需要写入的正式账套配置写入策略。先在测试账套上把要用的操作验证一遍（快速开始「开放更多账套」）。

会给审批人的手机发通知吗？#

缺省不推送；桥 config.json 设置 "mobilePush": true 后，经本服务的审批照常推送 U8 移动审批（配置参考）。

能增加新的单据类型或操作吗？#

能。每一条新的 COM 调用序列都要先在测试账套上验证，再写进桥和 API，并补充测试。步骤见贡献指南。