金蝶云星空销售订单附件查询接口权威教程(BOS_Attachment)

这个接口解决什么问题

在泛微 OA-E9Http 与金蝶云星空的供应链集成场景里,销售订单常常伴随合同、报价单、签收单等附件。这些附件默认存放在金蝶端,审批环节却发生在 OA——审批人需要看到附件、点击查看,财务归档也需要统一入口。通过 BOS_Attachment 查询接口把附件元数据拉到 OA,可以做到审批有据可查、附件一处存放、两边可追溯。

接口能力总览

• 认证方式:金蝶云星空私有化部署通常采用 OAuth2/账套凭据登录换取 token,所有接口调用需在 Header 携带 Bearer Token。
• 请求结构:HTTP POST,请求体遵循金蝶通用查询接口规范。
  • FormId:BOS_Attachment
  • FieldKeys:按需返回的字段集合,如 FID,FInterID,FAttachmentName,FFileId,FFileStorage,...
  • FilterString:FInterID='{Id}' and FBillType='{FFormId}'(销售订单 FormId 通常为 SAL_SaleOrder)
  • Limit(每页大小,默认 100)、StartRow(起始行,默认 0)、TopRowCount(本次返回上限)
• 响应结构:返回二维数组,每行对应一条附件记录,首行为列名;非查询字段通过 otherResponse 传递。
• 分页与增量:金蝶通用查询本身靠 StartRow + Limit 翻页;若需增量,可基于 FCreateTime 或 FModifyTime 在 FilterString 中追加区间条件。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,金蝶云星空被封装为「金蝶适配器」,通常这样落地该策略:

1. 数据源配置:选择金蝶云星空私有化适配器,填入账套地址、账套 ID、第三方系统账号、Secret 等认证信息,轻易云会自动维护 token 生命周期。
2. API 选择器:检索 executeBillQuery,FormId 填 BOS_Attachment,请求方法 POST,平台已预置通用查询参数模板。
3. 字段映射器:在轻易云字段映射器里,把上面表格中的字段拖到目标输出字段;FID 默认映射到 OA 附件主键,FAttachmentName 映射到附件名称,FFileStorage、FFileId 等用于驱动下载分支。
4. 过滤条件:FilterString 用轻易云的占位符表达,例如 FInterID='${SalesOrder.FInterID}' and FBillType='${SalesOrder.FFormId}',把上游销售订单查询的结果作为入参注入。
5. 翻页与限流:平台会根据 Limit/StartRow 自动翻页,内置限流保护避免压垮金蝶服务。
6. 下载分支:当 FFileStorage 为文件服务器且 FIsAllowDownLoad 为 false 时,轻易云的下载处理器会跳过该条;否则按 FFileId 调用金蝶附件下载接口,把二进制流推送至 OA 附件服务。
7. 目标配置:本策略 Target 写「空操作」,即为纯查询模式,只把元数据落到轻易云中转存储或直接转发给下游策略。

跨方案实战要点

1. FInterID 必须先到位:BOS_Attachment 是从表,本身没有业务意义,必须先有销售订单内码,这是典型的「先头后行」联动查询模式。
2. FBillType 是必传项:不传或传错会导致把其他业务对象的附件一并拉过来,数据污染是这条接口最容易翻车的地方。
3. 存储模式决定下载路径:数据库存储走 FAttachment,文件服务器存储走 FFileId,集成时务必在映射器里做条件分支,否则下载大概率 404。
4. FID 作为稳定关联键:OID、number 都不可靠(老数据可能为空),跨系统以 FID 为主键最稳。
5. 增量同步用 FModifyTime:附件可能后补上传,按创建时间增量会漏,稳妥做法是按 FModifyTime 滚动窗口。
6. 大附件与限流:Limit 不宜过大(默认 100 合理),并发拉取时注意金蝶私有化实例的 QPS 上限,轻易云的限流策略可以打开。

踩坑复盘

1. FilterString 忘了 FBillType:只传 FInterID='{Id}',结果把同一张销售订单关联的全部业务对象附件都拉了回来,OA 端出现重复或错乱附件。
2. FAttachmentSize 单位混淆:金蝶是 KB,OA 默认按字节,导致一个 1MB 文件显示成 1KB,审批人误以为传错文件。
3. FFileId 为空却强行下载:文件服务器模式下,某些历史附件 FFileId 为空,程序未做容错直接调用下载接口,金蝶返回 500 引发整批失败。稳妥做法是先判断 FFileStorage 与 FFileId 同时有效再下载。
4. SalesOrder FormId 写错:某客户把销售订单 FormId 误写成下游单据 FormId,FilterString 等于过滤出空集,但接口不报错,排查半天才发现。
5. 增量锚点选错字段:用 FCreateTime 做增量,审批流后补的附件同步不到 OA,改用 FModifyTime 后才彻底解决。

何时选用

适用于 OA 与金蝶云星空私有化部署、需要在审批流或门户中查看/下载 ERP 附件的场景。不适用:只需要单据文本字段、无附件需求,或金蝶端附件存储完全迁移到对象存储、且不再经由 BOS_Attachment 管理的场景——后者直接对接对象存储更划算。