Authoritative Tutorial on the Kingdee Cloud Sales Order Attachment Query API (BOS_Attachment)

What Problem This API Solves

In supply chain integration between Weaver OA-E9Http and Kingdee Cloud, sales orders typically come with contracts, quotations, signed receipts, and other attachments. These attachments live in Kingdee by default, yet approvals happen in OA—approvers need to view and click through them, and finance needs a unified archive. By pulling attachment metadata via the BOS_Attachment query API into OA, you get traceable approvals, single-source storage, and cross-system visibility.

API Capability Overview

• Authentication: For on-prem Kingdee Cloud, OAuth2 / tenant credentials are exchanged for a token; all calls must carry a Bearer Token in headers.
• Request Structure: HTTP POST; the body follows Kingdee's generic query convention.
  • FormId: BOS_Attachment
  • FieldKeys: a curated field set such as FID, FInterID, FAttachmentName, FFileId, FFileStorage, ...
  • FilterString: FInterID='{Id}' and FBillType='{FFormId}' (sales order FormId is typically SAL_SaleOrder)
  • Limit (page size, default 100), StartRow (starting row, default 0), TopRowCount (cap on rows returned)
• Response Structure: a two-dimensional array; each row is an attachment, the first row is the column header; non-query fields ride on otherResponse.
• Pagination & Incremental: Generic query pages with StartRow + Limit; for incremental pulls, append a FCreateTime or FModifyTime window to FilterString.

Typical Field Mapping

How to Configure It on Qeasy (Qingyi Cloud)

In the Qeasy Data Integration Platform, Kingdee Cloud is wrapped as the "Kingdee Adapter". A typical rollout looks like this:

1. Datasource Setup: Pick the Kingdee Cloud on-prem adapter, fill in tenant URL, tenant ID, third-party account, Secret, etc. Qeasy auto-manages the token lifecycle.
2. API Selector: Search executeBillQuery, set FormId to BOS_Attachment, method POST. The platform ships a generic query template.
3. Field Mapper: In Qeasy's field mapper, drag fields from the table above into target outputs—FID → OA attachment PK by default; FAttachmentName → attachment name; FFileStorage and FFileId drive the download branch.
4. Filter Conditions: Express the filter with placeholders, e.g., FInterID='${SalesOrder.FInterID}' and FBillType='${SalesOrder.FFormId}', feeding upstream sales order results in as inputs.
5. Pagination & Throttling: Qeasy pages with Limit/StartRow automatically and ships rate-limit guards to avoid overloading Kingdee.
6. Download Branch: When FFileStorage is FileServer and FIsAllowDownLoad is false, Qeasy's download handler skips that row; otherwise it calls Kingdee's attachment download endpoint using FFileId and pushes the binary stream into the OA attachment service.
7. Target Configuration: This strategy writes a "no-op" target—it's pure query mode, persisting only metadata to Qeasy's transit store or forwarding it downstream.

Cross-Scenario Practical Tips

1. FInterID must be ready first: BOS_Attachment is a child table with no business meaning on its own—you need the sales order ID first. This is a classic "header-then-line" chained query pattern.
2. FBillType is mandatory: Omitting or mis-typing it pulls attachments from unrelated business objects, causing data pollution—the most common pitfall on this API.
3. Storage mode drives the download path: Database → FAttachment; FileServer → FFileId. Build a conditional branch in the mapper, or downloads will 404.
4. FID is the stable correlation key: OID and number can be empty for legacy data; FID is the most reliable cross-system PK.
5. Use FModifyTime for incremental sync: Attachments can be uploaded after the fact; using FCreateTime will miss them. A rolling window on FModifyTime is safer.
6. Mind large files and QPS: Don't crank up Limit too high (100 is reasonable), and respect the on-prem Kingdee instance's QPS ceiling—Qeasy's rate-limit policy is worth enabling.

Pitfall Review

1. Forgot FBillType in FilterString: Filtering only by FInterID='{Id}' pulled attachments of every type linked to that order, producing duplicates or mismatches in OA.
2. FAttachmentSize unit confusion: Kingdee uses KB, OA defaults to bytes—a 1 MB file displayed as 1 KB misled approvers into thinking the wrong file was attached.
3. Force-downloading when FFileId is empty: In FileServer mode, some legacy attachments have an empty FFileId. Skipping a null check caused a 500 from Kingdee that failed the whole batch. Best practice: only download when both FFileStorage and FFileId are valid.
4. Wrong sales order FormId: A customer accidentally used a downstream doc's FormId, so FilterString returned an empty set with no error—hard to spot until you trace the input.
5. Wrong incremental anchor: Syncing on FCreateTime missed attachments uploaded after the approval step; switching to FModifyTime solved it.

When to Use It

Apply when OA must be integrated with on-prem Kingdee Cloud and approval flows or portals need to view/download ERP attachments. Not suitable for: plain text-only scenarios without attachment needs, or cases where Kingdee attachments have fully migrated to object storage and no longer pass through BOS_Attachment—direct object-storage integration is cheaper there.