Jushuitan × Kingdee Cloud星辰 Supply Chain Integration Interface Field Handbook: A Complete Guide to 21 Strategies from Outbound to Procurement
What Problem Does This Interface Solve
In retail and e-commerce scenarios, Jushuitan serves as the front-end e-commerce ERP while Kingdee Cloud星辰 serves as the back-end financial ERP. Both systems generate documents such as products, inventory, sales outbound/return, procurement inbound/return, and warehouse transfers. Without integration, business users must manually re-enter documents in both systems, leading to inventory mismatches, slow financial reconciliation, and unattended exceptions. The core value of this interface set is to automatically transfer Jushuitan's e-commerce business documents into Kingdee for financial accounting, while writing back Kingdee's product master data and inventory to Jushuitan for front-end operations—delivering true business-to-finance document unification.
Interface Capability Overview
- Authentication: Kingdee Cloud星辰 uses OAuth2 authorization code mode (requires periodic access_token refresh); Jushuitan uses AppKey + AppSecret + signature; Qimen interfaces use a separate authorization chain.
- Request Structure: All use HTTPS + JSON, predominantly POST; pagination is typically
page_index / page_size, and incremental pulls rely onmodify_start_time / modify_end_timeor themodifiedtimestamp. - Response Structure: Kingdee uses a uniform envelope
{ "code", "message", "data" }; Jushuitan returns{ "code", "msg", "data" }. Success codes are typically 200 / 0. - Pagination/Incremental Mode: Kingdee's product/inventory APIs support time-window pagination capped at 7 days; Jushuitan's outbound/return/procurement APIs use modification-time increment, and only documents with
Confirmedstatus are synced.
Typical Field Mappings
| Source Field | Target Field | Meaning | Practical Notes |
|---|---|---|---|
| material_number | sku_id / i_id | Material/Product code | Material mapping must exist first, otherwise documents fail |
| material_name | name | Product name | Direct pass-through; watch length limits |
| material_model | properties_value | Specification/model | Can also serve as auxiliary code |
| stock_number | warehouse | Warehouse code | Main=1, Sales return=2, Inbound=3, Defective=4 |
| io_id / as_id | bill_no | Document number | Returns use as_id, outbound uses io_id—never mix |
| modified / io_date | bill_date | Document date | Must be formatted as YYYY-MM-DD |
| shop_id / open_id / shop_buyer_id | customer_number | Customer code | Three distinct mapping sets per strategy |
| free_amount | bill_dis_amount | Document discount | Direct pass-through; mind currency |
| sku_id | material_number | Line material code | Map to array material_entity per line |
| qty / batch_qty | qty | Outbound/inbound qty | Prefer batch_qty to support batches |
| price / amount | price / amount | Unit price/amount | Keep two decimals |
| batch_no / batch_id | batch_no | Batch number | Joint lookup needed for procurement |
| product_date / expire_date | kf_date / valid_date | Production/validity date | Date format must be compliant |
| supplier_id / seller_id | supplier_number | Supplier code | Different field names for inbound vs return |
| remark | remark or custom_field | Remarks | Can use template {{po_id}}/{{remark}} |
How to Configure on Qeasy Cloud
On the Qeasy Cloud Data Integration Platform, this interface set is encapsulated into two standard adapters: the "Jushuitan Connector" and the "Kingdee Cloud星辰 V2 Connector". The standard approach is: first create data source accounts for both in Qeasy Cloud's connector marketplace and enable the authorization refresh strategy (corresponding to Strategy 3) to keep tokens alive; then use Qeasy Cloud's field mapper to configure the source/target field pairs above. Array-type material_entity is handled by Qeasy Cloud's built-in "entry mapping" node—no manual loops needed.
For the 21 strategies, Qeasy Cloud's orchestration canvas supports configuring the basic-data sync (products, brands, currencies) as upstream dependency nodes; business document nodes automatically inherit the code mapping results by referencing upstream outputs. Qeasy Cloud's scheduler supports direct crontab configuration, allowing staggered schedules (e.g., */8 vs */30) to avoid Kingdee-side rate limiting.
Cross-Solution Practical Points
- Code mapping is the lifeline of document landing: In multiple customer projects, 80% of first-run failures stem from missing material_number↔sku_id and customer_number mappings. Always run basic-data query strategies before business document strategies.
- Distinguish Qimen from non-Qimen: For the same Jushuitan outbound document, the Qimen interface uses shop_id / open_id / shop_buyer_id (three customer mapping sets), while the non-Qimen interface only uses shop_id. Document types must not be mismatched.
- Return documents must use as_id: Outbound uses io_id, return uses as_id—mixing them causes duplicate document numbers in Kingdee and audit failures.
- Prefer batch_qty for batch dimensions: When both items and batchs exist in Jushuitan details, prefer batchs as the material_entity source, otherwise batch numbers cannot reach Kingdee.
- Time window must be ≤7 days: Kingdee's incremental APIs strictly limit query span to 7 days; exceeding this throws an error. Slice by day.
- Explicitly pass operation_key for auto-audit: Transfers, other outbound, and procurement inbound/return all require
operation_key: "audit"explicitly in the request body, otherwise documents remain in "saved but unaudited" state.
Pitfall Post-Mortem
- Token expiration causes batch failures: Kingdee access_token is valid for ~2 hours. Without auto-refresh, "documents fail all of a sudden in the afternoon" is common. The safe approach: set Strategy 3 to
0 */2 * * *in Qeasy Cloud and enable trigger-based refresh hooks. - Inventory count wiped to zero by stocktake upload: When syncing Kingdee inventory to Jushuitan stocktake,
type=checkmeans full override—pushing a zero quantity will wipe Jushuitan's available stock. Correct practice: add a quantity threshold filter, skip values under 1. - Customer mapping mismatch causes cross-accounting: shop_id and shop_buyer_id have different meanings across e-commerce platforms; mismapping causes sales outbound documents to fall under the wrong customer, breaking reconciliation. Recommendation: use Qeasy Cloud's mapper dry-run mode and run a one-week shadow period first.
- Procurement inbound rejected due to missing batch: If Jushuitan procurement inbound doesn't enable batches, batchs is empty, but Kingdee's material has batch management enabled, causing validation failure. This is a common pitfall—use Strategy 4 to first check whether materials enable batches, then handle categories separately.
- Duplicate document creation by Qimen and standard interfaces: Running both Qimen and non-Qimen strategies simultaneously creates two copies of the same Jushuitan document in Kingdee. Correct practice: choose one per customer/store dimension, never run in parallel.
When to Choose
Choose this interface set whenever the business is an "e-commerce ERP (Jushuitan) ↔ financial ERP (Kingdee Cloud星辰)" closed-loop supply chain requiring inventory, orders, batches, and document-level real-time or near-real-time sync. Boundary: pure financial accounting scenarios don't need sales outbound/return sync; pure e-commerce operations don't need procurement inbound/return sync; multi-org/multi-account Kingdee environments must first confirm whether V2 corresponds correctly.