接口参考#

本文列出全部路由、请求字段、响应字段和错误码。字段和校验以代码为准：API 服务的 Pydantic 模型在 api/u8co_api/co_models*.py，桥的校验在 co/bridge/src/Requests*.cs。API 服务运行时另提供 OpenAPI 3.1 文档（GET /v1/openapi.json，§17）。

目录#

• 1. 两层接口
• 2. 公共字段
• 3. 路由总表
• 4. 单据类型
• 5. 读取 vouchers/load
• 6. 审核 vouchers/verify
• 7. 新增 vouchers/create
• 8. 修改 vouchers/update
• 9. 删除 vouchers/delete
• 10. 关闭和打开 vouchers/close
• 11. 参照生单 vouchers/generate
• 12. 收付款单和应收应付单
• 13. 审批流 workflow/*
• 14. 总账凭证 gl/vouchers/*
• 15. 基础档案 archives/*
• 16. 列表和现存量
• 17. 健康检查、登录检查和 OpenAPI
• 18. 错误码
• 19. 只读报表 reports/*
• 20. 幂等键
• 21. 字段元数据 meta
• 22. 操作员权限
• 23. 预演 dry_run
• 24. 名称解析 archives/resolve
• 25. 裁剪响应 fields、compact
• 26. 字段标签 meta/fields
• 27. 单据查询 vouchers/search
• 28. 批量读取 vouchers/load_many、archives/get_many
• 29. 期初记账与期初单据 openings/post、openings/arap
• 30. 账套体检 reports/account_readiness
• 31. 月末结账 periods/close
• 32. 存货核算记账与期末处理 ia/post、ia/period_end
• 33. 公司间接口（仅 API）
• 34. 经营管理查询
• 35. 其他单据和写入

1. 两层接口#

同一套业务路由有两个入口：

field、hint、detail 可能没有（§18）。例如 POST /v1/co/vouchers/load 转发到桥的 POST /u8co/v1/vouchers/load。两层的请求字段相同，区别只有：

• API 收明文 password，加密成 password_enc 后转给桥；直接调桥时由调用方加密。
• API 的 date、year 可省略（§2）；桥要求必填。
• API 先用自己的模型校验，不合法是 400 bad_request「请求参数无效：<字段>」（error.field 是出错字段的路径），不访问桥；桥上同样的错误带更具体的中文 message。
• API 的每个 POST 路由另收查询参数 fields、compact 裁剪响应（§25）。
• API 另有令牌权限（§17）、账套白名单、只读账套、频率和并发限制。

下文路径省略前缀，写成 vouchers/load。成功响应在桥上都带 "ok": true，API 原样返回。请求和响应都是 UTF-8 JSON；桥的请求体上限 64 KiB，成功响应最多 8 MiB，错误响应最多 64 KiB。

2. 公共字段#

除 health、meta 外，每个请求都带：

顶层出现未知字段是 400（桥上 message 为「含未知字段」）。单据主键 id 是 1 到 2147483647 的整数。

每次请求都用该操作员登录 U8，按它在 U8 里的功能权限、数据权限（记录级）和字段权限判断能不能做：越权 403，读取时字段权限隐去的字段置为 null 并列在 masked_fields（§22）。桥和 API 不保存操作员和口令。

3. 路由总表#

「权限」一列是 API 的读写分级（§17），直接调桥没有这层分级。「第二级」见表后说明。

预演。 标「写」的路由都可以在请求体里带 dry_run: true：走同样的检查和锁，但不写入（§23）。例外：sale-orders/verify、dispatches/verify 不支持预演（经 API 是 400「请求参数无效：dry_run」）；arap/writeoff/auto 的 dry_run 表示「只出计划」。

分级标记。 OpenAPI 里每个 /v1/co 操作带扩展字段 x-u8co-access（read、write、mgmt、perm_evaluate），与「权限」一列相同。配置了写入策略（configuration.md）时，写路由还要过策略的放行规则、冻结和时段。

第二级写入。 标「第二级」的写入（以及 §4 里期初结存单的写入）没有可调用的 U8 组件，或改的是跨模块的期初 / 结账状态，由桥执行与 U8 界面相同的 SQL（已在测试账套上与 U8 界面执行的 SQL 实测核对）。桥在登录 U8 之前（含预演）依次检查（例外：arap/voucher/delete 要读出凭证才知道它是否属于第二级，在登录之后、事务里任何写入之前检查，见 limitations.md「第二级：复现写入」）：

1. 桥配置 enableReplicatedWrites 为 true（缺省 false），否则 403 feature_disabled，message 为「第二级写入未开启：」加下面各路由的原文；
2. 账套在桥的 testAccounts 里，否则 403 test_account_only。

health 的 replicated_writes 显示开关状态。这类写入只用于测试账套；正式账套请在 U8 客户端操作（风险见 limitations.md）。

4. 单据类型#

type 不在下表里是 400「单据类型无效」。「行主键」是修改时的 line_id，也是生单时来源行的 source_line_id。

共 41 种可读取类型。「SQL」表示读取直接查表，不走业务组件。「生单」表示只能经 vouchers/generate 参照来源新增（§11），vouchers/create 是 400。ia_adjust、inventory_price_adjust 只读，写路由一律 400。退货申请单、退款单、无来源销售出库、手工结算、红冲蓝字发票的细则见 §35。

质量单据：

• 报检单（QM01、QM02）没有审批流，不能修改、关闭，也不开放单独审核：U8 在保存时按选项自动审核，删除时桥先弃审（§6、§9）；产品报检单可单独弃审（§6）。
• 检验单（QM03、QM04）的审核走 workflow/*，可修改表头（§8「质量单据」），不能关闭。
• 不良品处理单（QM05、QM06）可参照检验单生单、删除；不受审批流控制的可直接审核、弃审，受控的走 workflow/*；不能修改。
• 其他报检单（QM11）、其他检验单（QM15）没有来源单据、没有审批流（IsWfControlled 恒为 0，workflow/* 400）。其他报检单可无来源新增（§7）、审核、弃审、删除；其他检验单可参照其他报检单生单（§11）、审核、弃审、删除；两者都可修改表头。

各类型使用的 U8 登录子系统：销售和质量单据 SA，库存 ST，采购 PU，收款单、客户退款和应收单 AR，付款单、供应商退款和应付单 AP；生产订单读取和关闭 SA，审核、新增、修改和删除 MO；物料清单读取和列表 SA，审核、新增、修改和删除 BO。不带类型的路由：总账 GL，档案 AS，列表、现存量、login-check 和不带 type 的待办 SA。个别写入另用 QM、AR、AP，在各节注明。

5. 读取 vouchers/load#

请求：type、id。

响应：

销售订单和发货单的读取由 U8 按操作员的数据权限过滤。收付款单和应收应付单的主键对应的行若是别的 cFlag / cVouchType（例如供应商退款），按不存在处理，404。

报检单（QM01、QM02、QM11）只取固定的一组列（列名同 U8 单据模板）：

• 表头：单号 CINSPECTCODE、报检日期 DDATE、报检人 CMAKER、报检部门 CINSPECTDEPCODE（CINSPECTDEPNAME）、业务部门 CDEPCODE、供应商或客户（带名称）、来源 CSOURCE / CSOURCECODE / CSOURCEID、到货日期、检验类型、审核人和审核日期；自定义项 CDEFINE1–CDEFINE16。
• 表体：AUTOID、来源行 SOURCEAUTOID（到货单行 Autoid 或生产订单行 MoDId）、存货（带名称、规格、主计量单位）、仓库、批号、报检数量 FQUANTITY / 件数 FNUM、累计检验数量 FSUMCHECKQTY / 件数 FSUMCHECKNUM、生产订单号和行；自由项 CFREE1–CFREE10、自定义项 CDEFINE22–CDEFINE37。
• 下游检验单（QM03 / QM04 / QM15）表头的 INSPECTID / INSPECTAUTOID 指回报检单的 ID / AUTOID。
• 其他报检单（QM11）来源各列为空，一般只有一行。U8 不回写它的 FSUMCHECKQTY；是否已检验看表体 BFLAG：1 为已检验，NULL 或 0 都是未检验（不要只判 = 0）。

其他检验单（QM15）的读取同来料、产品检验单（表头整行、检验项目表体），只是没有 wf。

物料清单（bom，id 是 bom_bom.BomId）只读标准 BOM（BomType=1），替代 BOM 400「只支持标准物料清单」。code 是母件存货编码（表头没有单号）。键是固定的小写下划线名：

• 表头：bom_id、inv_code、inv_name、inv_std、part_id（母件 bas_part.PartId）、version、version_desc、eff_date、end_date、status（1 未审核、3 已审核、4 停用）、verifier、verified_at、parent_scrap、wf、created_by、created_at、modified_by、modified_at、ufts（十进制）。
• 每行：line_id（OpComponentId）、sort_seq、op_seq、inv_code、inv_name、inv_std、base_qty_n、base_qty_d、comp_scrap、wip_type、wh_code、dept_code、eff_beg、eff_end、remark、fv_flag、product_type、byproduct_flag、offset_days、plan_rate、accu_cost_flag、optional_flag、mutex_rule、cost_wip_rel、aux_unit、extras（"1" 表示该行带替代料、定位符、分段损耗或自由项，接口不能修改这张清单；辅计量看 aux_unit，§8）。
• state.verified 是 status 为 3，closed 是 status 为 4。数据权限按母件存货。

采购结算单（purchase_settle，id 是 PurSettleVouch.PSVID，code 是结算号 cSVCode）读取只查表。写入有参照采购发票自动结算（vouchers/generate，§11）、手工结算（vouchers/create，§35）和删除（§9）；修改、审核 400（U8 里也没有）。

• head 是 PurSettleVouch 的原列，另加供应商名称 ven_name、ven_abbname。
• lines 是 PurSettleVouchs 的原列（iRdsID 入库单行、iBsID 发票行、iSVQuantity 结算数量、iSVPrice 结算金额、iSVAPrice 暂估金额、bAccount 存货核算已处理结算成本等），每行另加入库与发票的对照：in_id（采购入库单 RdRecord01.ID）、in_code、in_date、in_qty（入库行数量）、in_aprice（入库行暂估金额）、in_price（入库行金额，同月结算时 U8 改成结算金额）、invoice_id（采购发票 PBVID）、invoice_code、invoice_date、invoice_qty、invoice_money（发票行本币无税金额）。iBsID 为 0 的行是红蓝入库对冲，发票对照为空；上游类型 cUpSoType 不是 01（入库单）的行入库对照为空。
• state.verified 恒为 false（结算单只有制单人），另有 line_count、accounted_lines（bAccount=1 的行数）、accounted（每行都已处理结算成本）、invoice_count、receipt_count（涉及的发票、入库单张数）。
• 表头、表体的 rowversion 是 psufts / psdufts。数据权限按供应商、存货（表体），部门、业务员、采购类型、表体仓库为可空列；功能权限认「结算单列表查询」PU040305（U8 没有单独的结算单查询功能）。

出入库调整单（ia_adjust，表 JustInVouch / JustInVouchs，id 是表头自增列 id，code 是单号 cJVCode）只读。入库调整（cVouchType=20，卡片 0401）、出库调整（21，卡片 0402）和发出商品等其他调整类型同在一张表，不按类型拆分。

• head 是表头原列，另加 wh_name、dep_name、rd_name；lines 是表体原列（按单号 cJVCode 关联；iJVPrice 调整金额、cbAccounter 记账人、CorID / cCorCode 被调整单据等），另加 inv_name、inv_std。
• 调整单不改现存量和货位，只记存货核算明细账（IA_Subsidiary）。
• 没有审核：state.verified（同 state.posted）表示表体每行都已记账；verifier 取表头记账人 cAccounter，为空时取表体的记账人；verified_at 为空串。state 另有 line_count、posted_lines、vouch_type、vouch_name（20 入库调整单、21 出库调整单，其他类型为空串）、auto（cAuto=TRUE，期末处理自动生成的出库调整单）。
• 记账、期末处理（会生成、删除出库调整单）走 ia/post、ia/period_end（§32）。数据权限按存货（表体），仓库、部门、业务员为可空列。

存货调价单（inventory_price_adjust，表 SA_InvPriceJustMain / SA_InvPriceJustDetail，id 是表头 id，code 是 ccode）只读：head、lines 是原列，另加 dep_name、inv_name、inv_std；state.verified 按审核人 cverifier 非空，verified_at 是审核日期 dverifydate（未审核为空串）。审核后 U8 把新价写进存货价格表（reports/price_list 的 kind=inventory）。列名按 U8 数据字典，尚未用实际数据核对。

单据附件 vouchers/attachments/list#

请求同 vouchers/load（type、id），权限同读取该单据（功能权限和记录级数据权限，越权 403）。只查数据库，不调用 U8 组件。单据不存在 404 not_found。

U8 单据卡片上的「附件」登记在通用附件表 VoucherAccessories：VoucherTypeID 是卡片号（vouchers.CardNumber，如销售订单 17），VoucherID 是该卡片主键列（vouchers.VchTblPrimarykeyNames，应收应付单是 cLink）的值。桥列出同一张表头表的全部卡片（例如发货单和退货单共用 DispatchList）下挂在这张单据上的附件。

响应 {"ok":true,"type","id","items","truncated"}。每项 card（卡片号）、file_id、name（原文件名）、memo、size（内容存在 U8 库里时的字节数，否则 null）、stored（database：内容在 FileContent 列；file_server：只登记了 U8 文件服务器上的文件标识）。按文件名排序，最多 500 个，超过时 truncated 为 true。只列清单，不提供下载（limitations.md）。各键按 U8 附件表结构写出，尚未用实际附件核对，使用前请先核对 card、file_id、stored。

客户端命令：attachments --type <类型> --id <主键>。

6. 审核 vouchers/verify#

请求：type、id、action（verify 审核，unverify 弃审；采购发票、销售发票另有 arap_verify、arap_unverify）。

成功响应：type、id、action，以及（有则返回）verified_by、verified_at、acc（收付款单、应收应付单和生产订单可能不返回）、state、generated、ar_verifier（销售发票的应收审核人）。

通用规则：

• 调用前单据已经处于目标状态：409 state_mismatch。
• 成功的判定：U8 返回成功，桥在本连接提交后 @@TRANCOUNT 为 0，并且在一条新连接上（不加 NOLOCK）读到目标状态：审核人和审核日期都非空、审核人等于登录操作员的姓名；弃审则两者都空。回读对不上是 409 state_mismatch，这时事务已经提交，不要再发同一次审核。

销售#

• 销售发票的审核是复核、弃复，状态列 cChecker、dverifydate。应收已审核的发票弃复由 U8 拒绝，409 u8_rejected（U8 原文）；先用 arap_unverify 弃审。
• 红字销售发票：只接受参照退货单生成的红字发票（表头 iDisp=1、没有发货单的 SBVID 指回本发票、每一行都指向退货单行），销售组件用红字的 VT（26 → 1，27 → 3）；先开票等其他红字发票 400「仅支持蓝字销售发票和参照退货单生成的红字销售发票」。
• 退货单（sale_return）：同发货单的审核、弃审，组件换成红字发货单（VT 10）。id 必须是红字发货单（bReturnFlag=1、cVouchType=05），否则 400「该单据不是退货单（红字发货单）」；审批流检查同发货单。

应收审核、应付审核（arap_verify、arap_unverify）#

只收采购发票（应付款管理的审核，登录子系统 AP）和销售发票（应收款管理的审核，登录子系统 AR）；其他类型 400 bad_request「只有采购发票、销售发票支持应收应付审核」（经 API 时请求校验就失败）。只收专用、普通发票（采购 01 / 02，销售 26 / 27），其他发票类型 400「只支持专用发票和普通发票」（先于状态检查）。

• 调用：UFAPBO 的 clsPub_AP，先 PUVouchCanSign / SAVouchCanSign，再 Sign_PurBill / Sign_SaleBill（弃审 CancelSign_PurBill / CancelSign_SaleBill），都在桥的事务里。
• 审核要求：已复核（采购发票 cVerifier、销售发票 cChecker 非空，否则 409「发票未复核，请先复核」）；未审核；IsWfControlled / iswfcontrolled 为 0（否则 409 workflow_enabled）；采购发票没有网络锁（iNetLock）；表体没有 cClue；登录日期所在年月应付（应收）未结账（GL_mend.bflag_AP / bflag_AR，否则 409「应付已结账」/「应收已结账」）。
• 弃审要求：已审核；明细没有凭证号（409「已生成凭证，请先删除凭证」）；没有核销或其他处理（cProcStyle 不等于单据类型的行，或本单作为对方单据的行：409「已核销或有其他处理，请先取消」）；审核登记行所在期间未结账。审核人是否本人由 U8 判断。
• 除上面的 400 和 workflow_enabled 外，拒绝都是 409 state_mismatch；CanSign 或 Sign 返回 false 时 409 u8_rejected（U8 原文）。
• 写入：cPBVVerifier（销售发票 cVerifier、dArverifydate）为登录操作员姓名、日期为登录日期，在 Ap_Detail（Ar_Detail）登记原始行；不生成凭证。登记行的往来科目 cCode 由桥在同一事务里调 U8 的 clsPub_AP.CusVenToCtrlKMForSAPU（往来单位、币种、销售 / 采购类型、存货、AR / AP）补上（与 U8 客户端审核的结果一致，制单按这一列取往来科目）；取不到时整笔回滚，409 state_mismatch「取不到往来单位 … 的往来控制科目，请先在 U8 应收应付的科目设置里设好」。
• 桥在提交前核对审核人与登记行，提交后在新连接上回读：不符或回读失败都是 504 outcome_unknown（已提交，先核对，不要直接重投）。
• 响应的 verified_by、verified_at 是应付（应收）审核人和日期，state 为 arap_verified、arap_verifier、arap_verified_at、gl_voucher（任一明细行已有凭证号）。
• 功能权限：采购发票 AP050104 审核、AP050105 弃审，销售发票 AR050104、AR050105；数据权限按表头供应商（客户）和部门。

采购#

• 采购发票：verify / unverify 是采购管理的复核、取消复核（VoucherCO_PU 的 ConfirmBill / CancelconfirmBill），状态列 cVerifier、cAuditDate。只收普通采购的专用、普通发票（01 / 02）；IsWfControlled=1 或采购发票已发布审批流时 409 workflow_enabled。红字发票（bNegative=1）同样可复核、取消复核（Init 的 bPositive 传 false）。复核要求未复核；取消复核要求已复核，且未在应付款管理审核（409「已在应付款管理审核，请先弃审」）、未结算、未现付、没有应付明细，否则 409 state_mismatch。U8 拒绝时 409 u8_rejected（U8 原文）。桥在提交前核对复核人确实写入或清除，提交后在新连接上回读；回读失败 504 outcome_unknown。
• 采购退货单（purchase_return）：与到货单同一组方法（ConfirmArr / CancelconfirmArr），用红字的 Init 参数（§11）。id 不是退货单（iBillType 不为 1）时 400「不是采购退货单」；弃审时已报检或已入库 409 state_mismatch。到货单（arrival）只收蓝字。
• 请购单（purchase_requisition）：VoucherCO_PU 的 ConfirmApp / CancelconfirmApp，状态列 cVerifier、cAuditDate。只收普通采购；IsWfControlled=1 或请购单已发布审批流时 409 workflow_enabled；表头或任一行已关闭 409。弃审时已被采购订单参照（PO_Podetails.iAppIds）或已有累计订货、合同、询价数量 409 state_mismatch。

库存#

• 调拨单：审核成功时 U8 生成其他出库单和其他入库单（都未审核），响应多一个 generated: [{"type":"other_out","id":…},{"type":"other_in","id":…}]。弃审删除这两张生成单；生成单已审核时 U8 拒绝。
• 形态转换单（shape_change）：同调拨单（12 参 Verify），生成转换出库（其他出库，cSource=形态转换、cBusCode 为形态转换单号）和转换入库（其他入库）各一张，响应带 generated。弃审时生成单由 U8 删除；生成单已审核时 409「生成的其他出入库单已审核，请先在 U8 里弃审」。形态转换单或盘点单生成的其他出入库单不能单独弃审（409「该单据由形态转换单生成，不能弃审」「……由盘点单生成……」），也不能单独修改、删除（来源不是库存）。
• 调拨申请单（transfer_request）：只写审核人（9 参 Verify），不生成调拨单。弃审前表头或任一行已关闭、已有调拨单参照（TransVouchs.iTRIds）或累计调拨数量不为 0 时 409 state_mismatch。
• 盘点单（stock_check）：不支持审核、弃审（U8 组件生成盘盈 / 盘亏其他出入库单时报「类型不匹配生单时出错」）。桥在任何 COM 调用之前 400「盘点单审核暂不支持（U8 生成盘盈盘亏单时报类型不匹配），请到 U8 客户端审核」；经 API 时类型不在可审核名单里，同样 400。在 U8 客户端审核的盘点单，审核人列是 cAccounter、审核日期 dveridate。
• 货位调整单（position_adjust）：9 参 Verify / UnVerify，不生单。U8 审核时写货位台账 InvPosition（cvouchtype=19，每行一出、一入两条）并改货位结存 InvPositionSum，弃审退回。桥在同一事务里：调用前按本单的净变动查结存（审核看调出，弃审看退回，按货位、存货、批号、自由项合计，不够 409 stock_shortage）；调用后核对审核人（审核后是登录操作员且有审核日期，弃审后都为空）、本单的货位台账行数（审核后是行数的 2 倍，弃审后 0）和每个结存的变动等于调整单，不符回滚 409 u8_rejected。响应另有 ledger_rows（台账行数）和 bin_moves（每个结存的 wh、pos、inv、batch、before、after）。审核人列 chandler、审核日期 dVeriDate。
• 期初结存单（stock_opening）：只有审核、弃审（U8 的库存期初没有记账），第二级写入（§3、§7）。走 USERPCO.VoucherCO，审核日期由桥在同一事务里改成单据日期（与 U8 录入的期初单一致）；存货核算已期初记账后弃审 409 state_mismatch。

质量#

• 报检单不开放单独审核。来料报检单（qm_incoming_inspect）审核、弃审都 400 bad_request「来料报检单不支持单独审核、弃审（保存时由 U8 自动审核；删除时桥会先弃审）」（经 API 时请求校验就失败）。产品报检单（qm_product_inspect）只收 action=unverify，verify 400「产品报检单只支持弃审（action=unverify）：审核由 U8 在保存时按选项自动完成」（经 API 时请求校验就失败，直接调桥在登录前 400）。
• 产品报检单弃审走 VoucherOperate(…, "unconfirm", …)（同删除前的弃审，U8 自己提交，预演只做校验），要求已审核（409「单据未审核」）且还没有检验单（行累计检验数量大于 0 或有检验单关联，409「已有检验单，不能弃审」）；回读同删除。弃审后接口不能再审核，也不能修改（§8「质量单据」），只能删除或在 U8 客户端处理。功能权限 QM02020107，数据权限按每行存货、仓库和表头部门。
• 报检单只在保存时按质量选项（来料 bArrInspectAutoVerify、产品 bProInspectAutoVerify）自动审核，U8 组件的审核对未审核的报检单无效（u8-notes.md「质量单据新增」）。选项关闭的账套里经本服务生成的报检单是未审核的，不能用来生成检验单。
• 检验单（QM03、QM04）不能直接审核，请用 workflow/*。经 API 时请求校验就失败（400「请求参数无效」）；直接调桥 400「该单据类型不支持直接审核」。
• 不良品处理单（qm_incoming_reject、qm_product_reject）：U8 质量管理组件的 AuditVoucher / UnAuditVoucher（先 GetTheVoucher 载入），登录子系统 QM，由 U8 自己提交（不在桥的事务里）。受审批流控制（IsWfControlled=1）或已提交审批（iVerifyStateNew 非 0）的 409 workflow_enabled，请用 workflow/*。审核要求未审核，弃审要求已审核且没有下游（同删除的下游判断），否则 409 state_mismatch。U8 拒绝时 409 u8_rejected（ErrBag 原文）；U8 报单据不存在或没有数据权限时 404。调用后在新连接上回读审核人（CVERIFIER），回读失败或调用异常且状态未到 504 outcome_unknown。响应另有顶层 verified_by、verified_at（弃审后为空串）。功能权限：来料 QM02010305 审核、QM02010307 弃审，产品 QM02020305、QM02020307；数据权限按表头供应商、存货、仓库。
• 其他检验单（qm_other_check）：组件 UFQMCo.clsOtherCheckVoucherCO，调用、回读、错误码和响应同不良品处理单（预演只做校验）。没有审批流（万一受控或已提交审批 409 workflow_enabled）。弃审要求没有下游：累计入库数大于 0、被入库单 rdrecords01/08/09/10.iCheckIdBaks 引用、已有不良品处理单都是 409 state_mismatch。功能权限：审核 QM02060205、弃审 QM02060207；数据权限按表头部门、存货、仓库。
• 其他报检单（qm_other_inspect）：组件 UFQMCo.clsOtherInspectVoucherCO，调用、回读、错误码和响应同不良品处理单。用于补审新增后没有自动审核的单据（auto_verify_error，§7），也可弃审后再审核。弃审要求还没有其他检验单（INSPECTID 指向本单或行 BFLAG=1，否则 409「已有其他检验单，不能弃审」）。功能权限：审核 QM02060105、弃审 QM02060107；数据权限按报检部门、每行存货、仓库。

应收应付单据、生产订单、物料清单#

• 收付款单、应收应付单走 UFAPBO 的 Sign / CancelSign，响应带 state：verified、verifier、verified_at、gl_voucher、settled、amount、unsettled_amount。
• 生产订单（id 是 MoId）走 U8 API 框架，登录子系统 MO。state.verified 表示全部明细行都已审核，另有 closed、verifier、verified_at。U8 生产制造服务（U8MPool）没在运行时 503 u8_unavailable；受审批流控制的订单 409 workflow_enabled。
• 物料清单（bom，id 是 BomId）走 U8 API 的 BomAuditing / BomUnauditing（参数是母件 PartId、1、版本号字符串），登录子系统 BO。审核只收未审核（Status=1），弃审只收已审核（Status=3），停用的 409「物料清单已停用」；IsWFControlled=1 409 workflow_enabled。功能权限要有物料清单卡片的「审核」（BO01001A）或「弃审」（BO01001UA），母件存货要在数据权限内（403）。U8 审核时会顺延同一母件其他版本的失效日期；弃审时 U8 不查生产订单是否在用这个版本，桥也不拦。桥在新连接上回读 Status，没到目标时：调用异常 504、IPC 错误 503、U8 返回成功却不符 409。响应带 code（母件）、version 和 state（同读取）。

专用审核路由#

sale-orders/verify（id 为 SO_SOMain.ID）和 dispatches/verify（id 为 DispatchList.DLID）：请求 id、action，成功 {"ok":true,"acc","id","action","verified_by","verified_at"}。verified_by 取 cVerifier，verified_at 优先 dverifysystime，否则 dverifydate。

发货单只接受蓝字：红字（bReturnFlag）、cVouchType 不是 05、期初 bFirst = 1 都直接拒绝。已有退货单行（iCorID）指向其明细的发货单不能弃审，409「发货单已有退货单，请先删除退货单」（vouchers/verify 的 dispatch 同样）。

这两条路由检查 U8 审批流：AuditBizObjects 里没有该表的行，或审批流表不可用，409 workflow_unknown；有行并且 Table_WorkFlowRelease 里该业务对象有 Status = 0、事件为 <对象ID>.Submit 的发布，或单据自己的 iswfcontrolled 为真，409 workflow_enabled。查不到不当成「没有启用」。

7. 新增 vouchers/create#

请求：type、head（一层对象，值只能是字符串、数字或布尔）、lines（1 到 200 行，同样是一层对象）。

允许的类型：

• 通用名单（本节「可写字段」）：sale_order、purchase_order、other_in、other_out、transfer、purchase_in（无来源）、purchase_requisition、shape_change、transfer_request、stock_check、position_adjust、stock_opening；
• 无来源新增：dispatch、sale_invoice（先开票）、arrival、material_out、qm_other_inspect；
• 应收应付：ar_receipt、ap_payment、ar_bill、ap_bill、ar_refund、ap_refund（§12、§35）；
• 自有字段：production_order（1 到 50 行）、bom；
• 见 §35：sale_out（无来源）、sale_return_apply、purchase_settle（手工结算）。

其他类型 400「该单据类型不支持新增」。固定资产变动单不在 API 里（§15「固定资产卡片与设备台账的写入」）。

成功：{"ok":true,"type","id","code","state"}。采购订单、请购单、生产订单和应收应付四种另有 lines（保存后的表体行数）；生产订单另有 allocates、details、warnings，物料清单另有 version、components。收付款单和应收应付单可能不带 state。新单据保持未审核（其他报检单例外，见下）。

字段值不能填主键和来源行 id（id、autoid、isosid、idlsid、iposid、poid、dlid、cbsysbarcode）、单号、制单人、审核人、ufts、editprop，也不能填销售订单行的关闭人和累计数量（cscloser、ifhquantity、ikpquantity、foutquantity）。行号 irowno 可以填。不在该类型允许名单里的字段是 400「不能设置字段 x」，在名单里但不在 U8 行集 schema 里的是 400「未知字段 x」。自定义项和自由项不接受前导零（cdefine01、cfree07）。

可写字段#

表头自定义项 cdefine1 到 cdefine16，表体自定义项 cdefine22 到 cdefine37，自由项 cfree1 到 cfree10。除此之外：

修改用同一份名单。金额、价税、辅数量由桥计算（U8 的业务组件保存时不重算），算法见 u8-notes.md「金额」。有计量单位组的存货还要辅计量，缺了 U8 会拒绝。

必填项与缺省：

• 采购订单：供应商（400「必须填写供应商」）、部门（400「必须填写部门」）；每行存货（400「必须填写存货编码」）、大于 0 的数量（400「数量必须大于 0」）、无税单价或含税单价之一（400「必须填写单价或含税单价」）。表头缺省：采购类型 cptcode 取默认采购类型（PurchaseType.bDefault = 1），没有时不写、由 U8 判断（U8 要求时 409 u8_rejected 带原文）；业务类型 cbustype「普通采购」；币种 cexch_name 取本位币（foreigncurrency.iotherused = -1），汇率 nflat 1；表头税率 itaxrate 13（固定缺省，请按账套需要自己给）；日期 dpodate 取登录日期。行税率 ipertaxrate 不给时：请求表头给了 itaxrate 就跟表头，否则取存货档案的 iTaxRate，档案没填仍跟表头（修改时新增的行同理）。
• 销售订单：制单人写登录操作员姓名。币种同无来源发货单：不带币种或填本位币时写本位币、汇率 1，另给的汇率必须是 1（400 head.iexchrate）；外币必须给大于 0 的汇率（U8 组件不补，汇率空时报「汇率不可以小于等于0」）。表体预完工日期缺省依次取行上的预发货、表头预完工、表头预发货、单据日期；预发货日期（U8 模板必输）缺省取表头预发货日期（早于本行预完工时取预完工，U8 要求预完工不晚于预发货），没有时取本行预完工日期，再取单据日期。多计量单位存货由桥按存货档案补计量单位组、单位、换算率和件数。
• 调拨单：转出仓（400「必须指定转出仓库」）、转入仓（400「必须指定转入仓库」）。收发类别 cordcode、cirdcode 只用调用方给的，桥不补缺省；U8 要求时 409 u8_rejected 带原文。
• 采购入库单（无来源）：仓库（400「必须指定仓库」）、供应商（400「必须指定供应商 cvencode」）；每行存货、大于 0 的数量。
• 请购单：每行存货（400「必须填写存货编码」）、大于 0 的数量 fquantity（400「数量必须大于 0」）。表头没有必填项。

形态转换单、调拨申请单、盘点单#

三类都走 USERPCO.VoucherCO（登录子系统 ST），与调拨单同一组方法：Insert 13 参、Update 12 参、Delete / UnVerify 9 参，都在请求连接的事务里；单号按 U8 编号规则取（sVouchType 15、62、18，卡片 0305、0324、0307）；空白模板取视图 AssemM / AssemD、transrequestm / transrequestd、checkm / checkd。备注、批号用各表自己的列名（cavmemo、ctvmemo、ccvmemo，cavbatch、ctvbatch、ccvbatch），不做 cmemo 别名。

• 形态转换单（shape_change，表 AssemVouch / AssemVouchs，只认 cVouchType='15'，同表的组装单 13、拆卸单 14 当作不存在）：表头没有仓库，每行要有仓库 cwhcode（400「形态转换单每行都要有仓库 cwhcode」）、存货、大于 0 的 iavquantity、bavtype（「转换前」或「转换后」）；igroupno 缺省 1，每组至少一行转换前、一行转换后（400「形态转换每组（igroupno）都要有转换前和转换后的行」），修改后按整单再核一次。日期 davdate 缺省取登录日期；收发类别缺省按名称取末级类别「转换出库」（cordcode）、「转换入库」（cirdcode），账套里没有就留空。
• 调拨申请单（transfer_request，表 ST_AppTransVouch / ST_AppTransVouchs）：转出仓、转入仓必填（同调拨单的 400）；每行存货和大于 0 的 itvquantity。核准数量 itvchkquantity：0 或以上，最多 6 位小数，不能大于申请数量（400「核准数量不能大于申请数量」；修改时只调小申请数量也按整行复核）；新增时（含修改时新增的行）不给取申请数量，修改已有行时只在送了才改；核准件数按换算率补。U8 审核不写核准数量；参照生成调拨单按核准数量算，核准为 0 的行不能参照。不做关闭 / 打开。
• 盘点单（stock_check，表 CheckVouch / CheckVouchs）：盘点仓库 cwhcode 必填（400「必须指定盘点仓库」）；每行存货和实盘数量 icvcquantity（可以是 0）。账面数量 icvquantity 不给时按现存量填（CurrentStock 该仓库、该存货、同批号、同自由项 1–10 的合计，没给的批号和自由项按空比；不分货位）。盘盈数量 iAdInQuantity = 实盘 − 账面（大于 0 时，否则 0）、盘亏数量 iAdOutQuantity = 账面 − 实盘（大于 0 时，否则 0），件数 iAdInNum / iAdOutNum 同理，都由桥算（同 U8 界面），不收调用方的值。同一仓库已有未审核的盘点单 409「该仓库已有未审核的盘点单」；存货、批号、自由项都相同的行重复 400。日期 dcvdate、盘点日期 dacdate 缺省取登录日期；收发类别缺省按名称取末级类别「盘盈入库」（cirdcode）、「盘亏出库」（cordcode），账套里没有就留空（可自己给）。不能修改，不做复盘，不能审核（§6）。

货位调整单#

货位调整单（position_adjust，表 AdjustPVouch / AdjustPVouchs，U8 单据类型 19，卡片 0313）在同一仓库内把存货从一个货位挪到另一个货位，不动仓库现存量。新增、审核、弃审、删除是普通写入，按写入策略放行。不能修改：vouchers/update 400「货位调整单不能修改，请删除后重新录入」。

• 新增走 USERPCO.VoucherCO.Insert("19")，空白模板取视图 AdjustPM / AdjustPD，VT_ID 113，单号按卡片 0313 的编号规则取。表头仓库 cwhcode 必填（400「必须指定仓库」），日期 ddate 缺省取登录日期。每行存货、调出货位 cbposcode、调入货位 caposcode、大于 0 的 iquantity 必填，调出和调入相同 400「调出货位和调入货位不能相同」；件数按换算率补，不收 inum。
• 调用 U8 之前桥核对：仓库存在、是货位管理（Warehouse.bWhPos=1，否则 400「仓库 x 不是货位管理仓库」）、不是代管仓（bProxyWh=1 400）；两个货位都是本仓库的末级货位（Position.bPosEnd=1，否则 400，field 指到行）；存货存在；保质期管理（bInvQuality=1）的存货 400；调出货位上有 VMI 供应商（cvmivencode）结存的 400；批次管理的存货必须给 cbatch，非批次管理不能给（400 lines.N.cbatch）。结存按货位、存货、批号、自由项 1–10 合计（InvPositionSum），按本单的净变动核对：同一张单据里调入某货位的行先抵掉从它调出的行（A→B、B→C 两行时 B 净变动为两者之差），净减少的不能超过当前结存，否则 409 stock_shortage。U8 在中间状态拒绝时原文 409 u8_rejected、整笔回滚。
• 保存后、提交前桥在同一事务里回读：新主键能读到，表头仓库、表体行数和逐行的存货、调出货位、调入货位、批号、数量与请求一致，还没有货位台账，涉及的货位结存没有变；不符回滚 409 u8_rejected。
• 保存时 U8 不写货位台账，审核时才写（§6）。删除只删未审核的（已审核 409「单据已审核」）；万一有货位台账，同其他库存单据先 ClearPosition 再以 bList=true 删除（u8-notes.md「库存」）。删除在提交前确认表头、表体都已不在，否则回滚 409。
• 读取（vouchers/load）是 SQL：表头、表体照表，另有 positions：本单的货位台账（id、line_id、inbound（1 入、0 出）、pos、inv、batch、qty、date、handler），未审核时为空；超过 1000 行只给前 1000 行并带 positions_truncated: true。列表的增量只按表头 ufts（表体没有 rowversion）；附加列 memo、source、created_at、modified_at。
• 功能权限：查询 ST010807；新增、删除要「录入」ST010806（删除没有单独的功能 id），审核 ST010802、弃审 ST010803，写入时在任何 COM 调用之前现查，没有 403 no_permission。数据权限：仓库（表头）、存货（行）、部门和业务员（可空）。

其他报检单#

其他报检单（qm_other_inspect，QM11，VT 361）没有来源单据，用 vouchers/create 新增。走 U8 质量管理组件 UFQMCo.clsOtherInspectVoucherCO（基于 VO 的接口，同不良品处理单），登录子系统 QM。

{"type": "qm_other_inspect",
 "head": {"dDate": "2026-01-15", "cInspectDepCode": "D901", "cDefine10": "LOT-001"},
 "lines": [{"cInvCode": "A01", "quantity": 100}]}

• 表头只收 dDate（缺省登录日期）、cInspectDepCode（报检部门，省略时取本操作员最近一张其他报检单的报检部门）、cDefine1…16、chDefine11…16。表体 1 到 200 行，每行 cInvCode、quantity（必填），可带 iTestStyle（检验方式，0 到 3 的整数，省略时取存货档案的 iTestStyle，档案为空取 3）和 cWhCode。不收来源字段（source_line_id、CSOURCE* 都是 400）。存货、仓库、部门不存在 400。
• 存货有换算（iGroupType 不为 0）时桥按存货的库存计量单位带辅计量和件数（CUNITID、FCHANGRATE、FNUM = 数量 / 换算率，按账套件数小数位四舍五入）。检验类型写 OTH，制单人（报检人）是操作员姓名，单号按 U8 编号规则取（卡片 QM11），取了不退。
• U8 单据模板（VT 361）的必输项没有填是 400「缺少必输字段 …（U8 单据模板设置为必输）」；模板可能把表头自定义项、扩展自定义项设为必输。
• 保存由 U8 自己提交，不在桥的事务里；预演在必输项核对之后、取号之前停。
• 自动审核：VO 接口的 AddVoucher 不按质量选项 bOtherInspectAutoVerify 审核。选项为 True 时桥在保存后接着 GetTheVoucher + AuditVoucher（同 U8 客户端保存即审核），只在操作员有审核权限（QM02060105）时做，state.verified 从回读取。补审核没做（「无审核权限，报检单保存为未审核」）或没成功（组件、载入、U8 拒绝、回读等任何错误）时，新增仍返回 200 和新单的 id、code，另带 auto_verify_error，单据是未审核的：用 vouchers/verify 补审（§6），不要重发新增。
• 保存后在新连接上按单号（U8 换了号时按调用前最大主键之后、本操作员建的唯一一张）找新单，核对制单人和表体（存货、数量）；对不上或读不到 504 outcome_unknown。
• 删除见 §9。功能权限：新增 QM02060103、删除 QM02060104（删除已审核的另要弃审 QM02060107）、保存后补审核要 QM02060105；数据权限按报检部门、每行存货、仓库。

期初结存单#

期初结存单（stock_opening，表 rdrecord34 / rdrecords34，U8 单据类型 34）是库存管理的期初数据。读取、列表照常开放；新增、删除、审核、弃审是第二级写入（§3），在登录 U8 之前检查：开关关闭 403 feature_disabled，账套不在 testAccounts 里 403 test_account_only「期初结存单只对配置为测试账套的账套开放」。

• 新增走 U8 的 EAI 导入（U8Distribute.iDistribute.ProcessEx，报文根 storeqc），不走 USERPCO.VoucherCO.Insert（无界面调用时 U8 报「在对应所需名称或序数的集合中，未找到项目」）。U8 的期初结存单一张一行，所以请求的每一行建成一张单据，单号由 U8 编。成功：{"ok":true,"type","id","code","docs":[{"id","code","line","wh","inv","qty"}],"count","date"}：docs 按请求行次序，line 是请求 lines 的下标（从 0 开始）；顶层 id、code 取第一张；count 是张数；date 是单据日期；传入的日期未采用时另有 warnings。
• 字段名单见「可写字段」，行上的 cwhcode 覆盖表头的仓库；其他字段 400「期初结存单不能设置字段 x」。每行要有仓库（400「缺少仓库 cwhcode」）、存货（400「缺少存货编码 cinvcode」）和大于 0 的数量；只给单价或金额时桥补另一项。仓库、存货不存在，批次管理的存货没填批号（或未启用批次却填了），货位管理仓库的货位不对，数量小数位超过账套的存货数量小数位，都是 400 并带 field，在调用 U8 之前查完，避免只导入一部分行。
• 单据日期固定为库存启用日前一天（AccInformation 的 dSTStartDate 减一天），传入的 ddate 不用，响应 warnings 带提示；库存管理未启用 409 state_mismatch。
• 登录日期：新增、删除、审核、弃审都以库存启用日（第一个库存期间的第一天）登录 U8，不用请求的 date（期初日可能落在没有会计期间的年度）。请求的 date 与启用日不同时，桥为本请求另登录一次、用完即关，不进登录缓存；请求连接和事务不变。
• 预演：新增是 validate 模式，只做调用 U8 之前的检查（字段、仓库、存货、分级检查），不导入，响应 detail.entries 是将要建成的张数；删除、审核、弃审是 rollback 模式。
• EAI 导入由 U8 自己提交、不在请求的事务里。部分行被 U8 拒绝时桥删掉本次已导入的单据再 409 u8_rejected（多行时按「第 n 行：原文」列出）；导入结果与请求对不上、回读失败或补偿删除失败时 504 outcome_unknown，先按列表核对，不要直接重发。
• 不能修改：vouchers/update 400「期初结存单不能修改，请删除后重新录入」（API 层就拦下）。
• U8 的拒绝原样透出：库存启用的第一个月已月结时，新增、删除 409 u8_rejected「库存启用的第一个月已月结,不可以增加删除期初!」。存货核算已做期初记账后，新增、删除、弃审 409 state_mismatch「存货核算已期初记账，不能修改库存期初结存」；审核不受影响。
• 审核后桥在同一事务里把审核日期写成单据日期（U8 写的是登录日期）。

无来源采购入库单#

purchase_in 的新增只做来源为库存的单据：表头 cSource 写「库存」，业务类型「普通采购」，VT_ID 27，本币、汇率 1。蓝字为缺省，表头 red: true 为红字退库（见本节末条）。参照采购订单或来料检验单入库用 vouchers/generate。

• 采购选项「普通业务必有订单」（AccInformation 里 PU / bPTHavePO 为 True）打开时，蓝字新增、修改里带新增行都是 409「账套设置了普通业务必有订单，不能无来源录入采购入库单」；红字退库不受此限制。
• 仓库不存在 400。仓库启用货位管理（Warehouse.bWhPos）时每行必须填末级货位 cposition（400「仓库有货位管理，必须指定货位 cposition」），货位要属于该仓库（Position.cWhCode）且是末级；未启用货位管理的仓库不能填货位。桥只写表体 cPosition，货位台账由 U8 写。修改时货位管理仓库的单据不能换仓库（409）。
• 采购类型 cptcode 不填时取默认采购类型（PurchaseType.bDefault = 1），收发类别 crdcode 不填时取该采购类型的收发类别；都没有是 400。
• 供应商不存在 400；供应商币种不是本位币（foreigncurrency.iotherused = -1）409「外币供应商的采购入库单本期不支持」。
• 存货不存在 400；需来料检验（bPropertyCheck）409「该存货需来料检验，不能直接入库」；不是外购属性 409。批次管理或保质期管理的存货必须填 cbatch，保质期管理的还要填 dmadedate 和 dvdate（imassdate、cmassunit 不填取存货档案）；未启用批次管理的存货不能填 cbatch。
• 单价三选一：含税单价 ioritaxcost、无税单价 iunitcost、无税金额 iprice（按金额反算单价）。含税单价不能和另两个同时给。都不给时不写金额。税率 itaxrate 不填取存货档案，给了单价又没有税率是 400。桥按采购公式补原币、本币的单价、金额、税额、价税合计（u8-notes.md「金额」），bTaxCost 按所给单价写 1 或 0。
• 采购入库单已启用审批流时 409 workflow_enabled。
• 红字退库：表头 red 为 true（布尔，别的值 400「red 必须是布尔」；false 或省略是蓝字）。请求照蓝字写，数量、单价填正数，上面各条校验照旧（「普通业务必有订单」除外，与 U8 客户端一致）；桥写表头 bredvouch=1，表体数量、件数和原币 / 本币的无税金额、税额、价税合计取负（单价不变，同 U8 里手工录的红字退库），Insert 的 bIsRedVouch 传 true。没有来源，不回写。红字单可以删除、审核、弃审，不能修改（409「红字采购入库单不支持修改」）。红字是出库方向，保存前另查（同销售出库的批号 / 货位预检）：批次存货必须填 cbatch（400），保质期管理的存货 409；表头仓库里该存货（批号、自由项）的可用量、填了货位的行在该货位上的结存不够 409 stock_shortage（多行合计）。保存后在新连接上确认 bredvouch=1 且每行数量为负，否则 504 outcome_unknown（带新主键）。meta 的采购入库新增表头列出 red。

无来源发货单、先开票销售发票、无来源到货单、无来源材料出库单#

不挂来源单据的新增。账套选项不允许时一律 409 state_mismatch，消息带 U8 选项名：

可写字段（另加表头 cdefine1–cdefine16；销售表体另加 cfree1–cfree10、cdefine22–cdefine37）：

• 业务类型固定「普通销售」/「普通采购」/「领料」，蓝字，制单人写登录操作员姓名。销售的价税按单行 BodyCheck 算（同销售订单）；到货单按采购公式算（ioricost 与 ioritaxcost 只能给一个，都不给按 0；税率缺省取存货档案；采购类型 cptcode 缺省取默认采购类型，没有就不写）。
• 币种、汇率：发货单、发票的 cexch_name 不填或填本位币时写本位币、汇率 1（另给的 iexchrate 必须是 1，否则 400）；填外币时必须给大于 0 的 iexchrate（400「外币 x 必须填写汇率 iexchrate」）。到货单固定本位币、汇率 1，只收本位币供应商（外币 409「外币供应商的到货单本期不支持」）。材料出库不涉及币种。
• 部门：发货单、发票不填 cdepcode 时取客户档案的分管部门，到货单取供应商档案的分管部门；都没有时在调用 U8 之前 400「无来源发货单（销售发票、到货单）需要部门 cDepCode」，field 为 head.cdepcode。材料出库的部门可选。
• 字段不在名单里 400「不能设置字段 x」，不在 U8 模板里 400「未知字段 x」；缺必填 400「必须填写 x」；数量要大于 0。
• 到货单：存货不是外购属性 409，浮动换算率存货 409。材料出库：批次管理的存货必须填 cbatch，保质期管理的存货 409；货位规则同无来源采购入库（缺货位 400，field 为 lines.<i>.cposition；桥只写表体 cPosition，货位台账 InvPosition 由 U8 写）。
• 删除走各自原有的删除（材料出库另放行来源「库存」）。先开票发票删除时 U8 连带删除它生成的发货单；桥在同一事务里核对，还在就回滚 409「先开票生成的发货单未随发票删除，请到 U8 客户端处理」。
• 锁键：先开票发票另锁 new:dispatch，到货单另锁 new:purchase_return（同生单的互锁）。

请购单#

purchase_requisition（PU_AppVouch / PU_AppVouchs，卡片 27）走 VoucherCO_PU，登录子系统 PU，新增 VoucherSave2 状态 2、修改状态 1，单号由 GetVoucherNO(头, "27", …) 取。

• 表头 ddate 不填取登录日期，cbustype 固定「普通采购」，制单人写登录操作员姓名。日期写 yyyy-MM-dd，否则 400。
• 表体数量是 fquantity（不是 iquantity）。需求日期 drequirdate 不填取单据日期；建议订货日期 darrivedate 可省。多计量单位存货由桥按存货档案补采购单位、换算率和件数。
• 单价可省；给了就二选一：原币无税单价 ioricost 或原币含税单价 ioritaxcost（同给 400「单价和含税单价只能填一个」）。税率 ipertaxrate 不填取存货档案，再没有用 13。币种固定本位币（foreigncurrency.iotherused = -1）、汇率 1，桥补原币和本币的单价、金额、税额、价税合计（fmoney 是本币价税合计），bTaxCost 按所给单价写 1 或 0。
• 修改：line_id 是 PU_AppVouchs.AutoID；只改未审核、未关闭、没有下游的普通采购请购单。改了数量、单价或税率的行重算金额。要改的行不是本位币、汇率 1（在 U8 里录的外币行）时 409 state_mismatch。行操作里空的 cinvcode 当作没传。修改、删除、弃审在事务里调用 U8 之前再查一遍下游（锁住请购行），查到就回滚并 409。

生产订单#

production_order 走 U8 API 框架的 MOrderAdd（与审核同一个 U8ApiComBroker，登录子系统 MO），不走通用字段名单，字段名是下面这些（不分大小写），其余 400「不能设置字段 x」：

• 行号按顺序从 1 编，订单类别固定「标准」（DMoClass=1）。不收销售订单关联（DOrderType / DOrderCode / DOrderSeq）。
• 不送子件，U8 按存货在开工日期有效的标准 BOM 自动展开用料（Usp_MO_GenAllocate），数量为 BaseQtyN / BaseQtyD × qty。存货没有有效的标准 BOM 时 U8 照样保存、不展开，该行 allocates 为 0，响应带 warnings。
• 新订单行 Status=2（未审核），制单人是操作员编码。审核、弃审走 §6，修改走 §8「生产订单」（U8 的 MOrderUpdate 会清空并重写全部子件，桥把 U8 加载出的子件全部重送并回读核对），删除走 §9，关闭走 §10。
• 功能权限要有生产订单输入卡片的「增加」（MO02001N），否则 403；每行的存货、部门、仓库还要在操作员的数据权限内（403）。
• 成功另给：allocates（全部行的子件行数）、details（每行 line_id、sort_seq、inv_code、qty、status、allocates）、warnings（有行没展开子件时）。
• 编码类字段（单号、存货、类别、部门、仓库）和备注去掉首尾空白后不能含控制字符（API 层拒绝 Unicode 类别 C 的字符，如制表符、零宽字符；全角空格照收）。日期只收 yyyy-MM-dd。
• U8 API 自己提交，不在桥的事务里。U8 拒绝（InvokeApi 返回 false）是 409 u8_rejected，原文取第一行（去掉 .NET 异常类型名和后面的堆栈）；生产制造服务（U8MPool）没起是 503 u8_unavailable。
• 结果确认：新 MoId 取自 U8 返回的实体，桥在新连接上确认这张订单存在且制单人是本操作员。拿不到 MoId（调用中途异常、IPC 错误，或 U8 返回成功却没有 MoId）时，桥在新连接上取「调用前的最大 MoId 之后、本操作员建的」订单逐张比对：只有恰好一张有相同存货，且行数、每行行号、存货、数量（按存货数量小数位）、部门、类别、仓库、备注、开工和完工日期都相同、创建时间不早于调用前的数据库时间（带了 mo_code 再比单号），才按成功返回；有多张、没有或对不上都是 504 outcome_unknown（U8 返回了成功时消息是「U8 已返回成功但回读不到新生产订单，结果未知」），这时不要重投，先按列表核对。可以带 Idempotency-Key（§20）。

物料清单#

bom 走 U8 API 的 BomAdd（登录子系统 BO），为一个母件新建一个标准 BOM 版本（BomType=1），不收替代 BOM。字段名是下面这些（不分大小写），其余 400「不能设置字段 x」：

• 明细 1 到 200 行。子件的生效日期取版本生效日期，失效日期 2099-12-31。每行的其他标志按 U8 缺省送（变动用量、偏置期 0、计划比例 100、非产出品、计成本、非选配、互斥全部、产出类型 1、不带分段损耗、不关联成本在制），缺了 U8 保存时报 CheckStructureIntegrity。
• 新版本的状态按 U8 选项「BOM 缺省状态」（mom_parameter.BomDefaultStatus，一般是 1 未审核），审批流启用时 U8 自己标 IsWFControlled。审核、弃审走 §6，修改走 §8，删除走 §9。
• 功能权限要有物料清单卡片的「增加」（BO01001N），否则 403；母件存货要在操作员的数据权限内（403）。
• 成功另给：version、lines（子件行数）、components（每行 line_id、sort_seq、inv_code、base_qty_n、base_qty_d）；code 是母件存货编码。
• U8 API 自己提交，不在桥的事务里。U8 拒绝是 409 u8_rejected（原文第一行，去掉堆栈）；生产制造服务没起是 503 u8_unavailable。
• 结果确认：U8 不把新 BomId 写回实体，桥在新连接上按（母件、版本、主 BOM）找：U8 返回成功时认创建时间不早于调用前数据库时间的那一行；调用中途异常或 IPC 错误时还要制单人是本操作员、行号、子件和用量分子逐行相同。找到按成功返回；有这个版本却认不了是 504 outcome_unknown，一行都没有时 IPC 错误 503、其他 504。504 时不要重投，先按列表核对。可以带 Idempotency-Key（§20）。

应收应付单据的字段见 §12。

8. 修改 vouchers/update#

请求：type、id，head 与 lines 至少一项非空，两项都空 400「没有要修改的内容」；不在下表的类型 400「该单据类型不支持修改」。物料清单（bom）按 sort_seq 定位行，生产订单（production_order）只能 update 已有行，规则见下文对应小节。

lines 为 0 到 200 行，每行有 op：

其他 op 400「op 只能是 add、update 或 delete」；同一请求 line_id 重复 400「明细行重复」；line_id 不属于本单 400「明细行不存在」；删光现有行又不新增 400「不能删除全部明细」。库存单据（其他入库、其他出库、调拨、形态转换、调拨申请）换存货 400「不能修改存货编码，请删除该行后新增」。

只改未审核、未关闭、没有下游的单据，否则 409 state_mismatch；在审批中 409 workflow_enabled。各类型的拒绝条件与其删除相同（§9）。其他入/出库还要求来源是库存，来源是调拨时 409「调拨生成的单据不能修改」。

成功：{"ok":true,"type","id","code","state","lines"}，lines 是保存后的表体行数。U8 的销售、应收应付业务组件保存时不写修改人，桥补写修改人、修改日期和修改时间（行集里有这些列时）。提交后回读失败 504 outcome_unknown：修改已保存，不要重投。

自由修改的类型#

• 采购入库单（来源为库存）只改蓝字单：红字、期初、已记账、已被采购发票或采购结算引用 409；外币或汇率不是 1 的单 409「外币采购入库单不支持修改」。新增行按新增规则核对；改了数量、单价或税率的行由桥重算税价，只改备注、自定义项的行不动金额。不能清空批号；改已有行的批号、生产日期、失效日期按该存货的批次 / 保质期规则核对（400）。
• 货位：已有行改 cposition 400「暂不支持修改已有行的货位，请在 U8 客户端修改」（值与现值相同时放行），新增行可带货位。单据有货位记录时不能换仓库；有货位的行（InvPosition 有该行或行上 cPosition 非空）不能删，只能改 cbmemo 和表体自定义项，其余 409「该行有货位记录，桥暂只能改备注和自定义项，请在 U8 客户端修改」。

生单来的单据#

这些单据挂着来源行，修改只做缩减：

• 不能新增行，400「该单据类型修改不能新增行」（API 层即拒绝）；发货单可新增参照来源销售订单的行（§35「发货单修改新增行」）。可以删行，至少留一行。
• 数量只能减少：大于原数量 400「修改只能减少数量」，不大于 0 400「数量必须大于 0」。红字单据（退货单、采购退货单）按绝对值比较，请求写正数，桥写负数，同生单。
• 可写字段只有下表所列，加表头 cdefine1–cdefine16、表体 cdefine22–cdefine37；名单外 400「不能修改字段 x」，在名单里但不在 U8 行集 schema 里 400「未知字段 x」。存货、来源行关联、仓库（发货单、退货单除外）、单价、退货单的 bneedbill / invoiced 不能改。
• 文本字段送空串 "" 为清空；任何字段送 JSON null 被拒绝（API 层 422，直接调桥 400）。
• 改了数量的行由桥按该类型生单时的算法重算金额（销售按比例缩放后单行 BodyCheck，采购按 btaxcost，库存按单价 × 数量），单价不变。
• 桥在事务里先锁来源行读累计数，保存后按每行数量差核对来源累计数（未改的行应变 0），并核对本单行数和数量；不符回滚并 409 u8_rejected，审计 detail 记基准值和实际值。U8 在保存中已自行提交时核对失败为 504 outcome_unknown，需人工核对。

各类型另外的拒绝条件：

• 发货单：非蓝字、期初同审核一样 400（「仅支持蓝字发货单」「仅支持发货单类型 05」「不支持期初发货单」）；已关闭 409。退货单：id 须是红字发货单（bReturnFlag=1、cVouchType=05），否则 400「该单据不是退货单（红字发货单）」。两者已被销售出库或销售发票引用 409「单据已有下游单据」。
• 销售发票：只改蓝字（红字 400「仅支持蓝字销售发票」）、未复核、应收未审核的；复核后又弃复、已复核开票数量没有退回时 409（同删除）。有行没有发货单来源（iDLsID 为空），或有发货单的 SBVID 指回本发票（先开票），409「先开票或无发货单来源的发票暂不支持修改」。表头 iDisp 为 0 的发票 U8 视为先开票、原样修改会被拒（「先开票不可以参照发货单」），因此其余 iDisp 为 0 的发票修改时桥写 iDisp=1 并补表体 cbdlcode（桥生单时已写这两项，见 u8-notes.md）。
• 库存单据：已记账、红字、期初 409；有货位记录的只能改备注和自定义项（同上）。销售出库只改来源为发货单或库存的；材料出库、产成品入库对应的生产订单行须仍为审核状态。参照合并检验的产品检验单生成的产成品入库（任一行 imergecheckautoid 大于 0）409 state_mismatch「参照合并检验单生成的产成品入库单不能修改，请删除后重新生成」。
• 到货单、采购退货单：已报检或已入库 409。采购发票：已复核、已应付审核、已结算、已现付、期初、有应付明细、采购期间已结账 409。

物料清单#

bom（id 是 BomId）走 U8 API BomUpdate（登录子系统 BO）。只改未审核（Status=1）、未进审批流的标准 BOM：已审核 409 state_mismatch「已审核的物料清单不能修改」，停用 409，IsWFControlled=1 409 workflow_enabled（U8 API 本身不查状态，闸门由桥做）。

桥读出现有全部行和每行的标志，叠上本次修改，以差异更新（UpdateByDiff=true）送全部行：U8 按行号更新，未送的行号删除（不带差异更新时 U8 整表替换）。差异更新对行上附属内容的处理决定了哪些清单能改：

任何一行带前四类（读取里 extras 为 "1"）时 409 state_mismatch「第 n 行带替代料、定位符、分段损耗或自由项，请在 U8 客户端修改」，不论本次是否改那一行。

• 表头只收 version_desc、eff_date、parent_scrap（规则同新增）；改了 eff_date 且与该母件其他版本相同 409。子件生效日期等于旧版本日期或早于新日期的，跟到新日期。
• 行按 sort_seq 定位，不用 line_id。update 须带 sort_seq 并至少再改一个字段，可改 base_qty_n、base_qty_d、comp_scrap、wip_type、wh_code、remark、op_seq；带 inv_code 400「不能修改存货编码，请删除该行后新增」；wh_code、remark 不能改成空（400）。delete 只能有 op 和 sort_seq。add 的字段同新增的行，sort_seq 不能与现有行重复（400「sort_seq 已存在」），省略时取最大行号加 10。update / delete 的 sort_seq 重复 400「明细行重复」，不存在 400「明细行不存在」，删光 400「不能删除全部明细」。新增或改过的行按新增规则查存货和仓库。
• 功能权限：物料清单卡片「修改」（BO01001M）；母件存货须在数据权限内（403）。
• 调用后在新连接上回读，与目标状态逐项比对：表头版本说明、生效日期、母件损耗率，行数，每行行号、工序行号、子件、用量分子分母、子件损耗率、供应类型、仓库、备注、生效和失效日期，以及桥送的全部标志（变动用量、偏置期、计划比例、产出品、计成本、选配、互斥、产出类型、成本在制关联）。全部相同才算成功。不一致时：调用异常 504 outcome_unknown；IPC 错误（生产制造服务未启动）503 u8_unavailable，回读已是目标状态时按成功返回；U8 返回成功却不一致 409。
• 成功响应同新增（version、lines、components），API 模型为 CoUpdateOut。

生产订单#

production_order（id 是 MoId）走 U8 API：MOrderLoad 取出整张订单（表头、行、全部子件），在加载出的实体上修改，再以新的 U8EnvContext / U8ApiComBroker 调用 MOrderUpdate 交回（登录子系统 MO，U8 自行提交，不在桥的事务里）。MOrderUpdate 按行号（DSortSeq）对行，并删除每一行的全部子件、按送去的子件重插（AllocateId 全部换新）：不送子件即清空用料，所以桥总是重送加载出的全部子件；扩展实体带不回的子件列由桥在 U8 提交后写回（见下）。

闸门

• 任何一行已关闭（Status=4）409「生产订单已关闭，请先打开再修改」（vouchers/close 的 action=open）；其他非 1 / 2 / 3 状态 409；集合生产订单（CollectiveFlag 非 0）409；IsWFControlled=1 409 workflow_enabled；已报检（DeclaredQty 大于 0）、已被产成品入库引用 409 state_mismatch。
• 已审核（Status=3）的订单按 U8 客户端「变更」直接修改，不弃审，改后仍为已审核；响应 state.verified、verifier、verified_at 按回读填。
• 已领料（子件 IssQty 大于 0、有材料出库行按 iMPoIds 指向子件）：改了数量的行，子件改后需求少于已领数量 409「第 n 行子件 X 已领 a，改后需求 b 少于已领数量，不能修改」（同 U8 客户端）；出库行存货与子件不同（替代料出库）409。
• 子件主键会换新，所以有任何行按 AllocateId 指向本单子件时 409「生产订单子件已被其他单据或计划引用，不能修改（表名）」：替代料 mom_moallocatesub、分段损耗、缺料明细、子件历史、领料申请、调拨申请、配比出库、材料出库历史表、报废、MRP / 计划（mps_*）、下级订单（PAllocateId）等（账套里没有的表跳过；材料出库单 rdrecords11 不在此列，由桥改写，见下）。同一行上行号、存货都相同的两个子件也 409（写回时无法对准）。
• 子件有 U8 修改接口重建时不保留、桥也不写回的非缺省设置时 409「子件有 U8 修改接口不能保留的设置（列名），不能修改」：母件损耗率、偏置期、质检、成本在制关联、需求跟踪（SoType / SoCode / SoSeq / DemandCode）、工厂、各种累计量和标志（调拨、领料申请、拣货、补料、报检、原始数量）、成本项、MoallocateSubId，以及结束需求日期不等于开始需求日期。
• 功能权限：生产订单输入卡片「修改」（MO02001M）；每行的存货、部门、仓库须在数据权限内（403）。

请求

• 表头只收 remark（最长 255）：MOrderUpdate 不读表头其他字段，表头 remark 写到本次没有单独给 remark 的每一行。
• lines 0 到 50 行，op 只能是 update（add、delete 400「生产订单修改暂不能新增行 / 删除行」），按 line_id（MoDId）定位，不是本单的行 400「明细行不存在」。可改：qty（大于 0，小数位不超过账套存货数量小数位）、due_date（yyyy-MM-dd，不早于开工日期；有产出品子件的行 409，因 U8 重建子件时不重算产出品需求日期）、remark（最长 255）、文本型表体自定义项 define22–define25（最长 60）和 define28–define33（最长 120）。start_date 一律 400「暂不支持修改开工日期（U8 重建子件时不重算需求日期）」。inv_code 只能送当前值，换存货 400（U8 同样拒绝）。remark 和自定义项不能送空串（U8 不写空值，400）；只带 null 的行、只有 null 的表头按无改动 400。
• 请求值与现值完全相同时不调用 U8，直接返回（changed 为 0）。

子件数量重算（改了数量的行，按 U8 的子件用量算法）

• 系数 1 + 子件损耗率/100；变动用量（FVFlag=1）且非返工订单（MoClass=2）时再除以 1 − 母件损耗率/100。变动用量 = 新行数量 × 基本用量分子 / 分母 × 系数；固定用量不随行数量变。按存货数量小数位 iStrsQuanDecDgt 四舍五入。手工调过数量的子件同样重算；没改数量的行子件原样重送。
• 有换算率的子件用 AuxBaseQtyN 计算，件数 = 未舍入数量 / 换算率（按件数小数位 iNumDecDgt）。BaseQtyN 须等于 AuxBaseQtyN × 换算率，或等于其按存货数量小数位四舍五入的值（U8 展开子件时即如此存储，例如辅用量 1、换算率 2.345678，主用量存 2.35）。只等于舍入值时，U8 按存货的「BOM 展开单位」走主计量或辅计量算法，桥读不到该设置，两条都算，新数量和件数都相同才修改，否则 409「按主计量和辅计量算出的新数量不同（取决于存货的 BOM 展开单位）」（上例行数量改为 3 时主计量得 7.05、辅计量得 7.04）。两者都不等 409「辅计量用量与主用量不一致」；有换算率却没有 AuxBaseQtyN、母件损耗率不小于 100 的子件也 409。行上有辅计量的按换算率重算行件数。

调用与核对

• 调用前桥在请求连接上记下全部行和子件，把每个子件要写回的快照值和旧 AllocateId 写进审计事件 mo_update_snapshot。U8 加载出的行数、行号、子件数、子件（行号、存货、用量、仓库、自由项）与库里不符时不调用 MOrderUpdate，409「…，未修改」。用量、数量和换算率按快照原值写回实体（Load 时按精度舍入过）。
• 写回子件列：U8 重插子件时丢失 OpComponentId、VirOpComponentIds、cSubSysBarCode、SoDId、UpperMoQty（变为 0 / NULL），桥在自己的事务里写回快照原值（UpperMoQty 是展开时的母件数量，U8 客户端改数量时也不动它）：UPDLOCK 重读本单子件，确认子件确已重插（现有 AllocateId 都不在快照里），按（行、行号、存货）为每个快照子件对上恰好一行，要写的列须仍是 U8 重建后的缺省或已等于快照值（否则可能有人在 U8 客户端改过，不覆盖）；任何失败回滚并 504（U8 的修改已提交，按审计事件手工恢复）。
• 改写材料出库关联：MOrderUpdate 不改出库行 rdrecords11.iMPoIds（仍指向旧 AllocateId，已领量随重插带到同一子件的新行），桥按 U8 客户端变更后的结果补齐。调用前把全部引用行写进审计事件 mo_update_refs（表、AutoID、出库单 ID、旧 AllocateId、子件的行 / 行号 / 存货、数量）；U8 提交后在自己的事务里 UPDLOCK 读现有子件，按（行、行号、存货）把旧 AllocateId 对到唯一一行新子件，按 AutoID 改写 iMPoIds，再核对每一行都指向同一存货的新子件、旧 id 不再被引用、新子件已领量等于旧值且不超过需求，全部通过才提交，旧→新对照写进审计事件 mo_update_remap。对不上或核对失败回滚并 504 outcome_unknown（U8 的修改已提交），消息带修复办法：按两条审计事件修正出库行的子件关联，或到 U8 客户端核对。
• 完整核对（新连接）：行数不变，每行存货不变、数量 / 件数 / 日期 / 备注 / 自定义项等于请求，每行子件数不变，每个子件数量、件数、UpperMoQty 等于目标，其余受保护的列和替代料行数不变。全部相符才算成功，否则 504 outcome_unknown，消息列出前几项不符（审计 detail 记全部），请到 U8 客户端核对用料，不要重投。
• MOrderUpdate 报错或调用异常时同样回读：与修改前完全相同时，IPC 错误 503 u8_unavailable、其余 409 u8_rejected（U8 原文第一行）；已是请求状态按成功；其余 504。
• 成功响应同新增：lines、allocates（全部行的子件行数）、details（每行 line_id、sort_seq、inv_code、qty、status、allocates），另有 changed（本次改动的行数）；API 模型为 CoUpdateOut。子件 AllocateId 会变。
• 已在测试账套实测：固定用量（FVFlag=2）、带子件损耗率的子件改数量后，U8 写入的数量等于上述算法；已审核订单改后仍为已审核；领料后修改时已领量带到新子件。尚未验证：Load 的数量精度是否就是 iStrsQuanDecDgt；主用量与辅用量 × 换算率严格相等时辅计量子件改数量的写入；小数位多于件数精度的子件换算率写回。

质量单据#

可修改来料检验单（QM03）、产品检验单（QM04）、其他检验单（QM15）、其他报检单（QM11）。只收 head，送了非空 lines 400「质量单据修改只收表头 head（检验项目放在 head.items），不收 lines」；字段名不分大小写，名单外 400「不能设置字段 x」。

• 检验数量 fquantity、存货、仓库、检验方案、抽检量、报检单关联不能改（400）；其他报检单的表体数量、仓库不开放修改。
• 数量：送了三个数量中任一个，就按单据已有检验数量 FQUANTITY 核对：未送的让步、不良取 0，未送的合格 = 检验数量 − 让步 − 不良，三者之和须等于检验数量（400）。改了数量又未送结论时，结论按不良数量取「合格」/「不合格」。有辅计量单位的单据按单据换算率同时改件数。
• 让步接收：creasoncode 是「让步接收原因」。改了数量且让步数量大于 0 时须有原因（请求带或单据已有，400）；只有不良数量不要求原因。其他检验单修改后没有让步数量时不能填原因，400（U8 要到审核时才报「没有'让步接收数量'，'让步接收原因'不能填写！」）。来料 / 产品检验单修改后让步数量大于 0 时须有核准人（请求带 cyieldercode 或单据已有），否则 400（U8 模板必输）；让步数量改回 0 时桥不清核准人。单据已有的 chdefine11–chdefine16 原样写回（chdefine15 是处置说明，不是核准人）。
• items：1 到 50 项 {cchkitemcode, cchkguidecode, ccheckvalue?, ctargetqjug?}，按检验项目和指标对到单据已有的检验项目行，覆盖检验值和单项判定，不增删行；对不上 400「单据中没有检验项目 x 指标 y」。单项判定变化时该行抽检量挪到指标合格数或不合格数（同生单）。
• 送了的 ccheckpersoncode、cchkconclusion、creasoncode、cinspectdepcode 不能是空串（400）；检验员、报检部门不存在 400。
• 状态：只改未提交审批、未审核、没有下游的单据。检验单受审批流控制且已提交或已审核（或 iVerifyStateNew 不为 0）409 workflow_enabled，先在 workflow/* 撤回或弃审；已审核 409 state_mismatch（其他检验单、其他报检单先用 vouchers/verify 弃审，桥不自动弃审）；已入库、已生成不良品处理单 409；其他报检单已有其他检验单 409。U8 本身不拦已审核的其他报检单，这些闸门由桥做。
• 功能权限（修改按钮）：来料检验单 QM02010203、产品检验单 QM02020203、其他检验单 QM02060203、其他报检单 QM02060103（与新增同一 id）；数据权限同删除。
• 检验单经 VoucherOperate(…, "update", …)，其他检验单、其他报检单经 VO 的 UpdateVoucher，均由 U8 自行提交；dry_run 只做校验（模式 validate）。调用后在新连接上回读：ufts 已变、请求的每个字段都读到、检验单对应的报检单行累计检验数量和检验标记未变，才算成功。ufts 未变时 409 u8_rejected（U8 原文）；ufts 已变但有不符，或 U8 报错，504 outcome_unknown（已修改，不要重投，先用 idempotency/get 或回读核对）。检验单、其他检验单由 U8 写修改人，其他报检单不写。
• 产品报检单（qm_product_inspect）、来料报检单不能修改（400「该单据类型不支持修改」）：U8 组件对这两类的修改接口在测试账套上无法写入（见 u8-notes.md）。
• 成功响应同其他修改，lines 是检验项目（检验单）或表体（其他报检单）行数。

应收应付#

收款单、付款单、应收单、应付单只改未审核的手工单据，拒绝条件同删除（§12：已制单、已核销、有往来明细、票据或网银生成、期初、单据月份已结账）。

• 可写字段是新增字段表（§12）去掉往来单位 cdwcode、币种 cexch_name、汇率 iexchrate。可新增、修改、删除行，金额可增可减；桥重算表头合计和未核销金额（等于金额），税额拆分同新增。只改备注、部门等时不动该行税额拆分，送了金额或 itaxrate 的行才重算。
• cdigest、cmemo、cdefine* 送空串 "" 为清空，送 JSON null 被拒绝（API 层 422，直接调桥 400）；金额、日期、编码的空值忽略。
• 收款单、付款单改到别的月份时，桥同时改表头会计期间 iPeriod 并在提交前核对。
• UFAPBO 以 SaveVouch(…, IsAdd=false) 保存，在事务里；提交前核对仍没有往来明细、表头金额等于表体合计。
• 成功响应同新增（state 带 gl_voucher、settled、amount、unsettled_amount）。

9. 删除 vouchers/delete#

请求：type、id。成功 {"ok":true,"type","id","deleted"}，deleted 为 true 表示表头已不存在。报检单、检验单、物料清单另带 code（见下）。

允许：sale_order、purchase_order、purchase_requisition、other_in、other_out、transfer、dispatch、sale_return、arrival、sale_out、purchase_in、sale_invoice、purchase_invoice、material_out、product_in、ar_receipt、ap_payment、ar_bill、ap_bill、purchase_return、production_order、bom、qm_incoming_inspect、qm_product_inspect、qm_incoming_check、qm_product_check、qm_incoming_reject、qm_product_reject、qm_other_inspect、qm_other_check、shape_change、transfer_request、stock_check、stock_opening、purchase_settle，以及 §35 所列类型。其他类型 400「该单据类型不支持删除」。

只删未审核的单据，并挡住下游（409 state_mismatch）。

货位：库存单据有货位记录（InvPosition 有该单据的行）时，桥在删除事务里先让 U8 清掉该单据的货位记录（ClearPosition）再删除，U8 回退货位存量（InvPositionSum）；U8 拒绝清货位 409 u8_rejected（原文带回）；删除后货位记录或表头仍在则回滚并 409 u8_rejected。采购入库、其他入库、其他出库、销售出库、材料出库、产成品入库均适用。

销售

• 发货单：已被销售出库或销售发票引用的不删；非蓝字、期初同审核一样拒绝。
• 退货单（sale_return）：只删红字发货单，未审核、不在审批中、未被销售出库或销售发票引用的；删除前每行标 editprop=D。桥在同一事务里核对 U8 退回了回写：原发货行（按 iCorID）iRetQuantity 与 fretqtywkp / fretqtyykp（按表头 bneedbill）减、订单行 fretquantity 减、iFHQuantity 加，不符回滚并 409 u8_rejected。
• 销售出库：只删来源为发货单或库存、且没有发票行指向它的。
• 销售发票：只删未复核且应收未审核的。复核后又弃复、发货行已复核开票数量没有退回时拒绝，请到 U8 客户端处理（见 limitations.md）。
• 红字销售发票：只删参照退货单生成的（判断同 §6，其余红票 400）。复核后又弃复、退货行已复核开票数量（fVeriBillQty，负数，按绝对值比）没有退回时 409。删除前每行标 editprop=D，桥在同一事务里核对退货行 iSettleQuantity 与订单行 iKPQuantity 各加回发票数量，不符回滚并 409 u8_rejected。
• 供应商退款、客户退款、退货申请单和红冲蓝字发票的删除见 §35。

采购

• 请购单：只删未审核、未关闭、普通采购、未被采购订单参照、没有累计订货或询价数量的。
• 到货单：只删尚未报检或入库的。
• 采购退货单：只删未审核、尚未报检或入库的；U8 删除时回退来源行累计退货数和订单行累计退货、累计到货，桥在同一事务里核对，未回退则回滚并 409 u8_rejected。
• 采购入库：只删来源为采购订单、来料检验单、采购到货单（参照到货单生成的蓝字、参照采购退货单生成的红字）或库存，且未被采购发票或采购结算引用的；其他来源 409「只能删除来源为采购订单、来料检验单、采购到货单或库存的单据」。任何来源已记账（表体 cbaccounter）409「单据已记账，不能删除」；期初（bpufirst、bIsSTQc、biafirst 任一为真）409「期初采购入库单不能删除」；发票、结算引用在事务里再查一次。来源为来料检验单的，桥在同一事务里核对检验单累计入库数已退回；来源为采购到货单的，核对到货 / 退货行 fValidInQuan 已退回（红字加回、蓝字减去本单数量），否则回滚并 409 u8_rejected。
• 采购发票：只删未审核、未应付审核、未结算、未现付、非期初、没有应付明细、采购期间未结账的。红字发票（bNegative=1）同样可删，U8 退回入库行的负累计开票数，桥核对。
• 采购结算单（purchase_settle，id 是 PSVID）：自动结算和手工结算生成的结算单都适用。VoucherCO_PU.Init(5) 载入后 Delete，在桥的事务里；先查功能权限，再查状态。只删普通采购、未制凭证（bMakePz）、未被锁定（iNetLock）、每行存货核算都未处理结算成本（bAccount=1 409「存货核算已记账，先取消记账」）、关联发票都未应付审核（409「发票已应付审核，请先取消应付审核」）、结算日期所在期间采购未结账的，最多 400 行。U8 删除后清空关联发票表头、表体的结算日期 dSDate；桥在同一事务里核对结算单表头、表体已不在、发票 dSDate 已清空，提交前再查一次关联发票仍未应付审核（期间被他人审核也 409），否则回滚并 409。登录日期所在月以前的月份采购未结账时 U8 拒绝（409 原文），可带 date 指定登录日期。功能权限「删除结算单」PU040315，数据权限同生单。

库存

• 其他入/出库：只删来源为库存的。
• 形态转换单、盘点单：只删未审核的（形态转换审核后生成的其他出入库单随弃审删除；在 U8 客户端审核的盘点单须先在客户端弃审）。调拨申请单另须未关闭、未被调拨单参照、累计调拨数量为 0。
• 材料出库、产成品入库：只删来源为生产订单、产品检验单或产品不良品处理单，且对应订单行仍为审核状态的。U8 回退已领量、合格入库量和检验单累计入库量；来源为不良品处理单的，桥在同一事务里核对合格入库量和已入库标记已回退；参照合并检验的检验单生成的，核对合并来源累计入库数、检验单累计入库数、订单行合格入库量都减回本单数量；不符回滚并 409 u8_rejected。产成品入库使合格入库量达到订单数量时 U8 自动关闭订单行，此时删除 409「生产订单行已关闭（入库完成时 U8 自动关闭），请先在 U8 打开生产订单行再删除」。

应收应付：收付款单、应收应付单见 §12。

质量单据

• 来料报检单、产品报检单：U8 质量管理组件 VoucherOperate 的 delete，传入从视图读出的整张单据（空白 DOM 会被 U8 拒绝）。任一行已检验（FSUMCHECKQTY > 0）或有检验单引用 409「已有检验单，不能删除」。已审核的（报检单保存时通常自动审核）先弃审再删，须有弃审权限，否则 409；响应另带 unverified: true。弃审由 U8 自行提交，此后删除只要未成功（U8 拒绝、回读不符、任何异常）都返回 504 outcome_unknown，不是 409：单据已由已审核变为未审核。桥不会重新审核（U8 不能经接口审核报检单），消息末尾带「（报检单已弃审且未删除；接口无法重新审核，请在 U8 客户端处理或再次调用删除）」。U8 回退来源累计报检数：到货行 fInspectQuantity 回 0、bInspect 回 0，生产订单行 DeclaredQty 减本次数量。
• 来料检验单、产品检验单：只删未审核（CVERIFIER 空）、未提交审批（iVerifyStateNew = 0）、没有下游的：已被采购入库（rdrecords01.iCheckIdBaks）或产成品入库（rdrecords10.iCheckIdBaks）引用、已有不良品处理单、累计入库数大于 0，都是 409。U8 回退报检单行 FSUMCHECKQTY 和 BFLAG。
• 来料不良品处理单、产品不良品处理单：GetTheVoucher 载入后 DelVoucher。只删未审核、未提交审批（iVerifyStateNew = 0）、没有下游的：表体行已被出入库单（rdrecords01/08/09/10/11/32/34.iRejectIds）、报废单（ScrapVouchs.iRejectIds）、到货单（PU_ArrivalVouchs.irejectautoid）、报检单行（QMINSPECTVOUCHERS.REJECTAUTOID）引用，有报检单（QMINSPECTVOUCHER.REJECTID）指向它，领料申请单行（MaterialAppVouchs.crejectcode）写着它的单号，409「已被下游单据引用，不能删除」；表体已处理（BFLAG=1）或已有返工数量，409「不良品已处理（已入库或已返工），不能删除」。U8 删除后回退检验单 BREJFLAG，此后可重新参照该检验单生单。桥在新连接上核对表头、表体已不在且 BREJFLAG 已回 0；表头已删但表体或标记未回退 504 outcome_unknown（需在 U8 中核对）。功能权限：来料 QM02010304、产品 QM02020304。
• 其他报检单、其他检验单：GetTheVoucher 载入后 DelVoucher（组件见 §7「其他报检单」、§11「其他检验单生单」）。其他检验单只删未审核、未提交审批、没有下游的（弃审判断同 §6），U8 删除后回退其他报检单行 BFLAG；桥在新连接上核对表头、检验项目已不在且 BFLAG 已回退，否则 504 outcome_unknown。其他报检单已有其他检验单（INSPECTID 指向本单或行 BFLAG=1）409「已有其他检验单，不能删除」；已审核的（保存时自动审核）先 UnAuditVoucher 再删，须有弃审权限（QM02060107，否则 409），响应 unverified 为 true；弃审后删除未成功一律 504 并注明已弃审（同来料报检单）。功能权限：其他报检单 QM02060104、其他检验单 QM02060204。
• 报检单、检验单、不良品处理单的删除及删除前的弃审由 U8 自行提交（不在桥的事务里）：桥先在单据锁下查完条件，调用后在新连接上确认表头已不在；调用异常且回读不清 504 outcome_unknown，先 vouchers/load 核对再决定是否重发。报检单、检验单的删除响应另带 code（被删单号）。

生产制造

• 生产订单（production_order，id 是 MoId）：U8 API MOrderDelete（登录子系统 MO，U8 自行提交）。集合生产订单（任一行 CollectiveFlag 非 0）409 state_mismatch「集合生产订单请在 U8 客户端删除」；任一行不是未审核（Status 1 或 2）409「已审核或关闭的生产订单不能删除」；审批流控制且已提交（IsWFControlled=1、iVerifyState=1）409 workflow_enabled；已被材料出库单（rdrecords11.iMPoIds 指向子件）或产成品入库单（rdrecords10.iMPoIds 指向订单行）引用 409。功能权限「删除」（卡片 MO02001D 或生产订单列表 MO03001D），每行在数据权限内。U8 删除表头、明细、日程和子件；桥在新连接上确认表头已不在。U8 拒绝 409 u8_rejected（原文第一行，去掉堆栈），生产制造服务未启动 503，调用异常且表头仍在 504 outcome_unknown。
• 物料清单（bom，id 是 BomId）：U8 API BomDelete（参数同审核，登录子系统 BO）。已审核或停用 409「已审核的物料清单不能删除」；IsWFControlled=1 409 workflow_enabled；被单据引用时 409「X已引用该物料清单，不能删除」，X 依次查：生产订单（mom_orderdetail.BomId）、委外订单（OM_MODetails.BomId）、组装 / 拆卸 / 形态转换单（AssemVouch.BomId）、配比出库单（MatchVouch.BomId 或表体 MatchVouchs.Bomid）、调拨单（TransVouch.BomId）。U8 删除本身不查这些引用，由桥挡住。功能权限「删除」（BO01001D），母件存货在数据权限内。U8 删除版本、母件和子件行；是该母件最后一个标准 BOM 且还有替代 BOM 或共享 BOM 时 U8 拒绝（409 u8_rejected）。桥在新连接上确认已不在；未删掉时调用异常 504、IPC 错误 503、U8 返回成功却仍在 409。响应另带 code（母件）和 version。

10. 关闭和打开 vouchers/close#

请求：type、id、action（close 或 open，否则 400「action 只能是 close 或 open」），可选 line_ids。允许 sale_order、purchase_order、purchase_requisition、production_order、arrival，其他类型 400「该单据类型不支持关闭」。

line_ids 省略表示整张单据；带上则为 1 到 200 个不重复的正整数（§4 的行主键）。写成 JSON null 是 400，不视为整单。

关闭要求单据已审核，未审核 409「单据未审核」（U8 组件本身会关闭未审核的销售订单，桥在调用前拒绝）。整单已关闭再关 409「单据已关闭」，未关闭就打开 409「单据未关闭」，按行同理。采购订单没有可处理的行 409「没有可处理的行」。

成功：{"ok":true,"type","id","action","closed","closed_by","closed_at","lines":[{"line_id","closed"}]}，lines 是全部表体行。采购订单只关部分行时表头关闭人仍为空，全部行关闭后 U8 才写表头。

请购单（purchase_requisition）：只做整单（VoucherCO_PU 的 CloseApp / OpenApp），带 line_ids 400「请购单只支持整单关闭或打开」。关闭要求已审核，表头已关闭再关 409；打开要求表头或任一行已关闭，否则 409「单据未关闭」，打开后在新连接上核对表头和各行关闭人都已清空。响应 lines 为空数组。

到货单（arrival）：整单或按行，id 是到货单 ID，line_ids 是 Autoid。走 VoucherCO_PU（Init vt 2）的 CloseArrItems / OpenArrItems，与采购订单一样在请求连接的事务里，可预演（dry_run，回滚模式）。

• 只收蓝字到货单（iBillType=0），采购退货单 400「仅支持蓝字到货单」；type 为 purchase_return 400「该单据类型不支持关闭」。
• 关闭要求已审核（cverifier 非空），否则 409「单据未审核」。表头 ccloser 非空再关 409「单据已关闭」；表头和各行（cbcloser）都没有关闭人时打开 409「单据未关闭」。按行规则同采购订单。
• 提交前在同一事务里核对：所处理的行（整单为全部行）关闭后都有行关闭人、打开后都没有，否则回滚 409「U8 没有处理任何行」；按行时未选的行关闭状态须与调用前相同（行数也不能变），否则回滚 409「U8 同时改动了未选的明细行，已撤销」。U8 拒绝 409 u8_rejected，原文带回。
• 响应同采购订单：closed、closed_by 取表头 ccloser（操作员姓名），closed_at 取表头 dclosedate（只有日期），lines 是全部表体行（line_id 为 Autoid）。提交后回读失败 504 outcome_unknown，不要重发。
• 关闭只表示不再参照生单（采购入库、来料报检参照时拒绝已关闭的行），不要求已全部入库。

生产订单（production_order）：按行关闭和打开，id 是 MoId，line_ids 是 MoDId。U8 没有关闭 / 打开的 API，桥按 U8 界面的做法在请求连接的事务里调用 Usp_MO_Close / Usp_MO_UnClose（见 u8-notes.md）。

• 不带 line_ids：关闭取全部已审核未关闭的行（Status=3），打开取全部已关闭的行（Status=4）。一行都没有时，关闭 409「单据已关闭」（全部已关闭）或「单据未审核」，打开 409「单据未关闭」。
• 带 line_ids：行不属于本单 400「明细行不存在」，重复 400「明细行重复」；关闭时该行已关闭 409「单据已关闭」、未审核 409「单据未审核」，打开时该行未关闭 409「单据未关闭」。
• 选中的行 IsWFControlled=1：409 workflow_enabled「单据已启用审批流，本期不支持」。
• 登录日期所在月已做成本计算：409 u8_rejected「本月成本已计算，不能关闭」（打开为「不能打开」）。
• 关闭时该行还有在制品（车间管理工序结存不为 0）：409 u8_rejected「生产订单还有在制，不能关闭」。U8 界面缺省允许关闭在制订单，桥传 @v_closeflag=0，不关闭在制订单。
• 功能权限：关闭 MO03001CLS、打开 MO03001UNC（生产订单列表的「关闭」「还原」按钮，输入卡片上没有），缺少时 403「没有生产订单关闭权限」「没有生产订单打开权限」。选中各行的存货、生产部门、仓库须在数据权限内（与读取同一组对象），否则 403「没有该单据的数据权限」。关闭时存储过程报无权限（Errno=0）也是 403；打开时 Errno=0 也可能是恢复预留后预留量超过现存量，报 409 u8_rejected「预留量超过现存量或没有权限，不能打开」。
• 任一行处理失败整笔回滚。提交前在同一事务里核对选中的行到达目标状态、其他行不变。
• 响应在上述字段外另有 code（生产订单号）、changed（本次处理行数）、state（verified、closed、verifier、verified_at，同读取）。closed 表示全部行已关闭；closed_by、closed_at（日期）取第一条已关闭的行，是 U8 记在行上的操作员编码，没有已关闭的行时为空。打开后 CloseUser 清空。

锁定和解锁 vouchers/lock#

请求：type、id、action（lock 或 unlock，否则 400「action 只能是 lock 或 unlock」）。只允许 sale_order（id 是 SO_SOMain.ID），整单锁定，不按行。purchase_order 400 bad_request「采购订单锁定暂不支持（U8 采购组件 DoLock 实测一律拒绝）」（API 参数校验即拒绝，不调用 U8；U8 采购组件的 DoLock 一律回「本张已经被修改,不能锁定.」，见 limitations.md）；其他类型 400「该单据类型不支持锁定」。

锁定人写在表头 cLocker，值是操作员姓名（不是编码）；读取的表头里为 clocker，列表的附加列为 locker（§16）。

闸门（调用 U8 之前，按顺序）：

• 单据不存在：404。
• 功能权限：销售订单锁定 SA03010108、解锁 SA03010109（销售订单卡片「锁定」「解锁」按钮），缺少时 403「没有销售订单锁定权限」等。表头客户、部门、业务员、销售类型须在数据权限内，否则 403「没有该单据的数据权限」。
• 已审核的销售订单不能锁定：409 state_mismatch「已审核的销售订单不能锁定」（U8 原文「销售订单已经审核!」）。
• 本人已锁定再锁定：不调用 U8，200，响应另带 already: true（锁定 504 后可直接重试）。他人已锁定：409 state_mismatch「单据已被 X 锁定」。未锁定就解锁：409「单据未锁定」。
• 只有锁定人本人能解锁，他人解锁 409「单据由 X 锁定」。姓名按 U8 写入 cLocker 的方式比较：两边去空格，操作员姓名截到列宽 20 个字符。

走 VoucherCO_Sa.LockVouch，在桥的事务里；提交前在同一连接上核对 cLocker 已到目标状态，否则 409 u8_rejected「U8 没有锁定单据」「U8 没有解锁单据」；U8 拒绝 409 u8_rejected，原文带回。提交后在新连接上回读，失败或状态不符 504 outcome_unknown（先 vouchers/load 核对再决定是否重试）。

成功：{"ok":true,"type","id","action","locked","locker"}（本人已锁定的重试另带 "already":true），locked 是回读的 cLocker 是否非空，locker 是锁定人姓名，解锁后为空串。

销售订单、采购订单被其他操作员锁定时（采购订单只能在 U8 客户端加锁；姓名比较同上），该单据的修改（vouchers/update）、删除（vouchers/delete）、审核和弃审（vouchers/verify、sale-orders/verify）返回 409 state_mismatch「单据已被 X 锁定」，与 U8 界面一致；锁定人本人不受影响。关闭、打开和参照生单不查锁定。

11. 参照生单 vouchers/generate#

请求：type 是要生成的单据，id 是来源单据主键，可选 source_type、head、lines。来源须已审核、未关闭。新单据为未审核（销售发票为未复核）。

source_type 省略取该目标的缺省来源；不在名单里的来源 400「该单据类型不能参照此来源类型生单」；类型不能生单 400「该单据类型不支持生单」。

每行必填 source_line_id（正整数）和 quantity（大于 0，不超过 1000000000000）。来源行重复 400「来源明细重复」，例外：销售出库同一发货行可按批号 / 货位列多次，（行、批号、货位）都相同才算重复，400「明细行重复」，且在桥读取发货单之后才判（发货单不存在、未审核先回 404 / 409）；不良品处理单的来源行就是检验单本身，每种处置一行，source_line_id 都等于检验单 ID。数量超过剩余 409「超过可生单数量」。

成功：{"ok":true,"type","id","code","source_type","source_id","state","lines"}，source_type 是实际来源，lines 是新单据的表体行数。检验单、不良品处理单另有 wf（其他检验单没有审批流，不带）。

采购发票和到货单保存后，桥在同一事务里核对 U8 已把本次数量加到来源累计数上，否则回滚并 409 u8_rejected。若 U8 在保存中已自行提交（本连接 @@TRANCOUNT 为 0），核对不过时无法回滚，返回 500 internal「U8 已自行提交，无法核对回写」，单据已落库，需人工核对。

通用：收发类别、采购类型、货位#

• 收发类别：采购入库（参照采购订单、来料检验单、采购退货单）不给 crdcode 时同 U8，取来源单据采购类型（cPTCode，参照检验单、退货单时取到货单 / 退货单上的）的 PurchaseType.cRdCode；采购类型没有设收发类别时取默认采购类型（PurchaseType.bDefault = 1）的；仍没有则 400「必须指定收发类别」（field 为 head.crdcode，hint「采购类型没有设置收发类别，请在请求里给 crdcode」）。材料出库、产成品入库（三种来源）U8 没有缺省，须给 crdcode（出库用出库类、入库用入库类的末级收发类别），缺少 400「必须指定收发类别」（field 为 head.crdcode），不存在、非末级或方向不对 400「收发类别无效」。桥不写死任何收发类别编码。
• 采购类型、币种：到货单、采购退货单、采购发票生单时来源单据上没有采购类型的，取默认采购类型（PurchaseType.bDefault = 1），也没有则不写、由 U8 判断；来源上没有币种时取本位币（foreigncurrency.iotherused = -1）。
• 货位（材料出库、产成品入库三种来源、采购入库参照采购订单 / 来料检验单 / 采购退货单）：行上可带 cposition，规则同无来源采购入库。仓库启用货位管理（Warehouse.bWhPos）时每行须填该仓库（Position.cWhCode）的末级货位，否则 400「仓库有货位管理，必须指定货位 cposition」；未启用的仓库填了 400「仓库未启用货位管理，不能填货位 cposition」；field 为 lines.<i>.cposition。采购入库表头仓库不存在 400「仓库不存在：<编码>」，field 为 head.cwhcode。U8 本身不拦（货位仓的入库行不带货位也能保存，cPosition 为空、不写 InvPosition），所以桥在调用 U8 之前一律核对。桥只写表体 cPosition，货位台账 InvPosition 由 U8 保存时写；删除时先清货位再删（§9）。红字入库（参照采购退货单）从货位出库，同样须调用方指定货位，桥不按原蓝字入库行带出。

销售#

• 发货单：仓库必填（行上的 cwhcode，否则表头，否则来源行），都没有 400「必须指定仓库」。
• 销售发票：同一张发票的行须来自同一客户；来源发货单已关闭或是期初时拒绝。
• 红字销售发票（source_type: "sale_return"）：退货单须是红字发货单（否则 400「该单据不是退货单（红字发货单）」）、非期初（400「不支持期初退货单」）、已审核、未关闭，且是已开票退货（bneedbill=1，否则 409「退货单是未开票退货（bneedbill=0），不开红字发票」：未开票退货冲减的是原发货行的未开票数量，不需要红票）；行未关闭，没有可开票数量 409「退货单没有可开票数量」。销售组件用红字 VT 1（26）/ 3（27），卡片同蓝字（07 / 13）。桥先试 GetNegaVouchData，U8 生成的表体不含全部请求行时改按参照视图（Sales_FHD_T / Sales_FHD_W）组装；表头 bReturnFlag=1、iDisp=1、sbvid=""，行 iDLsID 是退货行、cbdlcode 是退货单号，数量写负的本次数量，金额按比例后由 U8 按数量重算。可开票数量在事务里加 UPDLOCK、HOLDLOCK 重读；保存后在同一事务里核对：新发票行数、全为负数量且合计等于请求，退货行 iSettleQuantity 减了本次数量（更负），挂订单的订单行 iKPQuantity 净减本次数量；不符回滚并 409 u8_rejected。红字发票不能修改，可复核、弃复、删除（§6、§9）。
• 退货单（红字发货单）：来源须是蓝字发货单（bReturnFlag=0、cVouchType=05，否则 400「仅支持参照蓝字发货单」）、非期初（400「不支持期初发货单」）、已审核、未关闭，行未关闭。quantity 填正数。一张退货单要么是未开票退货（表头 bneedbill=0），要么是已开票退货（bneedbill=1）：head.invoiced 为 false 时每行不超过未开票可退、为 true 时不超过已开票可退（否则 409「超过未开票可退数量」/「超过已开票可退数量」）；省略时全部行都在未开票可退内则按未开票，否则全部在已开票可退内则按已开票，都不行 409 state_mismatch，请按 invoiced 拆成两张。桥让 U8 按原发货单生成整张红字单（GetNegaVouchData），只留请求的行，改为新增，数量改为负的本次退货数，金额按比例缩放后由 U8 按数量和单价重算；iCorID / cCorCode 指回原发货行和原单号，原行有订单关联时挂上 iSOsID、csocode、cordercode、iorderrowno。保存后在同一事务里核对：新单行数、每行负数量与合计；原发货行 iRetQuantity 与 fretqtywkp（未开票）或 fretqtyykp（已开票）加了本次数量；挂订单的销售订单行 fretquantity 加、iFHQuantity 减了本次数量（同一订单行按合计）。不符回滚并 409 u8_rejected，审计 detail 记基准值和实际值。

销售出库

• 省略 lines 时一次生成该发货单剩余的全部行，没有剩余 409「没有可出库数量」。带 lines 时只出列出的发货行和数量：行不属于该发货单 400「明细行不存在」，行上有其他字段 400「不能设置字段 x」。已关闭的发货行（cSCloser 非空）整单生成时不出，带 lines 列出它 409 state_mismatch「明细行已关闭」。
• 两步、非原子：桥先让 U8 整单生成并提交，再按发货行比较生成数量与应出数量（带 lines 为请求数量，不带为该行剩余数量），多出的在另一个事务里改回：新单的行改为应出数量（辅数量按换算率、有单位成本时金额按数量重算），不要的行删掉，一行都不要的整张删掉，提交前核对发货行累计出库数量等于生成前加应出数量。不带 lines 时这一步通常无动作；此前部分出库过的发货单 U8 会按原剩余数量整份再出，桥把它改回真实剩余。
• 第二步失败（含带 lines 时生成不足请求数量、要改数量的出库单有货位记录）时，桥删除第一步生成的全部出库单，核对累计出库数量回到生成前，返回 409 u8_rejected「已撤回生成的销售出库单：<原因>」；撤回也失败时 504 outcome_unknown，消息列出生成的出库单 id，先到 U8 核对，不要直接重发。
• 跨仓库时一张发货单生成多张销售出库，响应另有 ids（保留下来的全部新主键，升序，id 是第一张）。
• 第一步总是出该发货单剩余的全部行，所以带 lines 时每一个未出完的行都须能按剩余数量整行出库（库存够、货位仓有货位、批次存货有批号）；任何一行出不了，整个请求 409（例如 stock_shortage，消息里可能是未列出的另一行的存货）。此时先在 U8 处理那一行（补库存、关闭该行等），或在 U8 客户端出库。
• 批号、货位：每行另可带字符串 cbatch（最长 60）、cposition（最长 20）；同一 source_line_id 可列多次（拆行），批号或货位不同，各次数量之和是该发货行的应出数量。仓库不能改（跟发货行；要换仓库请在发货单生单时写行上的 cwhcode）。调用 U8 之前桥先查：存货未启用批次管理却填批号 400「存货 X 未启用批次管理，不能填批号 cbatch」，保质期管理的存货填批号 409（暂不支持）；仓库未启用货位管理却填货位 400「仓库 W 未启用货位管理，不能填货位 cposition」；货位不存在、不属于该仓库、非末级 400；拆行时批次存货每次都要有批号、货位仓每次都要有货位，两样都不管理的存货不能拆（400）；批号在该仓库的可用量（iQuantity − fStopQuantity，冻结行为 0，按自由项匹配）、货位上该存货的结存（InvPositionSum，批号取请求的或发货行的）不足 409 stock_shortage（多行合计）。
• 按上述两步生成、改数量后再多一步：出库行的批号、货位与请求一致（U8 已按发货行带出且数量一致）则不改；否则在事务外读出单据、在新事务里修改（只带数量的请求行不动，U8 生成几行就是几行）：该发货行的第 1 行改为请求的第 1 次（数量、批号、货位；换批号时清掉批次属性和生产 / 失效日期等随批号的列，再按批次属性档案 AA_BatchProperty 填新批号属性；应发数量、应发件数随之改），多出的次数复制该行追加（同一 iDLsID），多余的行删掉；货位记录（InvPosition）由 U8 保存时写。提交前核对发货行累计出库数量、每个发货行的出库行与请求一一对上、带货位的行都有货位记录、指定批号的行批次属性与档案一致，不符回滚。这一步失败同样按上文补偿（409 u8_rejected「已撤回生成的销售出库单：…」）。U8 生成时已带出货位记录的出库单又要改批号或货位时拒绝（按失败补偿）。

采购#

• 到货单：订单须已审核、未关闭、普通采购，行未关闭、有单价。
• 采购退货单：quantity 填正数，桥写负的数量、件数和金额（单价取原到货行或订单行），表头 iBillType=1、bNegative=1、iVTid=8169。参照到货单时原到货单须是蓝字（否则 409「来源须为蓝字到货单」）、已审核、未关闭、普通采购，新行 iCorId 是原行 Autoid，有订单行时带 iPOsID、cordercode；参照采购订单时带 iPOsID、cordercode。超过可退数量 409「超过可退货数量」；浮动换算率或带自由项的来源行 409；有订单行时，同一订单行上本单退货合计不能超过订单行 iArrQTY（409「超过采购订单行可退货数量」）；可退数量在事务里加 UPDLOCK、HOLDLOCK 重读。保存后在同一事务里核对回写：参照到货单时原到货行 fRetQuantity 加、订单行 fPoRetQuantity 加、iArrQTY 减本次数量；参照采购订单时订单行 fPoRetQuantity 加、iArrQTY 减（审核、弃审、删除后均复原）。不符回滚并 409 u8_rejected。采购退货单与到货单共用编号，两者的生单互相串行。
• 采购入库（参照采购订单）：需要来料检验的存货 409「该存货需来料检验，不能直接入库」。外币订单：表头币种 cExch_Name、汇率 iExchRate 取订单的 cexch_name、nflat，原币按采购公式计算（u8-notes.md），本币单价、金额、税额、价税合计 = 原币 × 汇率（单价 6 位、金额 2 位，即 iSum = round(ioriSum × 汇率, 2)）。
• 采购入库（参照来料检验单）：检验单须已审核、来源是到货单、不是合并检验（409「合并检验的检验单暂不支持生单」），到货行未关闭。
• 采购入库（参照到货单，source_type: "arrival"）：到货单须是蓝字（iBillType=0，否则 409「来源须为蓝字到货单」）、已审核、未关闭、普通采购，行未关闭。到货行要来料检验（bGsp=1）或存货 bPropertyCheck=1 时 409「到货单的存货需要来料检验，请先报检、检验后参照检验单入库」。表头 csource=采购到货单、ipurarriveid / carvcode / darvdate 指向到货单，cordercode 只在各行属于同一张订单时写；行 iarrsid 是到货行 Autoid，iposid / cpoid 取到货行的订单行，单价、税率取到货行（字段与 U8 界面参照到货单生成的入库一致）。可入库数量在事务里加 UPDLOCK、HOLDLOCK 重读；保存后在同一事务里核对到货行 fValidInQuan 加了本次数量（订单行 iReceivedQTY 只记审计），不符回滚并 409 u8_rejected。账套开启「普通业务必有订单」且订单已有到货单时，参照订单生成入库 U8 报「该操作会造成订单到货和入库同时存在」，应改为参照到货单。这样生成的入库可以生成采购发票（行上带订单行）。
• 红字采购入库（source_type: "purchase_return"）：采购退货单须是 iBillType=1（否则 409「来源须为采购退货单」）、已审核、未关闭、普通采购、不受审批流控制，行未关闭。表头 bredvouch=1、csource=采购到货单（U8 库存来源枚举里没有「采购退货单」）、carvcode / ipurarriveid 指向退货单，行 iarrsid 是退货行 Autoid，数量、金额为负。可入库数量在事务里加 UPDLOCK、HOLDLOCK 重读；保存后在同一事务里核对退货行 fValidInQuan 减了本次数量（订单行 iReceivedQTY 只记审计），不符回滚并 409 u8_rejected。不按 bPropertyCheck 拒绝（退的是已到货的货）。
• 采购发票：入库单须已审核、来源为采购订单或来料检验单、普通采购、蓝字，行有订单行和单价、未结算；发票日期所在期间采购未结账。同一发票号加类型已存在 409「发票号已存在」。
• 红字采购发票：来源入库单是红字（bredvouch=1）时生成红字发票：入库单须已审核、普通采购、来源为库存 / 采购订单 / 来料检验单 / 采购到货单，行数量为负、有单价、未结算，不要求订单行；quantity 填正数，桥写负的数量和金额（单价为正），表头 bNegative=1，VoucherCO_PU.Init 的 bPositive 传 false，其余同蓝字。保存后在同一事务里核对入库行 iSumBillQuantity 减了本次数量，不符回滚并 409 u8_rejected。红字发票可删除、复核、取消复核（闸门同蓝字，Init 同样用 bPositive=false），不能修改。

库存与生产#

• 调拨单参照调拨申请单：申请单须已审核、未关闭、不受审批流控制；行未关闭（cBCloser）、核准数量大于 0，否则 409「明细行已关闭」「调拨申请行没有核准数量」；超过核准减累计 409「超过调拨申请行的可调拨数量」（事务里加锁再查一次）。走 USERPCO 的 Insert("12")（同调拨单新增，vt_id=89、csource=1）；表头仓库、部门、业务员、收发类别取自申请单（部门等可由调用方改；申请单无收发类别且调用方未给时桥不补缺省，U8 要求时由 U8 拒绝），ctranrequestcode 写申请单号；表体 itrids = 申请单行 autoID，存货、批号、自由项、保质期、辅计量照申请单行，件数按换算率重算。提交前在同一事务里核对新调拨单各行都带 iTRIds、申请单行 iTvSumQuantity 加了本次数量，不符回滚 409 u8_rejected。这样生成的调拨单不能修改（409，删除后重新生成）；删除时在同一事务里核对 iTvSumQuantity 已退回。申请单已有调拨单参照时不能弃审、修改、删除（§6、§9）。响应另有 source_type、source_id。
• 材料出库：订单行须已审核、未关闭，子件须是领料方式，否则 409「生产订单未审核」「生产订单已关闭」「该子件不是领料方式，不能生成材料出库」。
• 产成品入库（参照产品检验单）：检验单须已审核、来源是生产订单、未入库完毕（表头 BPROINFLAG=1 409「检验单已入库完毕」）。非合并检验只能 1 行（多行 400「非合并检验的检验单只能有 1 行」）。合并检验的检验单（BMERGECHECKFLAG=1）每个来源一行，生成一张入库单：source_line_id 不是该检验单的合并来源 400「明细行不存在」（field 为 lines.<i>.source_line_id）；来源已入库完毕（BPROINFLAG=1）409「该合并来源已入库完毕」；来源的生产订单行须已审核未关闭、存货与检验单相同；数量不超过该来源的合格 + 让步 − 累计入库。表体每行 iMPoIds、cmocode、imoseq 取该来源的订单行，iNQuantity 是该来源合格数，imergecheckautoid 是来源 AUTOID，iCheckIdBaks 仍是检验单 ID；表头不写 cMPoCode（同 U8 客户端）。提交前在同一事务里核对来源累计入库数、检验单累计入库数、各订单行合格入库量都加了本次数量，不符回滚并 409 u8_rejected。
• 产成品入库（参照生产订单）：订单行须已审核未关闭；库存选项 ST.bQuality 为真且订单行 QcFlag=1（需要检验）时 409「生产订单行需要检验（QcFlag=1，库存选项 ST.bQuality），请参照产品检验单入库」。csource 写「生产订单」，表体 iMPoIds 是 MoDId，不写检验单。提交前在同一事务里核对 QualifiedInQty 加了本次数量，删除时核对减回；不符 409 u8_rejected 并回滚。这种入库单不能修改（409「只能修改来源为产品检验单的单据」）。
• 产成品入库（参照产品不良品处理单）：处理单须已审核（受审批流控制的须审批完成），来源是生产订单，订单行已审核未关闭；只接处理流程为「降级 / 让步接收 / 升级」（IDISPOSEFLOW=2）的行，否则 409「该不良品处理方式不能入库」；已入库完毕（BFLAG=1）409「不良品处理单已入库完毕」。入库存货是处理后存货（CDIMINVCODE）。保存后在同一事务里核对本行已入库数、生产订单行合格入库量（QualifiedInQty）都加了本次数量、入库满额时 BFLAG 为 1，不符回滚并 409 u8_rejected。

质量单据#

• 通用：U8 单据模板（VT 351 到 356，其他报检单 361、其他检验单 365）设为必输而请求未给、桥也推不出的字段，一次列出全部，400 bad_request「缺少必输字段 x（U8 单据模板设置为必输）」。检验单的扩展自定义项（chDefine11 等）常被设为必输，须由调用方填。U8 拒绝时 409 u8_rejected，message 是 U8 原文（错误列表的描述，或 ErrBag 的 description）。
• 来料报检单、产品报检单：来源到货单须已审核、是蓝字（采购退货单 400）；到货行可分次报检，不超过剩余数量（iQuantity − fInspectQuantity）；已全部报检（bInspect=1）的行 409，与 U8 的报检参照（只列 binspect=0 的行）一致。生产订单行须已审核、未关闭、要质检（QcFlag=1，否则 409）。报检人（CMAKER）是登录操作员姓名；单号按账套单据编号设置取（响应 code 取保存后的表）。U8 在保存中回写来源累计报检数（到货行 fInspectQuantity，满额时 bInspect=1；生产订单行 DeclaredQty），并按质量管理选项自动审核，响应 state 是回读结果。保存在桥的事务里：U8 先回写再校验，校验失败时已加上的来源累计数随事务回滚（见 u8-notes.md）。
• 来料检验单、产品检验单：报检单须已审核（经接口只能依靠 U8 保存时的自动审核，见 §6）。一张检验单一个存货，只能 1 行。fRegQuantity、fConQuantiy、fDisQuantity 都不小于 0，三者之和须等于 quantity（400）；省略 fRegQuantity 时取 quantity 减另外两项。cCheckPersonCode 须是存在的人员编码，否则 400。project_code 是检验方案编码（QMCHECKPROJECT.CPROJECTCODE，未停用）；省略时取同一存货最近一张同类检验单的方案，一张都没有 400「请指定检验方案 project_code」。cChkConclusion 缺省：不良数为 0 时「合格」，否则「不合格」。检验项目缺省为方案里的全部项目，检验值取标准值、判定「合格」；带 items 时整组替换：1 到 50 项，每项 cChkItemCode、cChkGuideCode 必填，可带 cCheckValue（检验值）、cTargetQJug（只能是「合格」或「不合格」），字符串最长 60，同一项目加指标重复 400。单号由桥按单据编号规则分配（U8 照收调用方送的号，不自行编号）。新检验单未审核、未提交审批，响应另有 wf（controlled 是否受审批流控制、verify_state_new 为 0），之后照常走 workflow/submit。U8 回写报检单行 FSUMCHECKQTY，检完时 BFLAG=1。保存由 U8 自行提交：桥先查完条件，调用后在新连接上回读新单；调用异常且回读不到 504 outcome_unknown，先按报检单核对再决定是否重发。

不良品处理单生单#

qm_incoming_reject（QM05）参照来料检验单，qm_product_reject（QM06）参照产品检验单，source_type 省略取对应的检验单类型。走 U8 质量管理组件 clsArrRejectCO / clsProRejectCO 的 AddVoucher，登录子系统 QM。

{"type": "qm_product_reject", "source_type": "qm_product_check", "id": 5,
 "head": {"dDate": "2026-01-10", "cDefine1": "批次复核"},
 "lines": [
   {"source_line_id": 5, "quantity": 1, "cScrapDisCode": "Sys01", "cReasonCode": "01"},
   {"source_line_id": 5, "quantity": 2, "cScrapDisCode": "Sys03", "cReasonCode": "01", "cDimInvCode": "A02", "cbWhCode": "01"}
 ]}

• 检验单须已审核（受审批流控制的须审批完成）、来源行未关闭（到货行 cbcloser / 生产订单行 CloseUser）、尚无不良品处理单、不良品数量大于 0，否则 409 state_mismatch：已有 CHECKID 指向它的处理单 409「检验单已生成不良品处理单」；BREJFLAG=1 却找不到处理单 409「检验单已标记生成不良品处理单，但找不到对应单据，需在 U8 中核对」。source_line_id 不等于 id 400「source_line_id 必须等于检验单 ID」。
• 表头另收扩展自定义项 chDefine11…16（按 U8 模板字段名的原样大小写；产品不良品处理单模板常把 chdefine15 设为必输，缺少时 400「缺少必输字段 chDefine15（处理类型）（U8 单据模板设置为必输）」，括号内是 U8 界面标题，field 为 head.chDefine15）。表体的部门、件数、处理后单位与件数由桥按检验单、报检单和存货补齐（见 u8-notes.md）。
• 各行数量之和不等于检验单不良品数量 400（field 为 lines）。处理方式（QMSCRAPDISPOSE）、不良原因（Reason，只收质量管理类 iReasontype=1）、处理后存货、仓库不存在 400。处理流程为 2（降级、让步接收、升级）的处理方式须给 cDimInvCode，桥写处理后数量 FDIMQUANTITY = 本行数量；其他处理方式给了 cDimInvCode 也 400。表头、表体都没有备注列，cMemo、cbMemo 400「不能设置字段」。
• 新单 IsWfControlled 按 QM05 / QM06 是否有已启用的审批流程写 1 或 0；受控的新单之后走 workflow/submit。单号按 U8 编号规则取（来料 QMRJ、产品 QMPJ + 单据日期 + 4 位流水），取号不退。U8 单据模板（VT 355 / 356）必输项未填满 400「缺少必输字段 …」。
• 保存由 U8 自行提交，不在桥的事务里；预演（dry_run）在 U8 参照带入、必输项核对之后、取号之前停止。保存后在新连接上按检验单查找新单，核对单号、制单人、表体行数和检验单 BREJFLAG=1（U8 保存后置 1）；找不到且 U8 报错 409 u8_rejected，回读失败或不符 504 outcome_unknown（先 vouchers/list 按检验单核对，不要直接重投）。
• 功能权限：来料 QM02010303、产品 QM02020303；数据权限按检验单的供应商、部门、存货、仓库。

其他检验单生单#

qm_other_check（QM15，VT 365）参照已审核的其他报检单（qm_other_inspect），一个报检单行生成一张检验单。走 U8 质量管理组件 UFQMCo.clsOtherCheckVoucherCO（基于 VO 的接口，同不良品处理单）的 AddVoucher，登录子系统 QM。

{"type": "qm_other_check", "source_type": "qm_other_inspect", "id": 1001,
 "head": {"cCheckPersonCode": "op001", "cDepCode": "D901", "project_code": "P01"},
 "lines": [{"source_line_id": 1101, "quantity": 100}]}

• 请求规则同来料检验单（cCheckPersonCode 必填，表体恰好 1 行，合格、让步、不良数量之和等于 quantity，可带 items、fDtQuantity、cChkConclusion、project_code、cDefine1…16、chDefine11…16）。检验部门 cDepCode 省略时取检验员（Person）的所属部门，都没有 400（field 为 head.cdepcode）；不以报检部门代替。检验方案缺省取同存货最近一张其他检验单的方案。
• 报检单须存在（404）、已审核（409）；source_line_id 不是本单的行 400；该行已有检验单 409「已生成其他检验单」，BFLAG=1 却找不到检验单 409。U8 不写报检单行累计检验数量（FSUMCHECKQTY），是否已检看 BFLAG。quantity 不能超过行数量。
• 没有来源单据：不写 CSOURCE、SOURCEID、SOURCEAUTOID、SOURCECODE；检验类型取报检单的（OTH）；ISWFCONTROLLED、IVERIFYSTATE、IVERIFYSTATENEW 都写 0，新单未审核，可用 §6 直接审核。表头、检验项目的字段集同来料检验单，属性名按 U8 模板字段名大写。单号按 U8 编号规则取（卡片 QM15），取号不退。U8 单据模板（VT 365）必输项未填 400（有的账套把 chDefine11…13 设为必输）。
• 保存由 U8 自行提交；预演（dry_run）在必输项核对之后、取号之前停止。保存后在新连接上按报检单行（INSPECTAUTOID）查找新单，核对制单人、检验项目行数等于方案行数、报检单行 BFLAG=1；不符 504 outcome_unknown。成功响应另有 items（检验项目行数），没有 wf。
• 功能权限：QM02060203；数据权限按检验部门、存货。

采购结算单生单#

purchase_settle（卡片 99）参照一张采购发票自动结算：每个发票行按其 RdsId 与采购入库行配对，结算数量等于发票数量，一张发票生成一张结算单。走 U8 采购组件 VoucherCO_PU（载入发票后 CheckSettle、bRdBVAutoSettle），在桥的事务里，可预演（dry_run 回滚模式）。

{"type": "purchase_settle", "source_type": "purchase_invoice", "id": 9000000007,
 "head": {"settle_date": "2026-01-31"}}

• 不能带 lines（不支持按行结算，400）。表头只收 settle_date（yyyy-MM-dd，可省），给了即为本笔的 U8 登录日期（覆盖 date），U8 写进结算单 dSVDate 和发票 dSDate。settle_date 不能晚于今天，否则 400；它不与请求的 year（账套年度库）比较。
• 结算日期：不早于发票日期和各入库单日期（409）；所在期间（按 U8 会计期间 UA_Period，不在任何期间内 409）采购未结账（GL_mend.bflag_PU，409「结算日期所在期间采购已结账」）；所在月以前的各月采购须已结账，否则 U8 拒绝，409 u8_rejected 带 U8 原文（「当前登录日期所在的会计月以前的月份未结账，不能结算」）。上月尚未结账时，把 settle_date 设为上月最后一天。
• 发票须存在（404）、普通采购、非期初、蓝字、非现付、已采购复核（cVerifier）、未结算（表头、表体 dSDate 为空且没有结算行，否则 409「发票已结算」），1 到 400 行；每行都参照采购入库单（UpSoType 为 rd、RdsId 指向存在的入库行），入库单已审核、供应商与发票相同（否则 409「采购入库单的供应商与发票不一致」）。不检查应付审核，结算也不做应付审核（cPBVVerifier 不变；应付审核走 vouchers/verify 的 arap_verify）。
• 桥在同一事务里核对：恰好生成一张结算单，行数等于发票行数，每行（iRdsID、iBsID、iSVQuantity）等于发票行（RdsId、ID、iPBVQuantity），结算单 dSVDate 和发票表头、表体 dSDate 都等于结算日期，应付审核人未变，@@TRANCOUNT 未变；不符回滚并 409 u8_rejected。U8 同时回写入库行的结算数量和成本（同月结算时入库行金额改为结算金额，跨月由存货核算的暂估处理接手）。
• 成功响应同生单：id 是新结算单 PSVID，code 是结算号，lines 是结算行数，state.verified 为 false，另有 settle_date。提交后在新连接上回读不到 504 outcome_unknown。
• 功能权限「自动结算」PU040301（在状态检查之前查）；数据权限（状态检查之后）按发票的供应商（必有）、部门、业务员、采购类型和每行的存货（必有）、入库仓库（可空列）。

12. 收付款单和应收应付单#

ar_receipt（收款单）、ap_payment（付款单）在 Ap_CloseBill，ar_bill（应收单）、ap_bill（应付单）在 Ap_Vouch。新增、修改、删除只处理手工录入的蓝字单据。核销、取消核销、自动核销、制单、取消制单、坏账、转账（应收冲应付、并账、红票对冲）、汇兑损益见本节各小节。

新增字段名不分大小写，用 U8 列名。名单外 400「不能设置字段 x」，同名重复 400「字段重复 x」。自定义项表头 cdefine1…16，表体 cdefine22…37。

规则：

• 日期缺省登录日期，币种缺省账套本位币（foreigncurrency.iotherused = -1）。本位币汇率缺省 1 且必须是 1，原币金额必须等于本币（消息里写本位币名称，如「人民币单据的汇率必须是 1」）。与本位币有关的检查在登录后做，登录前只查字段和金额格式。
• 外币必须给 iExchRate（400「外币必须给汇率」），每行必须给原币金额；本币不给按 round(原币 × 汇率, 2) 算，给了要与之相差不超过 0.01。
• 外币应收单 / 应付单的行币种按行科目（单据日期所在年度的科目表）定，与 U8 客户端录入一致：科目核算币种（code.cexch_name）等于表头币种的行用表头币种、汇率和原币金额；其余科目（收入、费用、税金等）的行记本位币，汇率 1，iAmount_f = iAmount = 本币金额（round(原币 × 汇率, 2) 或调用方给的本币）。bexchange 不参与判断。行上仍按表头币种送原币 iAmount_f，行的 cexch_name / iExchRate 不能送。行科目核算的外币既不是表头币种也不是本位币时 400「科目 x 按…核算，与单据币种…不一致」（field lines.N.ccode）。
• 外币应收单 / 应付单的表头本币必须等于各行本币之和，且等于 round(表头原币 × 汇率, 2)（U8 保存时两条都查），表头原币是各行原币之和。两者不等时桥把差额并到一行记本位币、本币未由调用方给出的行（优先本次送了原币的行；修改时也可以是不动的行，该行随之按新金额重拆税额）。没有可调的行、差额超过 0.01 × 行数、或调整后该行不大于 0：400「表头本币 … 与原币合计 … × 汇率 … = … 不一致，请调整某一记本位币行的本币金额」（field lines），不调用 U8；全是外币科目行的多行单据尾差一分时同样 400。修改时表头原币只按删除、新增、改金额、改币种的行增减（记本位币的已有行按 round(本币 / 汇率, 2) 折回原币），只改表头或备注、部门等时表头合计不动。
• 金额大于 0、不超过 1000000000000、最多两位小数，只能建蓝字单据。
• 单据日期所在月份应收或应付已结账时 409「应收已结账」/「应付已结账」。
• 币种、结算方式、部门（末级）、业务员、项目大类和项目先查存在，不存在 400。
• 表头金额、未核销金额、应收应付单的不含税金额和税额由桥计算（见 u8-notes.md）。部门、业务员、摘要行上没给就取表头。

期初单据（bStartFlag=1）不经这几条路由，用 openings/arap（§29）。弃审和删除都拒绝已生成凭证、非手工录入（含期初）、来自票据或网银、已核销的单据；弃审还拒绝除本单审核行以外还有往来明细、审核期间已结账；删除要求未审核且没有任何往来明细。都是 409 state_mismatch。审核成功要求新连接上审核人等于登录操作员姓名。

例外：notes/create 登记生成的收款单（cSrcFlag='C'、cCoVouchType='50'）同 U8 收付款单审核界面可以弃审，条件是票据号与来源号一致、来源票据的 iCloseID 指向本单（分包票据的收款单票据号是「票据号-起-止」，起止须与票据的子票区间一致）、票据不是期初、没有处理记录（AP_Note_Sub）、余额等于票面、没换票，其余弃审条件照旧（不满足 409 state_mismatch，如「票据 X 已有处理记录（结算、贴现、背书等），不能弃审其收款单」）。这类收款单不能修改、删除，删除走 notes/delete。

核销 arap/writeoff#

收款单（付款单）的一行，对若干张销售发票、应收单（采购发票、应付单）核销，相当于 U8 应收（应付）款管理的手工核销。调用 U8 核销组件 U8ApCancel.cLsCancel（Init 后 Save 核销报文），登录子系统随收付款单（收款单 AR、付款单 AP），在桥的事务里执行。

请求（不带 type、id）：

{"receipt": {"type": "ar_receipt", "id": 9000000005, "line_id": 9000000103},
 "items": [{"type": "sale_invoice", "id": 9000000006, "line_id": 9000000104, "amount": 6.00}]}

币种：收付款单的币种和汇率就是这次核销的币种和汇率（表头为空按本位币；本位币汇率必须是 1，外币汇率必须大于 0）。每张单据必须与它同币种，否则 409 state_mismatch「…的币种与收付款单不一致」。单据自己的汇率可以不同：同 U8，核销一律按收付款单的汇率记，汇兑差额留给期末汇兑损益（9M，见 arap/exchange_gain），本接口不做。报文 close 和每个 vouch 都写收付款单的 cexchname、iexchrate；本币 = 原币 × 收付款单汇率四舍五入到分，close 按合计折算，各 vouch 逐个折算，尾差并到第一个 vouch。余额核对一律按原币。

预收 / 预付行（Ap_CloseBills.bPrePay=1，即新增时 iType=1 的行）同样可以核销，报文带 bprepay="1"。U8 在这种行上核销时可能另插 Ap_CloseBills 行，桥核对余额时按行主键重读该行，再加上 Save 新插行（本收付款单上行主键大于调用前最大值的行）的余额。

以 AR / AP 登录时 U8 的 Save 不查日期、期间和锁，这些由桥在事务里带锁读单据后检查：

• 收付款单存在且类型对得上（否则 404）、已审核（cCheckMan）、该行未核销余额 iRAmt_f 大于 0；
• 每张单据存在（否则 404）、已应收（应付）审核（有原始往来明细行）、往来单位（原始往来明细的 cDwCode）与收付款单相同；
• 收付款单和每张单据不受审批流控制（否则 409 workflow_enabled），采购发票没有网络锁（iNetLock）；
• 每行的未核销余额不小于 amount，口径与 U8 相同：Ar_Detail / Ap_Detail 上 cCoVouchType、cCoVouchID 是该单据，cDwCode 是往来单位，iBVid 是该行，iFlag<3（NULL 不算），应收取借方减贷方，应付取贷方减借方；
• amount 合计不超过收付款单该行的未核销余额；
• 核销日期不早于收付款单和每张单据的日期，也不早于应收（应付）启用日期（AccInformation 的 dARStartDate / dAPStartDate）；
• 会计期间按 UFSYSTEM..UA_Period（dBegin ≤ 日期 ≤ dEnd）定，不一定是自然月；找不到期间 409，该期应收（应付）已结账（GL_mend.bflag_AR / bflag_AP）409「应收已结账」/「应付已结账」。

400 bad_request：字段、类型、数量、金额不合法；line_id 不属于该单据「明细行不存在」；没给 line_id 而收付款单或发票有多行未核销余额（「请指定 line_id」）。其余拒绝（含币种不一致）都是 409 state_mismatch。U8 的 Save 抛错或返回 false 时 409 u8_rejected，message 为 U8 原文。桥不查 Locked_by_Other（LockVouch 表），见 docs/limitations.md。

U8 写入 Ar_Detail / Ap_Detail 的 9P 行（同一个新核销号 cCancelNo，HXAR… / HXAP…；每个单据行一条，另有收付款单的冲减行），并更新收付款单行余额、发票累计核销、应收应付单余额。提交前核对：收付款单该行余额减少了合计、每个单据行余额减少了各自金额、本收付款单上新写的核销行只有一个核销号，否则回滚、409 u8_rejected；事务已被数据库回滚（如死锁牺牲品）503 u8_unavailable（未写入，可以重试）。提交后在新连接上回读本核销号的核销行，每个单据行的金额和收付款单冲减合计对得上才算成功；不符或回读失败 504 outcome_unknown（已提交，先用 reports/arap_detail 或 vouchers/load 核对，不要直接重投）。

响应：

{"ok": true, "acc": "801", "cancel_no": "HXAR0000000000001", "date": "2026-09-28",
 "receipt": {"type": "ar_receipt", "id": 9000000005, "line_id": 9000000103, "code": "SK0000000001", "remaining": 844.00},
 "items": [{"type": "sale_invoice", "id": 9000000006, "line_id": 9000000104, "code": "SOZP0000000001",
            "amount": 6.00, "remaining": 0.00}]}

remaining 是核销后的未核销余额；应收单、应付单没有 line_id。

• 锁键：收付款单、每张单据，另加 arap:writeoff:AR / arap:writeoff:AP（同一侧的核销串行）。
• 功能权限：应收「手工核销」AR050201 或「选择收款」AR0503，应付 AP050201 或「选择付款」AP0503（U8 的选择收付款在一个界面里同时收付款并核销，所以也放行）。数据权限按收付款单和每张单据表头的往来单位（必控）、部门、业务员，任一张不在权限内 403。
• 可以带 Idempotency-Key（§20）：收到 504 先用 idempotency/get 查；没带键时先核对再决定是否重试。
• 撤销用 arap/writeoff/cancel。

取消核销 arap/writeoff/cancel#

按核销号整批撤销一次核销，相当于 U8 应收（应付）款管理「其他处理 → 取消操作」里取消一条核销（9P）。U8 没有可调用的取消组件，桥执行与 U8 界面相同的 SQL（9P 分支，实测核对），在请求连接上的一个事务里完成，提交前核对每个余额精确回到核销前。登录子系统就是 flag。

请求（不带 type、id）：

{"flag": "AR", "cancel_no": "HXAR0000000000001"}

只收与 arap/writeoff 同形的批次。桥在事务里带锁读出该核销号的往来明细（条件 cProcStyle=N'9P'、cCancelNo、cFlag，走 U8 索引 INDEX_Ar_Detail_HXZD / INDEX_Ap_Detail_HXZD，只锁这一批）后检查：

• 一行都没有 404「核销号不存在」；超过 500 行 409；
• 每行都是本侧（cFlag = flag）的 9P 行，挂在同一张收款单（48）/ 付款单（49）上，对方是这张收付款单自己（冲减行，iCoClosesID 是它的行）、销售发票 26 / 27 或应收单 R0（应付：采购发票 01 / 02 或应付单 P0）；否则 409（请在 U8 客户端取消）；
• 没有制单（cPZid 为空），否则 409「核销已制单，请先删除凭证」；没有合同（cContractID）；同一会计期间；整批同一币种、同一汇率（否则 409，请在 U8 客户端取消）。外币核销同样能取消：原币、本币分开按核销行加回，与单据自己的汇率无关；
• 核销行的期间（iPeriod，年度按核销登记日期在 UA_Period 上所在的年度）应收（应付）未结账，否则 409「应收已结账，不能取消该期间的核销」；
• 收付款单和每张单据在本批之后（Auto_ID 更大、核销号不同）没有审核登记（Sign）以外的处理，否则 409「单据在本次核销之后还有其他处理，请先取消后面的处理」。Sign 行是 cProcStyle 为 26、27、R0、48、49、01、02、P0 或等于该行单据类型（cVouchType，如期初 50）的行；其余都算后续处理，包括核销 9P、红票对冲 9N、汇兑损益 9M、票据背书 9E、应收冲应付 9I、应付冲应收 9J、票据托收 / 退回 / 贴现 9A / 9C / 9D、并账 BZ 等（与 U8 的判断一致）；
• 应收一侧：账套里有未审核的收款单（不含现结，全账套检查，同 U8 存储过程 AR_ExistUnAuditCloseBill）时 409，U8 同样不让取消；
• 收付款单、每张单据都在（按单号带锁读），采购发票没有网络锁（iNetLock）。

写入内容和顺序同 U8：按冲减行加回 Ap_CloseBills.iRAmt_f / iRAmt / iRAmt_s（表头由触发器 TR_Ap_CloseBills 汇总）；加回应收单 / 应付单 Ap_Vouch.iRAmount_f / iRAmount，iRAmount_s 按原币余额比例重算；销售发票经临时表 #ap_SaleBillVouchHXdata 交 U8 回写组件 Ussaupdispatch.clsWrite2Bill.UpdateBillForAR（同一事务）加回 iExchSum / iMoneySum，并连带销售订单、发货单的累计核销和信用额度；采购发票经 #ap_PurBillVouchHXdata 加回 PurBillVouchs.iOriTotal / iTotal；收付款单各行都回到未核销时清空 cCancelMan、bPrepay 置 0；最后删掉该核销号的 9P 行。不做 U8 的「保留线索」（选项 bAR2Cancel / bAP2Cancel）。

提交前在同一事务里核对：核销行已删光；收付款单每行余额 = 原值 + 冲减合计；每个单据行余额（同核销的口径）= 原值 + 本批金额；应收单 / 应付单 iRAmount_f = 原值 + 本批金额；发票累计核销 = 原值 + 临时表合计。不符回滚、409 u8_rejected；回写组件抛错 409 u8_rejected（原文），改变了事务 504；事务被数据库回滚 503 u8_unavailable。提交后在新连接上确认该核销号的行已不在：读不出或仍在 504 outcome_unknown（已提交，先核对，不要直接重投）。

响应：

{"ok": true, "acc": "801", "cancel_no": "HXAR0000000000001", "flag": "AR",
 "receipt": {"type": "ar_receipt", "id": 9000000005, "line_id": 9000000103, "code": "SK0000000001", "remaining": 850.00,
             "lines": [{"line_id": 9000000103, "amount": 6.00, "remaining": 850.00}]},
 "items": [{"type": "sale_invoice", "id": 9000000006, "line_id": 9000000104, "code": "SOZP0000000001",
            "amount": 6.00, "remaining": 6.00}]}

amount 是加回的金额，remaining 是取消后的未核销余额；批次涉及收付款单多行时 receipt.line_id、receipt.remaining 为 null，看 lines。

• 锁键只有 arap:writeoff:AR / arap:writeoff:AP（涉及的单据入队前不可知，所以与同一侧的全部核销、取消核销串行）。
• 功能权限：「其他处理 → 取消操作」应收 AR0807、应付 AP0807；数据权限同核销。
• 可以带 Idempotency-Key（§20）；收到 504 先用 idempotency/get 查，或用 reports/arap_detail（带 include_writeoff）查该核销号是否还在。

自动核销 arap/writeoff/auto#

对一个客户（供应商）按 U8 的自动核销规则配对，一次核掉多行，相当于 U8 应收（应付）款管理的「自动核销」。U8 的 cLsCancel.AutoCancel 无界面调用时不写入（见 u8-notes.md），所以由桥配对，每行收付款单一批，交给与 arap/writeoff 相同的核心（同一道闸门、同一个 Save 报文：一个 close 下挂这一批的全部 vouch，同样在事务里核对）。登录子系统就是 flag，核销日期是登录日期。

请求（不带 type、id）：

{"flag": "AR", "partner": "C900001", "date_to": "2026-09-28",
 "receipt": {"type": "ar_receipt", "id": 9000000005, "line_id": 9000000103},
 "targets": [{"type": "sale_invoice", "id": 9000000006}],
 "max_amount": 100.00, "dry_run": true}

配对规则（U8 核销规则 iHxRule=0 时的规则，只按往来单位，不按订单、合同、存货）：

• 收付款单一侧：该往来单位下已审核、币种汇率有效（本位币汇率 1，外币汇率大于 0）、不受审批流控制、单据日期不晚于 date_to、行余额 iRAmt_f 大于 0 的收款单（付款单）行，按单据日期、iID、行 ID 排序。预收 / 预付行只在 include_prepay: true 时参加。
• 单据一侧：该往来单位下有未核销余额的行（余额口径同 arap/writeoff），类型为销售发票 26 / 27、应收单 R0（应付：采购发票 01 / 02、应付单 P0），已审核、币种汇率有效、不受审批流控制、采购发票没有网络锁、单据日期不晚于 date_to；按单据日期、单号、行排序。
• 先进先出：第一行收付款单冲第一行单据，每次取两边剩余余额（和 max_amount 剩余）的较小者，一边用完换下一行，直到任一边用完或到上限。只在同币种（空按本位币）的行之间配对；单据汇率不比，按收付款单汇率核销，汇兑差额留给期末汇兑损益。
• 一次最多 20 行收付款单、200 行单据，超出 409，请用 receipt、targets 或 date_to 缩小范围。

账套设置了按规则核销（iHxRule 不为 0，或 bAPAutoCancelWithHxRule 为真）时 409「账套设置了按规则核销（订单 / 合同 / 存货等），自动核销暂不支持」，dry_run 同样。

执行：全部批在一个事务里，逐批先过 arap/writeoff 的闸门（带锁重读，余额含前面各批 Save 的结果；同样的 404 / 409 / 403），再 Save、核对余额和新核销号；任一批失败整体回滚，返回 U8 原文（409 u8_rejected）或闸门的错误。提交后在新连接上逐批回读核销行，不符或回读失败 504 outcome_unknown（已提交，message 列出核销号，先核对，不要直接重投）。没有可配对的不是错误：200，batches 为空、total 为 0。

dry_run：候选查询和配对照做，每一批也过闸门和数据权限（只读，不开事务、不建组件），返回计划。

响应（执行）：

{"ok": true, "acc": "801", "flag": "AR", "partner": "C900001", "date": "2026-09-28", "date_to": "2026-09-28",
 "batches": [{"cancel_no": "HXAR0000000000002",
              "receipt": {"type": "ar_receipt", "id": 9000000005, "line_id": 9000000103, "code": "SK0000000001",
                          "remaining": 750.00},
              "items": [{"type": "sale_invoice", "id": 9000000006, "line_id": 9000000104, "code": "SOZP0000000001",
                         "amount": 100.00, "remaining": 0.00}],
              "amount": 100.00}],
 "total": 100.00}

响应（dry_run）：dry_run: true、mode: "plan"（区别于 §23 的预演响应），plan 每项 {receipt: {type, id, line_id, code, date, remaining}, targets: [{type, id, line_id, code, date, balance, amount}], amount}（remaining、balance 是分配前的余额），另有 total；没有 batches。

• 每一批的核销号可以用 arap/writeoff/cancel 逐个取消（reports/arap_writeoffs 可查）。
• 锁键只有 arap:writeoff:AR / arap:writeoff:AP（与同一侧的全部核销、取消核销串行），受全局写闸门约束（dry_run 也是）。
• 功能权限：「核销处理 → 自动核销」应收 AR050202、应付 AP050202，与手工核销分开（只有手工核销权限不能自动核销），没有时 403 no_permission；数据权限同 arap/writeoff。
• 执行时可以带 Idempotency-Key（§20），dry_run: true 不能带（400「预演不能带 Idempotency-Key」）；收到 504 先用 idempotency/get 查，或用 reports/arap_writeoffs 按往来单位核对。

制单 arap/voucher#

一张已审核的单据生成一张总账凭证，相当于 U8 应收（应付）款管理「制单处理」里对一张单据制单；用 ids 可把同类型的 2 到 20 张单据合成一张凭证（「合并制单」，见下文）。U8 没有可无界面调用的制单组件，桥按 U8 的制单规则拼分录，经 U8 凭证导入组件 U8PzInsert.clsPZInsert.Transact 保存（同 §14，组件自行提交），再做与 U8 相同的回写。登录子系统就是 flag。

请求（带 type、id）：

{"flag": "AR", "type": "sale_invoice", "id": 9000000006, "sign": "转", "voucher_date": "2026-09-24", "digest": "销售"}

支持的单据和分录（与 U8 客户端制单结果一致；科目都按 code 中会计年度 = 制单日期年份的科目查）：

• 收入 / 采购 / 税金科目：先查「对方科目设置」AP_OppCodeSet（cFlag、会计年度）：行上填了的键（存货、存货分类、往来单位、往来单位分类、销售 / 采购类型、地区、币种、税率）都要与单据一致，分类和地区按编码前缀；取最具体的一行（第一个填了的键越靠前越具体，同一个键比编码长度），同样具体的几行给出不同科目 409。没有匹配行再用「基本科目设置」Ap_InputCode：销售收入 xssrkm、应交增值税 xssjkm、采购 cgkm、采购税金 cgsjkm。都没有 409，采购发票是「采购发票制单暂不支持：账套未设置采购科目」。从不猜科目。
• 科目要存在、末级、未封存、不核算外币，否则 409。分录上的档案值同总账新增（§14）逐项再查：部门存在且末级，人员、客户、供应商、结算方式存在，现金流量项目存在且未关闭，否则 409「第 N 行分录的部门 … 不存在或不是末级部门」之类。辅助核算只按科目要求（bcus / bsup / bdept / bperson / bitem）填，值取自单据：客户 / 供应商取往来单位（AR 只能是客户、AP 只能是供应商），部门、个人取明细行或表体行，个人没有部门时取人员档案的部门；项目大类是「存货核算」（fitem.ctable = inventory）时项目取存货编码，其余大类要单据行上带了同一大类的项目。缺值 409。有客户或供应商辅助项的行另写业务员姓名（cname；单据没有业务员写 -）。
• 合并：应收应付选项 bYPzKMHB（发票、应收应付单）/ bSPzKMHB（收付款单）为真（缺省）时，同科目、同方向、同辅助项的行合并。借方在前，同方向保持上面的先后。借贷必须平、2 到 200 行，否则 409。
• 现金流量：总账选项 bXJLL 开着、凭证里既有现金流量科目（code.bCashItem）又有别的科目时，别的科目每行按「现金流量项目数据来源」GL_CashItemDataSource 挂一个项目（按科目编码前缀，bDir 1 对借方行、0 对贷方行，取最长的前缀；有起止日期的按制单日期），金额方向同该行；定不下来（没有匹配的前缀，或同样长的前缀给出不同项目）409「科目 X 的现金流量项目无法按数据来源唯一确定，请用 cash_items 指定，或在 U8 客户端制单」。
• 附单据数 = 单据张数。只做本币（本位币、汇率 1）、蓝字（金额不为负）单据，外币、红字 409。
• 退款单：U8 审核时把退款登记成负数往来明细，凭证与 U8 客户端生成的退款凭证一致：往来行在前、红字（金额为负，留在明细的那一方），结算行翻到同一方、记正数，借贷合计相等（都可以是 0）。供应商退款借 应付 −金额、借 银行 +金额，凭证类别缺省「收」；客户退款贷 应收 −金额、贷 银行 +金额，缺省「付」。摘要缺省同收付款单，都没有时「收<供应商>退款」/「付<客户>退款」。coutsign 两种都是 RP。现金流量行同分录的列和符号（往来红字行的现金流量也是负数），数据来源的方向按分录所在的列取。往来明细之外的费用行不拼：往来明细有 iFlag 0 / 3 / 6 以外的行或借贷不平 409，请在 U8 客户端制单。

闸门（在事务里带锁，409 state_mismatch，文案尽量用 U8 的）：

• 单据不存在 404；类型不在上表 400；
• 未审核（发票：未应收 / 应付审核）或没有审核登记的往来明细；已制单「凭证已生成，不能重复制单。」；
• 现结 / 现付发票（往来明细有 cProcStyle='XJ' 行）409「现结发票请在 U8 客户端制单」；
• 已用于坏账收回的收款单（往来明细有 cVouchType='48'、cVouchID = 该单号的 9H 行）409「收款单 X 已用于坏账收回（处理号 HZAR…），请对坏账收回制单」，用 arap/process/voucher 对该 HZAR 处理号制单；
• 总账里已有本单的凭证（coutbillsign = 单据类型、coutid = 单号、制单系统 flag 或 GL，不论是否记账）而它的外部业务号没有本单任何往来明细引用（上次制单 504 留下的）409「单据已有一张没有回写的凭证 …（外部业务号 …）…」，核对后用取消制单或在 U8 删除该凭证再制单（存货核算结转成本的凭证制单系统是 IA，不算）；
• 单据登记期间应收（应付）已结账；制单日期早于单据日期、不在登录年度内、总账该期间已结账、应收（应付）该月已结账；制单序时控制（bMakShtSort）；
• 科目、辅助项、现金流量、凭证类别如上。

功能权限：应收 AR0508、应付 AP0508（U8 授权目录「生成凭证」）；数据权限按单据表头的往来单位（必控）、部门、业务员（同核销）。

执行分三步：

1. 事务：带锁读单据、过闸门、拼分录，取外部业务号：Ap_CancelNo 里 cType='PZ'、cFlag=AR|AP 的号加一（AR / AP 加 13 位补零数字，如 AR0000000000001；已被占用就往后跳），提交。
2. Transact 保存凭证（renewproofno="y"，U8 取凭证号）。报文带外部来源：voucher_making_system = AR / AP、reserve1（coutsign：付款单 RP、应付单 AR，其余同 flag）、reserve2 = 外部业务号、每条分录 bill_type / bill_id / bill_date（单据类型、单号、制单日期）。按 AR / AP 被拒且确认未写入时改用 GL 再导一次（响应 making_system 说明实际值），仍被拒 409 u8_rejected，带 U8 原文（外部业务号已消耗，同 U8 不回退）。然后（不在事务里）核对 U8 返回的凭证号上正是这张凭证（行数、借贷合计、未记账），否则 504，不碰它。
3. 事务：补齐凭证的来源列（coutsysname、coutsign、coutno_id、coutbillsign、coutid 等）和 GL_CashTable.csign，做与 U8 相同的回写：往来明细 cPZid、dPZDate、cGLSign、iGLno_id、ino_id（该明细行所在分录的分录号）；发票表体 cClue = 外部业务号、cPZNum（如 转-0001）、dSignDate；收付款单、应收应付单表头 cPzID、cPZNum、doutbilldate。核对回写完整、外部业务号没有撞号（U8 客户端取号不等桥的锁：总账里只有本凭证用这个号，往来明细里用这个号的正好是本单的原始行），都对才提交。

第 3 步失败（包括单据在第 1、3 步之间被 U8 客户端制了单、外部业务号撞号）：在新事务里删掉刚生成的凭证（同取消制单；撞号时只按凭证键删本凭证，不清别人的回写）并清掉回写，409 state_mismatch「制单回写失败（…），已删除刚生成的凭证 …」，单据仍未制单；删不掉 504 outcome_unknown，消息带凭证号和外部业务号，请在 U8 里删除该凭证。第 2 步调用异常、返回无法解析或没有凭证号 504 outcome_unknown（凭证可能已保存）。提交后在新连接上回读凭证行和往来明细，对不上或读不出 504。

响应：

{"ok": true, "acc": "801", "flag": "AR", "type": "sale_invoice", "id": 9000000006, "code": "SOZP0000000001",
 "pz_id": "AR0000000000001", "making_system": "AR",
 "voucher": {"year": 2026, "period": 9, "sign": "转", "no": 1, "num": "转-0001", "date": "2026-09-24"},
 "lines": [{"entry": 1, "account": "1122", "digest": "销售…", "debit": 113.00, "credit": 0, "customer": "C900001",
            "dept": null, "person": null, "supplier": null, "item_class": null, "item": null, "settle": null},
           {"entry": 2, "account": "6001", "digest": "销售…", "debit": 0, "credit": 100.00, "item_class": "ch",
            "item": "INV001", "...": "..."},
           {"entry": 3, "account": "2221", "digest": "销售…", "debit": 0, "credit": 13.00, "...": "..."}]}

lines 是提交后回读的凭证行，每行另有 bill_code（凭证行的 coutid，即来源单据号）。bills 是本凭证覆盖的单据 [{"type","id","code","vouch_type"}]（按请求顺序，单张制单也有一项）；type、id、code 是第一张。

合并制单（ids）：与 U8 合并制单的凭证一致（例如多张收款单一张凭证，每行 coutid 是该行来源单据号）。逐张带锁读单据、过上面全部闸门（任一张不合格整笔拒绝，消息前加「ids 第 i 张（id …）」，field 是 ids.<i>）；每张单据各自拼分录、只在本单内合并，再整张排序（借方在前，同方向按单据顺序）；制单日期不早于任何一张单据日期；一个外部业务号、一张凭证，各单据逐张回写。锁键是每张单据的单据键加下面的凭证键。预演的 detail.voucher.sources 列出全部单据、每行分录带 bill_code。取消用 arap/voucher/delete 一次完成。不做混合类型（如发票和收款单一张凭证）、核销制单。

• 锁键：单据键（sale_invoice:<id> 等）、new:gl:<类别>（与总账新增共用，没给 sign 时收、付、转都锁）、arap:voucher:AR|AP，受全局写闸门约束。
• 可以带 Idempotency-Key（§20），收到 504 先用 idempotency/get 查。没带键时注意：504 时往来明细的 cPZid 往往还是空的（凭证已导入、回写没做），不能只看它；先在总账按单据号（coutid = 单号、coutbillsign = 单据类型）或消息里的外部业务号（coutno_id）核对（gl/vouchers/list 看当期新凭证）。直接重投时若总账已有本单没有回写的凭证，本路由 409 并点名那张凭证，不会生成第二张。
• 凭证之后可在总账审核、记账；要改先取消制单再重做（总账的修改、作废、删除只收总账自己做的凭证）。

取消制单 arap/voucher/delete#

按外部业务号删除应收（应付）生成的凭证并清掉单据上的凭证号，相当于 U8 应收（应付）款管理「凭证查询」里删除凭证。桥在请求连接的一个事务里执行与 U8 相同的删除和清除。登录子系统就是 flag。

请求（不带 type、id）：

{"flag": "AR", "pz_id": "AR0000000000001"}

pz_id 是 arap/voucher 返回的外部业务号，或 U8 里制单的单据往来明细上的 cPZid（= 凭证的 coutno_id）；AR / AP 后接 1 到 20 位数字，前缀要与 flag 一致，否则 400。

闸门（带锁）：

• 没有这张凭证 404；一个外部业务号对应多张凭证 409；
• 来源不是发票、收付款单、应收应付单（coutbillsign 不是 26、27、01、02、48、49、R0、P0）409；
• 应收、应付往来明细里引用该外部业务号的行，只要有一行不是本方（cFlag = flag）上述 8 类单据的原始行（cProcStyle = cVouchType）就 409「该凭证不是发票 / 收付款单 / 应收应付单制单或处理制单（应收冲应付、应付冲应收、并账、汇兑损益、红票对冲、票据处理、坏账处理整批）生成的，请在 U8 客户端删除」。核销（9P）、转账等处理生成的凭证也带原单的 coutbillsign，删除时 U8 各有回写，桥不做。没有往来明细引用的凭证（例如制单 504 留下的）可以取消。处理制单的凭证（整批引用）放行，只清凭证号，其中坏账收回（9H）的凭证连同收款单审核行和表头的凭证号一起清；坏账处理的凭证属于第二级写入，条件同 arap/bad_debt；
• 「此凭证已记账，不能删除」「此凭证已审核，不能删除」「此凭证已经出纳签字，不能删除」「此凭证所在期间已结账，不能删除」（U8 原文）；已做银行对账或往来两清；被红字冲销；正被别人编辑（GL_mvcontrol）；不是本系统生成的（coutsysname ≠ flag）；应收（应付）在凭证月份或单据登记期间已结账。

功能权限同制单（AR0508 / AP0508）；数据权限按往来明细的往来单位、部门、业务员。

合并制单的凭证同样一次取消：清除语句按外部业务号执行，引用它的全部单据在同一个事务里清掉凭证号。

写入：删未记账凭证（GL_accvouch、GL_CashTable、GL_CodeRemark）；同 U8 清除发票表体、Ar_BadPara、AR_RZDetail、Ap_Vouch、Ap_CloseBill、Ap_Note_Sub、CM_Balance 上的凭证号，往来明细的 cPZid、cGLSign、iGLno_id（dPZDate、ino_id 不清）。提交前核对凭证行、往来明细、发票线索号、表头凭证号都不再引用该外部业务号，否则回滚 409 u8_rejected；提交后在新连接上再核对：读不出或仍有引用 504 outcome_unknown（已提交，先核对，不要直接重投）。Ap_CancelNo 的号不回退（同 U8）。

响应：{"ok": true, "acc": "801", "flag": "AR", "pz_id": "AR0000000000001", "deleted": true, "voucher": {"year": 2026, "period": 9, "sign": "转", "no": 1}}。锁键只有 arap:voucher:AR|AP，受全局写闸门约束。

坏账 arap/bad_debt#

U8 应收款管理「坏账处理」的三种操作，只做应收（登录子系统 AR）。属于第二级写入（复刻 U8 界面执行的 SQL，已在测试账套实测核对）：缺省关闭，桥 config.json 未开 enableReplicatedWrites 时 403 feature_disabled；打开后只对 testAccounts 里的账套开放，其他账套 403 test_account_only。两道检查在登录前做，含预演。正式账套请在 U8 客户端操作（见 docs/configuration.md、docs/limitations.md）。写入在请求的事务里执行，提交前核对。

某个 action 不收的字段给了就 400。三种处理共用 U8 的处理号 HZAR + 13 位数字（Ap_CancelNo 的 cType=HZ、cFlag=AR，在桥的事务里取号）；currency 省略为本位币。

公共条件（409 state_mismatch，除注明外）：

• 处理日期就是登录日期 date；会计年度、期间按 UA_Period 定，不在任何会计期间里 409「日期 … 不在 U8 的会计期间里」，早于应收启用日期 409；该月应收已结账（GL_mend.bflag_AR）409「应收 YYYY 年 M 月已结账」。digest 为空串或全空白同省略。
• 坏账准备参数（Ar_BadPara）：同 U8，发生、收回都更新 autoid 最大的那一行；该行的 iYear 与 date 所在会计年度不同时 409，不碰别的年度；没有该年度参数行 409「未设置 YYYY 年坏账准备参数（应收款管理 › 设置 › 坏账准备）」；计提方法 iJtStyle 不是 1、2、3 时 409「不支持的坏账计提方法」（不支持直接销售法）。

occur（坏账发生）：lines 每项 {type, id, line_id?, amount}。type 是 26 / 27 / 28 / 29（销售发票）或 R0 到 R9（应收单，不含 RZ；不收收付款单，同 U8），id 是单据号；line_id 是发票表体行，省略时按行主键从小到大分摊，应收单按整单、不能带；amount 是原币，大于 0、最多两位小数、不超过该单据（行）的正余额。同一单据行不能重复，同一单据不能既整单又按行。单据须已审核、属于 customer、币种与 currency 相同；外币各单据的汇率须相同（否则 400），坏账行用单据的汇率折本币。dept（最多 12 位）须是存在的末级部门、person 须是存在的业务员，登记日期当天或之前已停用的也不行（都是 400，同应收单据新增）。写入：一个处理号，每个单据行一行 9G 贷方往来明细（iCAmount / iCAmount_f，cVouchType = cCoVouchType 为原单据，cCode 是原单据的应收科目），冲减单据余额（应收单 Ap_Vouch.iRAmount*；发票经 #ap_SaleBillVouchHXdata 和 U8 回写组件 UpdateBillForAR），坏账准备余额 iRemainAmount 减去本币合计。

recover（坏账收回）：receipt 是该客户、该币种的收款单（48）单号（须唯一），须未审核（cCheckMan 为空）、未核销（cCancelNo 为空）、只有一行应收款（iType=0，多行 409）、不是票据或网银生成、不受审批流锁定；已有往来明细（做过审核、核销或其他处理）时在审核前拒绝（409）。amount 必须等于收款单全部余额，否则 409「坏账收回金额须等于收款单金额 X」（U8 整张收款单一起消耗，取消时整张复原）。写入（一个事务）：先用 U8 收款单审核组件审核收款单（同 vouchers/verify 的 ar_receipt，写审核行（贷方）和审核人；审核日期是登录日期），再写一行 9H 借方往来明细挂在收款单上（cVouchType = cCoVouchType = 48，登记日期为 date，科目取收款单行的应收科目 Ap_CloseBills.cKm），收款单余额 iRAmt* 清零，坏账准备余额加上本币金额。9H 借方与审核行贷方相抵，客户应收余额不变；提交前核对这张收款单上的往来明细（iFlag<3）借贷合计本币、原币都为 0，否则回滚 409 u8_rejected，消息带合计。不另建应收单。制单时一并回写收款单审核行和表头凭证号（见下文「制单」），U8 的制单列表不再列出这张收款单。

provision（计提坏账准备）：按参数行的计提方法算应计坏账准备 target：

方法 3 的取数区间是本服务的约定，与 U8 界面结果不一致时以 U8 为准。本次计提 = round(target − 当前余额, 2)，可以为负（冲回）；为 0 时 409「本次计提金额为 0」。写入：只更新该年度的参数行（dJtDate、iRemainAmount 与 iJtAmount 各加本次计提、cProcStyle=9F、cCancelNo 为本次处理号），不写往来明细；没有该年度参数行时 409（U8 会新增一行，桥不新增）。

响应：{"ok": true, "acc": "801", "action": "occur", "cancel_no": "HZAR0000000000001", "style": "9G", "amount": 120.5, "remain_before": 500, "remain_after": 379.5, "rows": [{"type": "26", "id": "0000000012", "line_id": 1001, "amount": 100.5, "remaining": 0}, …]}。amount 在发生、收回是原币合计，在计提是本次计提（本币）；remain_before / remain_after 是坏账准备余额；style_name 是处理方式名称（坏账发生、坏账收回、计提坏账）；计提另有 base、rate、target、method_name（应收余额百分比法、账龄分析法、销售收入百分比法）。dry_run 是 rollback 模式。

取消（arap/process/cancel，flag=AR，cancel_no 为 HZAR…，开放条件同上）：桥按处理号判断种类（往来明细里的 9G / 9H 行，或参数行 cCancelNo 对应 9F）。处理所在会计年度、期间按处理日期在 UA_Period 里查。

• 条件：未制单（9F 看参数行的 cPZID）、处理所在月份应收未结账；9G / 9H 涉及的单据在本次之后没有审核登记以外的处理。
• 9G：加回单据余额和坏账准备余额。
• 9H：删处理行、收款单余额复原、坏账准备余额减回，再用 U8 收款单弃审组件撤销审核（删审核行和审核人；审核所在期间已结账 409），核对收款单未审核、余额已复原、没有往来明细，不符回滚 409 u8_rejected。收款单没有审核行的 9H（如在 U8 客户端做的坏账收回）409「该坏账收回不是本接口生成的（收款单没有审核行），请在 U8 客户端取消」；收款单号不唯一 409。
• 9F：参数行 iRemainAmount 减去 iJtAmount，iJtAmount、dJtDate 清空（同 U8）；该年度有多行参数时 409。U8 一个年度只在参数行上记最后一次计提的处理号，iJtAmount 是累计数，所以只能取消该年度最后一次计提，且会把同一年度的全部计提一起冲掉；前一次计提不能单独取消（409）。

制单（arap/process/voucher，flag=AR，cancel_nos 为 HZAR…，一次只能是同一种坏账处理，否则 409；开放条件同上）：凭证来源 coutsign 为 JT，coutsysname 为 AR。

• 分录：计提借参数里的对方科目 cDyCode、贷坏账准备科目 cHzCode；发生每行借 cHzCode、贷该行的应收科目（带客户辅助项）；收回借收款单表头的结算科目（要求现金流量项目时同 arap/voucher 收款单的取法）、贷 cHzCode。科目须是登录年度的末级科目，否则 409「坏账准备参数里的科目 X 不存在或不是末级」。收回的借方只取收款单表头的结算科目，没有则 409（收款单行的应收科目不能代替）。
• 回写：9G / 9H 往来明细的 cPZid、cGLSign、iGLno_id、dPZDate；9H 另回写收款单自己的审核行（cProcStyle = cVouchType = 48，ino_id 取借方银行分录）和表头 Ap_CloseBill.cPzID、cPZNum、doutbilldate，收款单已在别处制单则回滚 409；9F 回写参数行 cPZID。
• 取消制单用 arap/voucher/delete，清掉同样这些凭证号。外币坏账发生不能制单（处理制单只收本币明细，409），请在 U8 客户端制单。

读取：9G / 9H 是往来明细里的处理行，出现在 arap/process/list；9F 没有往来明细，只出现在 arap/process/list 的摘要项里（每个年度参数行一项，取最近一次计提），不在按 Auto_ID 增量的处理记录列表里。

功能权限（按 U8 窗体的权限号检查）：发生 AR050602、收回 AR050603、计提 AR050601（上级「坏账处理」AR0506 也放行）；取消同 arap/process/cancel（AR0807），制单同 arap/process/voucher（AR0508）。数据权限按客户、部门、业务员。

应收冲应付、并账、红票对冲 arap/transfer、arap/merge、arap/red_offset#

U8 应收（应付）款管理「转账」里的三种处理。都写往来明细的处理行，发票累计核销经 U8 的回写组件，在桥的事务里执行，提交前核对余额，不符回滚 409 u8_rejected。处理日期就是登录日期 date（缺省今天），须在本系统（转账为应收、应付两边）未结账的期间内，且不早于单据日期和系统启用日期。三者都返回处理号 cancel_no：取消用 arap/process/cancel，制单用 arap/process/voucher（处理号表见 §16「notes/process」末尾）。dry_run 是 rollback 模式。

单据项 {type, id, line_id?, amount}：type 是 U8 单据类型代码，应收一侧 26 / 27（销售发票）、R0（应收单），应付一侧 01 / 02（采购发票）、P0（应付单）；收付款单（48 / 49）不收，请用核销。id 是单据号；line_id 是发票表体行，省略时按行主键从小到大依次分摊，应收单、应付单按整单、不能带；amount 是原币，大于 0、不超过 1000000000000、最多两位小数。同一单据行不能重复，同一单据不能既整单又按行。每侧 1 到 50 项。digest 最多 120 个字符。

请求示例：

{"flag": "AR", "customer": "C900001", "vendor": "S900001",
 "ar_lines": [{"type": "26", "id": "0000000001", "amount": 100.00}],
 "ap_lines": [{"type": "P0", "id": "0000000002", "amount": 100.00}]}

并账每张单据（行）写一对 ± 处理行，单据本身不改；红票对冲调用 U8 的对冲组件 U8ApCancel.cLsCancel.AP_JZ_Red。

响应：

• arap/transfer：acc、flag、style、cancel_no、date、customer、vendor、currency、amount、digest；ar_rows / ap_rows 每项 type、id、doc_id、line_id（整单时省略）、amount（原币）、amount_native（本币）、remaining（处理后的余额）。
• arap/merge：acc、flag、cancel_no、date、from、to、currency、digest、amount（合计）；rows 每项同上，另有 from_remaining、to_remaining。
• arap/red_offset：acc、flag、cancel_no、amount；red_rows / blue_rows 每项同上。

错误：404 not_found 单据不存在；409 workflow_enabled 单据受审批流控制；409 state_mismatch 单据未审核、往来单位或币种不符、余额不足、日期早于单据日期或系统启用日期、期间已结账（转账另有外币两侧折合本币不等，并账另有单据不属于 from、一次超过 500 行，红票对冲另有红蓝方向不对）；U8 拒绝时 409 u8_rejected（带回 U8 原文）。

功能权限：应收冲应付 AR050502、应付冲应收 AP050502，红票对冲 AR050503 / AP050503，并账 AR050504 / AP050504；上级「转账」AR0505 / AP0505 同样放行。数据权限按各单据的往来单位、部门、业务员（并账另按 from、to）。

汇兑损益 arap/exchange_gain、arap/exchange_gain/cancel#

U8 应收（应付）款管理的汇兑损益（处理方式 9M）：按外币余额和调整汇率计算本币差额，每个（往来单位、单据）一个处理号 SYRAR… / SYPAP…，写往来明细，发票累计核销经 U8 的回写组件。属于第二级写入（§3），开放条件同 arap/bad_debt。登录子系统就是 flag；登记日期就是登录日期 date，须在本系统未结账的期间内。

arap/exchange_gain 请求：

{"flag": "AR", "currency": "美元", "rate": 7.0, "partners": ["C900001"]}

响应：acc、flag、date、fiscal_year、period、currency、rate（使用的调整汇率）、rows（写入的明细行数）、total（本币差额合计）、batches（每个处理号的 cancel_no、partner、type、id、lines、diff，diff 是本币差额，借正贷负）。

arap/exchange_gain/cancel 请求：flag，可选 cancel_nos（1 到 200 个处理号，SYRAR… 用 AR、SYPAP… 用 AP，不能重复）；省略时取消登记日期为登录日期 date 的全部未制单汇兑损益。桥按 U8 界面执行的取消 SQL 写，在一个事务里加回余额、删掉明细行并核对。响应：acc、flag、by_date（按日期取消时的日期，按处理号取消时省略）、rows（删掉的行数）、batches、total。

错误：登记时 409 state_mismatch 为币种不存在或是本位币、日期不在会计期间或早于启用日期、期间已结账、批次过多；取消时 404 not_found 为处理号不存在或该日没有汇兑损益，409 state_mismatch 为已制单（先用 arap/voucher/delete 删凭证）、期间已结账、之后还有其他处理。核对不符回滚 409 u8_rejected。dry_run 是 rollback 模式。

制单用 arap/process/voucher，须给 pl_code（汇兑损益科目编码，U8 在制单界面选，桥不猜），只做本币批次。功能权限：汇兑损益 AR0507 / AP0507，取消同「取消操作」AR0807 / AP0807；数据权限按往来单位。

13. 审批流 workflow/*#

只接入了四种质量单据：qm_incoming_check（QM03）、qm_product_check（QM04）、qm_incoming_reject（QM05）、qm_product_reject（QM06）。其他类型 400「该单据类型未接入审批流」。审批流本身（节点、审批人、条件分支）在 U8 里配置，桥只按 U8 的规则推进。

opinion 最长 500 字，不写审计。

wf 对象（state 的响应，也出现在 vouchers/load 和各审批动作的响应里）：

history 响应：{"ok":true,"type","id","code","history":[…]}，每项 action（U8 动作编号）、action_name（submit、agree、disagree、reject、withdraw、return、abandon、resubmit，其他为 other）、task、opinion、person、operator、name、at。

tasks 响应：{"ok":true,"operator","person","tasks":[…],"other_count"}，每项 task_id、type、biz（U8 业务对象，如 QM04）、id、code、task_type、activity_id、from（上一处理人）、created_at（待办到达时间）、title（待办标题，即 U8 消息中心显示的那一句）、piid（同 wf.instance.piid）。other_count 是业务对象无法映射到已知类型的待办条数。操作员没有关联人员时返回空列表。节点名称只存在 U8 的流程定义里，这里不返回；同一节点用 activity_id 区分。

给即时通讯或待办系统建待办：订阅事件服务的 workflow 事件（docs/events.md）得知哪张单据的审批状态或当前审核人变了，再用 workflow/state 的 pending（每个待办人的 person、operator、task_id）决定给谁建、撤哪条；某个操作员自己的待办清单用 workflow/tasks。

审批动作响应：{"ok":true,"type","id","code","action","u8_message","wf"}，wf 是动作之后重新读到的状态。桥清理了本次审批留下的 U8 孤儿任务行时多一个 orphan_tasks_cleaned（行数，只在大于 0 时出现）。

审批相关的错误码（都是 409）：workflow_disabled 单据未启用审批流，already_submitted 已经提交，not_submitted 未提交或没有在途实例，not_current_approver 当前操作员不是待办人（操作员未关联人员时 message 为「操作员未关联人员」）。U8 的审批服务自行提交：返回成功（或调用异常）后在新连接上回读审批状态，既不是目标状态也不是原状态时 504 outcome_unknown（先用 workflow/state 核对，不要直接重试）；回读仍是原状态且调用异常时按 U8 拒绝 409。

审批引擎会尝试向 U8 移动端推送消息：缺省拦下；桥 config.json 设 "mobilePush": true 后照常推送（见 docs/configuration.md）。

14. 总账凭证 gl/vouchers/*#

登录子系统 GL。会计年度取登录日期 date 的年份；请求的 year 是账套库年度，不作会计年度用。

凭证键：period（1 到 12）、sign（1 到 2 个字的凭证类别字，必须在 U8 的凭证类别里）、no（1 到 32767）。

功能权限查 U8 的操作员权限表（本人或所属角色，或 admin），没有时 403 no_permission「没有…权限」：

第二级写入（取消记账、期间损益结转、自定义转账）复现 U8 界面执行的 SQL：桥的 enableReplicatedWrites 缺省关闭，关闭时 403 feature_disabled；打开后只对 testAccounts 里的账套开放（含预演），其他账套登录前 403 test_account_only。正式账套请在 U8 客户端操作。开关说明见 configuration.md，风险见 limitations.md。

create / update#

head 只有 sign、date（缺省登录日期，年份必须等于登录年度；修改时必须在原期间内）、attachments（附单据数，0 到 32767）。修改时 head.sign 必须等于 sign。

lines 2 到 200 行，每行：

借贷合计必须相等且大于 0。凭证号由 U8 编，新增成功 {"ok":true,"period","sign","no"}。

update 整张替换，只改总账自己的、未审核、未签字、未作废、未被红字冲销、未做银行对账或往来两清的凭证；红字冲销凭证和带自定义项的凭证不能修改。调用方不能填的列由桥从原凭证带过来，带这些值的分录在新报文里同一分录号必须仍是同一科目（409「修改不能改动分录的科目顺序」）。

新增和修改由 U8 的凭证导入组件自己提交，不在桥的事务里。调用抛错、应答无法解析、回读失败都是 504 outcome_unknown：先 load 或 list 核对，再决定是否重试。

其他操作#

void（作废）、unvoid（取消作废）、verify（审核）、unverify（取消审核）、sign（出纳签字）、unsign（取消签字）、delete（删除）只带凭证键。成功带 state：verified、checker、audit_date、signed、cashier、posted、void、error；删除另带 deleted: true。

门槛（都是 409 state_mismatch）：

• 未记账、期间未结账、U8 界面没有锁着这张凭证（「凭证正被其他人编辑」）、各行状态一致。
• 修改、作废、取消作废、删除只收总账自己的凭证；其他系统生成的凭证 409「凭证由 X 系统生成，请在来源模块处理」。审核和出纳签字也处理其他系统生成的凭证。
• 作废要求未审核、未签字、未做银行对账或往来两清。删除要求已作废、未记账，不重排凭证号。
• 出纳签字只对有现金或银行科目行的凭证；取消签字只能取消本人的。
• 审核：登录日期不早于制单日期；总账选项「允许制单人审核」「允许取消他人审核」「出纳凭证必须先签字」「修改他人凭证」「制单序时」按 U8 的规则执行。

post（记账）#

请求：period（1 到 12）、vouchers（1 到 200 项 {sign, no}，不能重复）、可选 fiscal_year（缺省登录日期的年份）。例：

{"acc": "801", "operator": "op001", "password": "…", "date": "2026-09-29", "period": 9,
 "vouchers": [{"sign": "转", "no": 3}, {"sign": "收", "no": 12}]}

成功 {"ok":true,"period","fiscal_year","posted":[{"sign","no","state"}],"local_txn":true}，顺序同请求；state 同上，另带 poster（记账人姓名），posted 为 true。local_txn 恒为 true：桥在提交前核对过事务没有升级为 MSDTC 分布式事务。

桥在写线程上直接调用 U8 总账的 .NET 记账组件（与 U8 界面「记账」相同的组件，见 docs/u8-notes.md），不经 COM。全部凭证在一个事务里一次记账，任何一张不合格都不记。门槛（409 state_mismatch，凭证不存在 404）：

• period 必须是该年度第一个未结账的总账期间：早于它「该期间总账已结账」，晚于它「上一会计期间没有结账，不能记账」；记 1 月时上年度必须已结账。
• 每张凭证：各行状态一致、未记账、不是错误凭证、已审核；总账选项「出纳凭证必须经出纳签字」开着时，有出纳科目的凭证要已出纳签字（出纳科目指现金、银行标志恰有一个的科目，两个都勾的不算）；「凭证须主管签字」开着时要有主管签字；U8 界面没有锁着这张凭证。
• 作废凭证同 U8 一样也记账：只打记账标志，不计入科目总账、辅助账；不查审核和签字，但带审核人的作废凭证 409。
• 年度首张凭证：总账选项「期初余额对账不平允许年度首张凭证记账」未开启时先做期初对账（同 U8 界面，会重写对账结果），总账与明细账、总账与辅助账、辅助账与明细账等不平 409「期初余额对账不平」；再做期初试算，不平 409「期初试算不平衡」。期初试算一般取第 1 期的年初余额；年中建账的建账年度取第 1 期的期末余额。
• 操作员姓名含单引号 409。

与 U8 客户端并发：事务第一条语句给 U8 的记账范围表加表级更新锁（持有到提交），U8 客户端的汇总要等桥提交。本年度已汇总未记账的范围同 U8 自己的汇总一样被覆盖；桥记完后在同一事务里清掉本年度的范围。因此若 U8 用户在桥加锁之前已在「记账」向导里汇总，之后再点「记账」不会记任何凭证（向导可能仍报成功），并且 U8「恢复记账前状态」再也撤销不了桥这次的记账；这时让对方重新汇总再记账。

记账过程（一个事务，ReadCommitted，超时 5 分钟）：加锁 → U8 按请求的凭证汇总记账范围 → 桥核对范围与请求完全一致（U8 会静默跳过不合格的凭证，对不上 409 并给原因） → U8 记科目总账、辅助账并回写记账标志 → 桥修正误写的凭证（见下） → 核对 → 清范围 → 核对事务仍是本地事务 → 提交。

U8 的已知缺陷：记账组件回写记账标志时按（期间、类别序号、凭证号）关联范围表，不带年度。多年度的账套库里，别的年度键相同的凭证会被改成本操作员记账（U8 客户端记账同样如此）。桥在同一事务里调用前快照这些行的记账标志和记账人，调用后改回，再核对本次凭证每行已记账、记账人是本操作员、其余行与快照一致，不符整体回滚。

错误（提交之前的错误都回滚、不留痕迹）：

收到 504 先 load 看 posted、poster 再决定是否重试。取消记账见 unpost（第二级写入）；正式账套上记错了用 reverse 或在 U8 客户端处理。

reverse（红字冲销）#

把一张已记账的凭证整张复制为红字凭证（金额取负），同 U8 凭证界面的「冲销凭证」。请求：凭证键 period、sign、no 定位原凭证；可选 fiscal_year（原凭证的会计年度，缺省登录日期的年份，不能晚于登录年度，可以是上一年度，即跨年冲销）、voucher_date（红字凭证日期，缺省登录日期，必须在登录年度内、不早于原凭证日期）。例：

{"acc": "801", "operator": "op001", "password": "…", "date": "2026-02-10",
 "fiscal_year": 2026, "period": 1, "sign": "转", "no": 9}

成功 {"ok":true,"period","sign","no","fiscal_year","voucher_date","lines","out_no","reversal_of":{"fiscal_year","period","sign","no","out_no","out_no_assigned"}}：顶层是红字凭证（期间取 voucher_date 的月份，类别同原凭证，号由 U8 编），reversal_of 是原凭证。红字凭证未审核、未记账，之后照常审核、记账，也可以作废后删除，不能修改。

• 复制：科目，部门、人员、客户、供应商、项目辅助核算，结算方式、票号、票据日期、币种、汇率，原始单据类型和单号、业务员，表头备注、外部业务类型，附单据数。取负：本币借贷、原币、数量（单价仍为正）、现金流量金额（项目不变）。原币只在汇率大于 0 时写，取原凭证原币的负数，不按汇率重算。
• 摘要：[冲销yyyy.MM.dd 类别-NNNN号凭证] 加原摘要（日期是原凭证的制单日期，凭证号补到至少 4 位），最长 120 字，超出截断。例如 [冲销2026.01.31 转-0009号凭证]。
• 关联：红字凭证的 cblueoutno_id 写原凭证的外部业务号 coutno_id（load 的 blue_out_no 与 out_no）。原凭证没有外部业务号时（例如经凭证导入生成的）先按 U8 的编号规则补一个，out_no_assigned: true；原凭证所在期间已结账时照样补写（只是关联标识，不改金额）。
• 门槛（409 state_mismatch，原凭证不存在 404）：原凭证已记账、未作废、各行状态一致、是总账自己的凭证、至少 2 行；没有被冲销过（本接口只做整张、一次冲销）；本身不是红字冲销凭证；不带自定义项；每行数量与金额同方向；外币行汇率不为 0（有原币而汇率为 0 时请在 U8 客户端冲销）；科目和辅助核算在红字凭证的年度仍合格；红字凭证所在期间未结账；「制单序时」打开时日期不早于本期同类别最后一张凭证。U8 导入拒绝时 409 u8_rejected，库里没有改动。
• 执行：读原凭证（加锁）、检查、拼分录 → 凭证导入组件保存（U8 自己提交）→ 一个事务里取号、写关联、补现金流量的类别 → 新连接上逐行回读核对。保存之后任何一步失败都是 504 outcome_unknown（消息写明红字凭证可能已保存及其期间、类别）：先 load 或 list 核对，不要直接重发，因为没写上关联的红字凭证桥识别不出来。
• 预演是 validate 模式：detail.voucher 给出红字凭证的分录和预取的外部业务号（随回滚撤销，实际冲销会重新取号）。与同类别 create 互斥、与记账互斥（gl:post）。写入策略里归 (gl, create)。

unpost（取消记账，第二级写入）#

相当于 U8「恢复记账前状态 → 最近一次记账」：把本年度最近一次记账（桥记的和 U8 客户端记的都算）整批恢复为未记账，不能挑单张凭证。

请求全部可选：fiscal_year（缺省登录日期的年份）、period、vouchers（[{sign, no}]，不重复，最多 200 张，给了就必须给 period）。period、vouchers 只用来核对：给了就必须与最近一次记账的期间、凭证集合完全一致，否则 409 并写明不一致之处，什么都不改。成功 {"ok":true,"fiscal_year","period","count","vouchers":[{"sign","no"}]}。

• 门槛（409，消息带首张命中的凭证）：本年度有可恢复的记账（本年还没记过账或最近一次已恢复时 409）；范围不跨期间、不超过 500 张；该期间和后续期间总账都未结账；范围里的凭证都还在、都已记账；没有做银行对账、往来两清或往来对账；没有被红字冲销；U8 界面没有锁着。
• 执行（一个事务，锁同记账）：按 U8 记账的公式把这批凭证的发生额从科目总账（本期和后续期间的余额）、辅助总账、多辅助总账里冲回 → 凭证改回未记账 → 自检：科目总账发生额与已记账凭证按科目重算一致、本期起余额首尾相接、辅助总账一致，不符 409 并回滚 → 清掉本年度的恢复范围 → 提交 → 新连接上回读，不符 504 outcome_unknown。
• 记账时新增的总账、辅助账行（新科目、币种或辅助组合）只改回零、不删除，余额不受影响。依赖这批凭证的期间损益结转凭证不检查。
• 功能权限按记账 GL0208 查（U8 的恢复记账没有单独的功能 id）。预演是 rollback 模式，detail.unpost 给出期间、凭证和张数。写入策略里归 (gl, other)：放行 post 不连带放行取消记账。

期间损益结转、自定义转账（gl/transfer/pnl、gl/transfer/custom，第二级写入）#

相当于 U8 总账「期末 → 转账生成」的期间损益结转和自定义转账。桥按 U8 的转账定义和已记账余额算出分录，经与 create 相同的凭证导入保存，再按 U8 生成的结转凭证补标记。

请求：fiscal_year（必填，必须是登录日期 date 的年份）、period（1 到 12）；可选 voucher_date（缺省该期间最后一天，必须在该期间内）、exclude_existing（只能和 dry_run 一起用，见下）；自定义转账另有可选 tran_id（U8 的转账序号，如 T001，缺省生成全部定义）。例：

{"acc": "801", "operator": "op001", "password": "…", "date": "2026-09-30", "fiscal_year": 2026, "period": 9}

成功 {"ok":true,"kind","fiscal_year","period","voucher_date","out_sign","count","vouchers":[{"sign","period","no","lines","out_no","digest","debit","credit","pack"|"tran_id"}],"skipped":[{"tran_id","account","reason"}]}。

• 期间损益：每个转账序号两行定义（第 1 行损益科目、第 2 行本年利润科目）。损益类末级科目（带辅助核算的按辅助项分行）已记账期末余额非零的，反向结平，差额转入本年利润；贷方性质的科目（收入，pack: income）一张凭证、本年利润在最后一行贷方，借方性质的（费用，pack: expense）一张、本年利润在第一行借方；余额在反方向的写成同一边的负数；正负相抵为 0 时不写本年利润行。摘要「期间损益结转」，类别取定义上的类别。定义不完整、科目不存在或不是末级、本年利润科目带辅助核算的跳过（skipped）。
• 自定义转账：每个转账序号一张凭证，行的科目、方向取定义，金额按公式算，摘要取定义（没有时取转账说明）。公式支持 QM(科目, 月|年, [借|贷], [辅助项])、CE()、数字、+ - * / 和括号：QM 取该科目（含下级，可以不是本行科目）已记账的期末余额，不给方向时按科目余额方向取净额，给「借」「贷」只取该方向的余额；给辅助项时该科目必须是只核算一种辅助项的末级科目；CE() 是本凭证其余各行的借贷差额。QM 的期间参数只支持 月：用到 年 的定义在给了 tran_id 时 400 bad_request「转账定义 <序号> 用到按年取数（QM(…,年,…)），暂不支持，请在 U8 客户端生成」，不给时跳过并在 skipped 写明。其他函数（FS、JE、QC、LFS 等）400 bad_request，消息写明函数名。行的辅助项取定义上固定的辅助项，没有时取本行公式里唯一带辅助项的 QM 的辅助项（类型须与本行科目相同），给不全的跳过。金额为 0 的行不写；全为 0、按年取数、科目不合格、本期已生成的定义跳过。
• 门槛（409 state_mismatch）：
  • 该期间总账未结账；本期没有未作废的未记账凭证（结转只取已记账余额，同 U8）。
  • 期间损益本期已有未作废的结转凭证时 409「该月已经做过期间损益结转」。例外：已有凭证能按损益科目性质认出是收入还是费用，且已记账后重新算出的只有缺的那一类，则照常生成，响应和预演另给 existing: [{"sign","no","pack"}]。
  • 不给 tran_id 而后面定义 QM 取数的科目（含下级）与前面定义本次生成的分录科目重叠时 409（U8 按序号逐个结转、后一个在前一个记账之后取数；请用 tran_id 逐个生成、审核、记账；核对模式不查）。
  • 自定义转账同期已有外部业务类型「自定义转账」、摘要相同的未作废凭证时跳过该定义（给了 tran_id 时 409）；全部跳过时 409「没有生成凭证：…」并列出原因。
  • 每张凭证借贷平衡、不超过 500 行，科目和辅助核算按 create 的规则查；制单序时。
• 标记（同 U8 生成的结转凭证）：coutsign 为「期间损益」或「自定义转账」，coutno_id 按 U8 的编号规则取，附单据数 idoc=-1，coutsysname 为空，ioutyear 为空、ioutperiod 为期间、doutbilldate 为凭证日期。凭证未审核、未记账，之后照常审核、记账；要重做时作废、删除后再生成。
• 执行：逐张保存（U8 自己提交）→ 每张在一个事务里取号、补标记、补现金流量类别 → 全部保存后新连接上逐行回读。第一张被 U8 拒绝时 409 u8_rejected，库里没有改动；之后任何失败（含第二张被拒）都是 504 outcome_unknown，消息列出已保存的凭证和补救办法，先 list 核对。期间损益只存了一张时，把它审核、记账后再调用 gl/transfer/pnl，桥只补生成缺的那张；已保存的凭证没补上标记时作废、删除后整体重做。
• 预演是 validate 模式：停在凭证导入之前，detail.transfer 给出 vouchers（每张的类别、摘要、借贷合计、lines）和 skipped。exclude_existing: true（核对模式）：余额里去掉本期已生成的同类结转凭证及同类别、凭证号在它之后的结转凭证，不查结账、未记账、重复三道门槛，用来与 U8 已生成的凭证逐行核对，去掉的凭证在 detail.transfer.excluded。exclude_existing 只能预演：登录前按 dry_run 查，入队后按实际的预演状态再查，保存前再查一次。
• 数据权限：口径同总账查询。科目（总账选项「明细账查询权限控制到科目」打开时）、部门、人员、客户、供应商、项目的数据权限开着时，定义里取数和入账的每个科目、QM 的辅助项参数、每条取数余额和每行分录都要有查询权限，否则 403 no_permission（消息不带金额）。定义里的科目在取数之前查，其余在算出之后查，预演和核对模式相同。账套主管、该对象的数据权限管理员不受限。
• 锁：同年同期的两种结转互斥（gl:transfer:<年>-<期>），与记账和取消记账（gl:post）、总账结账（period:gl）、常见类别的新凭证编号（new:gl:转 等）互斥。写入策略里归 (gl, voucher)：放行 create 不连带放行自动转账。
• 不支持：对应结转、销售成本结转、汇兑损益结转、修改转账定义、自动审核记账。

load / list#

load 返回 voucher（period、sign、no、date、attachments、maker、checker、audit_date、cashier、poster、posted、void、error、source_system、source_sign、source_no、out_no、blue_out_no（红字冲销凭证指向的原凭证外部业务号））和 lines（entry、account、account_name、digest、debit、credit、debit_fc、credit_fc、qty_debit、qty_credit、currency、rate、dept、person、customer、supplier、item_class、item、settle、doc_no、doc_date、cash_flow）。

list 请求：period_from、period_to 必填，可选 sign、date_from、date_to、maker、state（all、unaudited、audited、posted、void）、after（上一页的 next，不透明字符串）、limit（1 到 200，缺省 50）。按（期间、类别、凭证号）翻页。每项 period、sign、no、date、maker、checker、cashier、posted、void、debit_total、lines（分录数）。

数据权限：总账选项「明细账查询权限控制到科目」打开、科目开了数据权限控制、操作员不是账套主管也不是科目的数据权限管理员时，load、list、digest、attachments/list 按整张凭证过滤：全部分录科目都有查询权限才可见（取较严的口径）。list、digest 里越权的凭证不出现（debit_total、watermark 只算可见凭证），load、attachments/list 403 no_permission「没有该单据的数据权限」，凭证不存在仍是 404。见 §22。

digest（凭证摘要）#

供事件服务使用。凭证表没有 rowversion，事件服务按期间逐张比对凭证指纹，发现新增、删除、审核、出纳签字、记账、作废和修改。走读线程池（只跑 SQL），权限同凭证查询（含按科目整张过滤：事件服务的操作员看不到的凭证不产生事件）。

请求全部可选：fiscal_year（缺省登录日期的年份）、periods（1 到 12 个不重复的期间）、closed_periods（0 到 12，缺省 1，不能与 periods 同时给）、after、limit（1 到 500，缺省 200）、keys_only。periods 省略时取该年度全部未结账期间（不含期初 0 期），再加最近 closed_periods 个已结账期间；年度没有期间记录时 periods、items 为空。缺省期间只在这一年度里取：上一年度未结账的期间和跨年度的最近已结账期间要另发请求，显式给 fiscal_year 和 periods。

响应 {"ok":true,"fiscal_year","periods","items","next","watermark","ident"}：periods 是实际扫描的期间（升序），翻页时原样放进下一页的 periods，避免翻页途中结账改变范围；watermark 是所扫期间的 MAX(i_id)，ident 是 IDENT_CURRENT('GL_accvouch')（删凭证不回退），都在读这一页之前取，十进制字符串。每项 period、sign、no、fingerprint；不带 keys_only 时另有 date、maker、checker、cashier、bookkeeper（记账人）、posted、void、debit_total、lines。fingerprint 是 SUM(md)、SUM(mc)（4 位小数）、行数、MAX(i_id)、制单人、审核人、出纳、记账人、ibook、iflag 以 | 连接后的 SHA-256（小写十六进制）。按（期间、类别序号、凭证号）翻页，after 同 list。

attachments/list#

请求同 load（period、sign、no，年度取登录日期的年份），权限同凭证读取。凭证不存在 404 not_found。

凭证的 attachments 只是附单据数；电子附件（U8 填制凭证界面的「附件」）登记在 GL_AccAttachs，文件在 U8 文件服务器上。响应 {"ok":true,"voucher","items","truncated"}：voucher 是 period、sign、no、attachments；每项 id、name（原文件名）、file_id（文件服务器上的标识）、submitted_at（yyyy-MM-dd HH:mm:ss）、source（来源模块）。按上传顺序，最多 500 个。只列清单，不提供下载；没有附件时为空数组。

客户端命令：gl-attachments --period 9 --sign 转 --no 3。

15. 基础档案 archives/*#

登录子系统 AS。archive 为 customer、vendor、inventory、department、person、warehouse、customer_class、vendor_class、inventory_class（下称「九类可写档案」），以及下文各节的档案，其他 400「未知档案类型 x」。code 1 到 30 个字符（其他档案按下表的长度），不含控制字符，前后没有空格（中间可以有空格）。code_prefix 最长与该档案的编码相同，name_like 1 到 60 个字符，都不含控制字符。

九类可写档案的 fields 键是 U8 EAI 的标签名（不分大小写，发送时换成 U8 对照表的写法），值是字符串、数字或布尔，null 表示不发送。未知标签 400「未知字段 x」；code、建档/变更人和日期、统计类标签（例如客户的应收余额、最后交易日）400「不能设置字段 x」。

• get 返回对照表里有对应列的全部标签的当前值，包括银行账号、联系方式。按需给调用方授只读权限。
• list 按编码翻页，after 是上一页最后的编码，limit 1 到 500（缺省 100），changed_since 见 §16「翻页和增量」。
• keys_only: true（只收布尔，任何档案都可用）时每项只有 code、ufts，整轮的编码集合用来发现被删的档案。
• customer、vendor、warehouse、department、person、inventory 的整行另有 end_date（停用日期 yyyy-mm-dd）和 disabled（已填停用日期即为 true，不与当天比较）；未填时桥给 null，API 省略。
• 选择器标志（整行才有，keys_only 不给；列值为空按 false）：warehouse 的 bin_managed（启用货位管理）；position 的 leaf（末级货位，class_code 是所属仓库）；inventory 的 batch_managed（批次管理）、shelf_life_managed（保质期管理）。这些键不影响事件服务的档案指纹（只看名称、分类、停用状态和停用日期）。
• 新增必须有 name；存货新增必须带 template（已有存货编码，桥按它铺满其余标签），其他档案可选。编码已存在 409「档案编码已存在」。客户、供应商要给税号类必填项，缺了由 U8 报错。
• 修改至少一个字段，不能改编码。桥发整条记录（当前值打底，再用 fields 覆盖），因为 U8 修改时按档案设置检查全部必输项。
• 删除：已被单据使用的档案由 U8 拒绝，409 u8_rejected。

经 EAI 的写操作由 U8 自己提交。U8 拒绝时 409 u8_rejected，message 是 U8 原文；原文含「不可为空」时后面加「（U8 档案设置为必输）」，调用方要在 fields 里给出该字段。U8 说成功但回读对不上，或应答无法识别，504 outcome_unknown。EAI 对照文件读不到或格式不对 503 u8_unavailable。

其他档案的写入能力：

只读档案#

以下档案的读取不用 EAI 对照表：get 的 fields 键是 U8 表的列名，返回全部非空列，去掉口令类列（列名含 password 或 pwd）和原始 rowversion；有 rowversion 的表另带十进制 ufts。exchange_rate、fa_card、operator、role 例外，见下文。

• 没有 rowversion 的档案（voucher_sign、project、customer_address、fa_card、operator、role）列表的 ufts、watermark 为 null，带 changed_since 400；需要增量时整轮重读。
• account：科目按年度存，读登录日期那一年的科目，响应带 fiscal_year。
• bank：返回银行账号等付款要用的列，按需授只读权限。
• project：大类取自 fitem，只认 ctable 恰好是 fitemss<大类> 且表存在的大类；借用其他档案的大类（如存货核算）不在其中，用对应的档案读。大类 1 到 2 位字母数字，项目编码 1 到 60 个字符（code、code_prefix 整串最长 63）。get 另带 project_class；大类不存在 404「项目大类不存在」。list 可选 project_class 只列一个大类，省略时列全部大类（超过 100 个大类时 400，请按大类分别列），按整串编码排序翻页，code_prefix 也按整串匹配（例如 98:）。每项另带 project_class 和 closed（项目已关闭）。
• 两段编码的档案（customer_address、user_define、customer_inventory）：code 写成 <第一段>:<第二段>，按第一个冒号拆开（第一段不含冒号，第二段可以含），两段长度按上表、前后没有空格，否则 400。list 按（第一段，第二段）排序，next / after 是整串编码；code_prefix 按整串匹配，例如 C900001: 只列这个客户的收货地址；class_code 是第一段。已知限制：某一段本身带前导或尾随空格的记录仍出现在 list 里（编码原样带空格），但 get 取不到（400）；若它是一页的最后一行，下一页请求会 400，这时用 code_prefix 或 name_like 缩小范围跳过它。
• user_define：name 就是档案值 cValue，别名、上级值等在 fields 里。
• customer_inventory：U8 的唯一索引是（客户、存货、客户存货编码），同一客户同一存货可以有几条客户存货编码不同的对照，而 API 的编码只有两段：有重复时 get 只返回其中一条，list 都列出但编码相同，恰好落在页边界时下一页会跳过同编码的另一条。见「货位、计量单位等 EAI 档案的写入」的已知限制。
• position：class_code 是所属仓库。货位本身的数据权限不展开，也不按仓库的数据权限过滤。
• exchange_rate：U8 的 exch 一行一个汇率，itype 2 是记账汇率（固定汇率，按月），3 是调整汇率（按月，期末调汇用），1 是浮动汇率（按日，cdate 是日期，存成 yyyy-mm-dd）。桥把同一（币种、年度、期间、日）的行并成一项：currency、year、period（月份）、day（浮动汇率的 cdate 原文，固定汇率为 null）、rate（记账汇率或当日浮动汇率）、adjust_rate（调整汇率，未录入为 null）、mode（fixed / floating），name 是币种名称；get 的 fields 也是这几项加 code。list 可选 currency（币种名称，1 到 8 个字符）和 fiscal_year（四位年度，缺省登录日期的年份），按（币种、期间、日）排序，after 必须是本年度列表的 next；name_like 按币种名称匹配，code_prefix 按整串编码。响应另带 fiscal_year 和 rate_mode（账套的汇率方式：fixed 或 floating）。
• exchange_rate 按日期读取（<币种>:<yyyy-mm-dd>）返回 U8 给该日期单据带出的汇率：固定汇率取日期所在年月的记账汇率（期间按自然月换算；会计期间不按自然月划分的账套，月初月末可能落到相邻期间，请以 U8 单据带出的汇率为准），浮动汇率取当日汇率（当日没有 404「该日期没有汇率」，不向前找）；响应另带 rate_mode，fields.code 是命中项的编码。单据上的汇率可能从来源单据带出或被手工修改，以单据为准。外币付款先用它取汇率，再把 rate 作为单据的汇率。
• fa_card：get 的 fields 与 list 的每一项相同，不是表列名：code（卡片编号）、name（资产名称）、asset_num（资产编号）、spec（规格型号）、type_code / type_name（资产类别）、status_code / status（使用状况）、origin_code / origin（增加方式）、depreciation_method_code / depreciation_method（折旧方法）、start_date（开始使用日期）、entry_date（录入日期）、useful_life_months（使用年限，月）、used_months（已使用月份）、original_value（原值）、accumulated_depreciation（累计折旧）、impairment（减值准备）、net_value（净值 = 原值 − 累计折旧 − 减值准备）、net_salvage（净残值）、disposed / disposed_date / disposal_code / disposal_way（已减少、减少日期、减少方式）、keeper（保管人）、location（存放地点）、depts（使用部门 [{"code","name","ratio"}]，单部门卡片 ratio 是 1）。金额保留两位小数。
• fa_card 的口径：U8 每次变动、减少都新增一个卡片版本。桥取截至日（登录日期所在月的月末）当时的版本，即录入、变动、减少日期都不晚于截至日的最后一个版本，同 U8 卡片查询；截至日还没录入的卡片 404。累计折旧取登录年度「已计提期间」期末的累计值（已计提期间是该年度不晚于登录月份的最大计提期间）；本年还没计提时取年初数（本年录入的卡片取录入时的累计折旧）；已减少的卡片取减少时的累计折旧；登录年度固定资产还没建账时为 null。响应另带 fiscal_year、as_of（截至日）和 depr_period（所取的已计提期间，本年还没计提为 null）。会计期间不按自然月划分的账套、多部门卡片 ratio 的口径未覆盖。
• fa_card 的 list 按卡片编号排序，缺省只列在役卡片，include_disposed: true 连已减少的一起列。type_code（1 到 20 个字符）按类别编码前缀匹配，含下级类别；dept_code（1 到 12 个字符）是使用部门之一；name_like 按资产名称匹配。get 对已减少的卡片照常返回（disposed 为 true）。
• operator、role：数据在 U8 系统库，桥用三段名 UFSYSTEM..UA_User、UA_Group、UA_Role、UA_HoldAuth 读取，比较编码时按账套库的排序规则。只列本账套有授权的：操作员本人或所属角色在本账套、请求年度或建账年度（年度窗口同 §22）有任一授权；角色本身有这样的授权。系统管理员（admin）不列。不在范围内的编码 get 404。get 的 fields 与 list 的每一项相同。操作员：code、name、dept（操作员档案上的所属部门，文本原样）、state（nState 原值，0 正常、1 停用）、disabled（nState 不是 0）、roles（所属角色编码，只含本账套有授权的角色）、person_code / person_name（关联的人员，与登录对象的 cEmployeeId、审批任务的人员是同一编码；没有关联为 null）。角色：code、name、members（成员操作员编码，系统管理员除外）。口令、口令日期、邮箱、手机、系统用户名等列不读。name_like 按姓名或角色名称匹配。

读取权限与数据权限（§22）：