Authoritative Tutorial on Jushuitan Qimen Sales Outbound Order API Field Handbook
What This API Solves
The Jushuitan Qimen Sales Outbound Order API serves as the bridge between e-commerce ERP and traditional ERP for order data flow. Across multiple retail supply chain integration projects, we use it to sync outbound orders from Taobao, Tmall, and JD channels into Kingdee Cloud Cosmos sales orders, automatically generating ERP sales orders from online outbounds, completing financial accounting and inventory linkage, and avoiding manual dual entry.
API Capabilities Overview
- Authentication: Jushuitan Qimen uses AppKey + AppSecret + platform identifier signature auth, exchanging an authorization code for an access_token; the request header carries the token and platform code.
- Request Structure: POST JSON body, with core parameters
modified_begin/modified_end(incremental time window),page_index/page_size(pagination),shop_id(shop filter). - Response Structure: Outer
datasarray, inner document object containing header fields anditemsdetail line array;has_next/page_indexindicate pagination status;modifiedis an ISO timestamp. - Pagination/Incremental Pattern: Incremental pull based on the
modifiedfield +page_sizepagination (recommended 50); full backfill on initial deployment before switching to incremental.
Typical Field Mapping
| Field Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| io_id | string | Outbound order number | Must prefix XSDD as Kingdee FBillNo to avoid conflict with other ERP documents |
| io_date | date | Outbound date | Direct map to Kingdee FDate; note GMT+8 timezone |
| shop_id | string | Shop code | Convert to FCustId via shop-to-customer mapping table; cannot write directly |
| o_id | string | Platform internal order | Write to FNote for traceability |
| items[].sku_id | string | SKU code | Convert to FMaterialId via material mapping; style products map by SKU not style code |
| items[].qty | number | Outbound quantity | Direct map to FQty |
| items[].sale_amount_new | number | Allocated amount | Must allocate discounts and shipping by ratio via AfterSourceInvoke hook script |
| node+order_type | string | Document type branch | Fee/normal/resend/exchange branches determine FBillTypeID |
| modified | datetime | Modification time | Incremental cursor, second precision; initial pull recommend 7-day backtrack |
How to Configure on Qeasy
On the Qeasy Data Integration Platform, this API is encapsulated as the "Jushuitan Qimen Adapter". Simply configure AppKey, AppSecret, and platform authorization code to enable; the token auto-refreshes.
The platform's field mapper automatically recognizes the Jushuitan response structure, binding the header and detail lines via the items array, supporting constant (Sales Org FSaleOrgId=7000, Receipt Condition FRecConditionId=09), direct mapping, and script conversion rules. The amount allocation script can be hung directly on the AfterSourceInvoke hook, and the platform provides a sandbox debugger for real-time replay. Incremental scheduling advances based on the modified cursor, and failed records automatically enter the dead-letter queue.
Cross-Scenario Practical Points
- Master Data First: Material, shop-to-customer, and warehouse mapping tables must be fully written into the Qeasy hub first, otherwise sales orders and inventory policies will fail at scale due to missing codes.
- Incremental Cursor Precision:
modifiedmust follow server-side returned values, not local timestamps; cross-day scheduling should add a 2-minute overlap window to prevent boundary data loss. - Amount Allocation Cannot Be Skipped: Jushuitan discounts and shipping are at document level, while Kingdee requires detail level; the steady approach is proportional allocation via
AfterSourceInvokescript. - Channel Branch Required:
node+order_typedetermines document type. JD & Tmall Supermarket channels use fixedXSDD01_SYS; regular Taobao/Tmall require conditional branches, otherwise FBillTypeID mismatch will be rejected by Kingdee. - Idempotency Key Design: Use
io_id+shop_idcombination as the idempotency key to avoid duplicate sales orders on rerun. - Approval Status Filter: Only sync approved (C status) documents; pushing draft status to ERP makes documents non-revocable.
Pitfall Retrospective
- Pitfall 1: Writing shop code directly. A retail enterprise initially wrote
shop_iddirectly into FCustId, causing missing customer profiles in Kingdee and full reconciliation failure. The steady approach is to build a shop-to-customer mapping table first. - Pitfall 2: Rounding cumulative difference in allocated amounts. After script allocation, the detail line total differs from the document-level amount by 1 cent, failing Kingdee validation. This is easy to fail; the steady approach is to compute the last line by subtraction, locking the tail difference.
- Pitfall 3: Incremental cursor losing cross-day documents. The
modifiedcursor was truncated during cross-day scheduling, losing several orders. Overlap window + server-side time cursor are mandatory. - Pitfall 4: Style product mapping misalignment. Confusion between Jushuitan i_id (style) and sku_id (SKU); some customers mapped FMaterialId with i_id causing one-product-multiple-codes. Unified agreement: SKU-level maps FMaterialId, i_id only as auxiliary.
- Pitfall 5: Qimen token expired without refresh. access_token typically expires in 2 hours; if the platform doesn't auto-renew, widespread 401 errors occur. The Qeasy adapter has built-in renewal; self-developed scripts need scheduled refresh.
When to Use
The Jushuitan Qimen Sales Outbound Order API suits multi-channel e-commerce outbounds that need to quickly enter ERP financial and inventory chains; if the enterprise only uses Jushuitan self-operated warehouses or only needs non-Qimen channel data, the simple API can streamline the policy. If the source system is not Jushuitan, this API does not apply.