金蝶云星空销售订单附件查询接口权威教程(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 中追加区间条件。

典型字段映射

字段名	类型	含义	实战注意事项
FID	string	附件主键,metadata 中 id 与 number 均指此	跨系统唯一关联键,务必存入 OA 附件表的自定义主键
FInterID	string	关联销售订单的主表内码	FilterString 入参,先从销售订单接口拿到
FBillType	string	单据类型编码	销售订单对应 SAL_SaleOrder,不同业务对象不可混用
FBillNo	string	关联销售订单编号	人工核对用,与 OA 流程单号映射
FAttachmentName	string	原始文件名	包含扩展名,可直接用于 OA 端展示与下载
FaliasFileName	string	别名/显示名	可与原始名不同,展示时优先用
FExtName	string	文件扩展名	用于 OA 端图标与类型判断
FAttachmentSize	string	大小(KB)	单位是 KB,OA 端展示时记得换算
FFileStorage	string	存储位置	数据库 或 文件服务器,决定下载走哪条路径
FFileId	string	文件服务器文件标识	文件服务器模式下下载的核心字段
FAttachment	string	数据库存储的附件引用	数据库存储模式下,二进制内容从此取
FIsAllowDownLoad	string	是否禁止下载	落到 OA 权限控制,禁止时按钮置灰
FThumbnailId	string	缩略图编码	图片类附件可在 OA 端做缩略图预览
FCreateTime / FModifyTime	string	创建/修改时间	增量同步的时间锚点
FCreateMen / FModifyMen	string	创建人/修改人	与 OA 用户体系映射时注意编码差异
FBillStatus	string	单据状态	OA 端可据此控制附件可见性(未审核不外发)
FSourceId	string	来源内码	追溯附件源头(如从某条明细行上传)

在轻易云上如何配置

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

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 后才彻底解决。