金蝶云星空销售订单附件查询接口权威教程(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 后才彻底解决。
相关推荐
特立独行的猫A13 小时前
别再用 nohup 了:让应用在后台常驻的正确姿势与 systemd 服务详解
java·后端·python
民乐团扒谱机14 小时前
Rakazo 智能清洁机器人深度评测报告
机器人
feasibility.14 小时前
英伟达把物理AI的3D模型“应用商店”开放了:2575个SimReady仿真资产,总计约472GB,可让agent装配机器人训练场景
人工智能·3d·机器人·仿真·建模·具身智能·英伟达
吃我一窝jio16 小时前
Python与Go线程模型深度对比
java·开发语言·python
zwd200516 小时前
Manim 怎么放大画面的某一部分?
python·动画·可视化·manim·数学动画
屿华AI17 小时前
AUTOSAR 实战-诊断工具 | UDS 0x27 安全访问的配置化实现:种子密钥算法插件化设计
python·测试工具·汽车
RobinDevNotes17 小时前
Claude Code 剪视频,不上传、不要 API Key
人工智能·python·音视频·开发工具·ipython
如夏倾城19 小时前
VRRP(虚拟路由器冗余协议Virtual Router Redundancy Protocol)
网络·python·网络协议·安全·智能路由器·负载均衡·信息与通信
wangxiaoxuan21719 小时前
机器人软件如何分层:驱动、算法、能力、动作与业务
机器人·科沃斯八界
IvanCodes19 小时前
LangChain(04):Runnable 与 LCEL 的执行与组合机制
python·langchain·agent