Kingdee Cloud Galaxy Sales Outbound Order API Field Manual: From Field Mapping to Qeasy Cloud Configuration
What This Interface Solves
The Kingdee Cloud Galaxy SAL_OUTSTOCK sales outbound order API bridges ERP outbound facts back to CRM. In retail-distribution integration scenarios, once the warehouse approves the outbound order, the CRM-side delivery note must update in real-time to enable subsequent payment collection and reconciliation. This interface connects SAL_OUTSTOCK to Fenxiao CRM DeliveryNoteProductObj, serving as the critical hub linking ERP logistics execution with CRM sales collaboration.
Interface Capability Overview
Kingdee Cloud Galaxy provides OAuth2 and application ID authentication. When calling the SAL_OUTSTOCK query API, you must include formId and field filter conditions. The response body is a standard JSON array with header fields and FEntity detail rows returned in parallel.
Pagination and Incremental Mechanism: Pagination is achieved through Limit and StartRow (recommended 500 records per page). Incremental filtering relies on FModifyDate > LAST_SYNC_TIME, with status filtering limited to FDocumentStatus='C' (approved). In Qeasy Cloud, the platform encapsulates the paginator and cursor management by default, eliminating manual offset maintenance.
Typical Field Mappings
| Field Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| FBillNo | String | Document number | Unique delivery note ID, mapped to CRM name field |
| FDate | Date | Outbound date | Transformed to delivery_date, watch timezone alignment |
| FCustomerID.FNumber | String | Customer code | Joined with mapping table → CRM account_id |
| FReceiveAddress | String | Shipping address | Direct pass-through, watch special character escaping |
| FSHRMC | String | Recipient | Chinese field, watch character encoding |
| FLXDH | String | Contact phone | String type, avoid numeric precision loss |
| FCarriageNO | String | Logistics number | Direct pass-through |
| FMaterialId.FNumber | String | Material code | Detail row field, joined → product_id |
| FRealQty | Decimal | Actual shipped qty | Core detail row field, direct pass-through |
| FPrice | Decimal | Unit price | Watch currency and precision |
| FDocumentStatus | String | Document status | Only sync approved status |
| FModifyDate | DateTime | Modify timestamp | Core timestamp for incremental judgment |
How to Configure on Qeasy Cloud
In Qeasy Cloud, this interface is typically invoked through the Kingdee Cloud Galaxy adapter. The configuration path has three layers:
- Data Source Configuration: Fill in tenant information (injected via environment variables after desensitization), application ID and secret, select the
SAL_OUTSTOCKdocument. - Field Mapper: Qeasy Cloud's field mapper automatically recognizes the source table structure and provides drag-and-drop mapping. For fields requiring joins (customer, material), the platform has a built-in encoding mapping converter—simply specify the mapping table name to complete FNumber ↔ _id bidirectional conversion.
- Strategy Orchestration: Place this strategy after the dependency chain (Material→Product, Customer→Customer, Warehouse→Warehouse Archive) and set the schedule cycle to 10–15 minutes. Qeasy Cloud's scheduler queues by dependency automatically, ensuring master data goes first.
Cross-Solution Practical Points
From multiple customer projects, we have distilled these common lessons:
- Master data first is ironclad: Sales outbound orders depend on material, customer, and warehouse master data. If master data is not in place, detail row joins will fail massively. Always run the master data strategies (1/2/3/4) first.
- Full-to-incremental switch timing: The first sync must be full to build the mapping table, then switch to incremental. Qeasy Cloud's "first full / subsequent incremental" toggle makes this switch one-click.
- Status filtering determines data quality: Syncing only approved status avoids downstream dirty data. However, if business requires draft states, confirm status semantics with the customer (some use 'B' for partial approval).
- Link back to sales orders: Delivery notes should reference the source sales order (matched by FBillNo or extension fields), so CRM can see order fulfillment progress, improving business transparency.
- Fault tolerance on join failures: When customer/material mapping is missing, record to dead-letter queue and alert, rather than silently skipping. Qeasy Cloud's alert channel integrates with WeCom and DingTalk.
- Amount and quantity precision: Kingdee uses Decimal type. When transmitting to CRM, align precision—recommend unifying to 4 decimal places.
Pitfall Post-Mortem
Pitfall 1: Join failure causes entire document to be discarded In real scenarios, if one detail row's material code is missing from the mapping table, the entire outbound document is skipped. The safe approach is row-level fault tolerance: persist the header first, and when detail rows are missing, record them to dead-letter individually rather than rolling back the whole document.
Pitfall 2: Timezone offset causes incremental data loss Kingdee's FModifyDate carries timezone info by default. If Qeasy Cloud does not normalize timezones after fetching, cross-day data may be missed. Recommend explicitly setting timezone conversion rules in the field mapper.
Pitfall 3: Delivery note and sales order number collision If the same FBillNo appears across different organizations (multi-org scenario), the encoding mapping must carry an organization prefix, otherwise CRM will misjudge them as the same document.
Pitfall 4: Empty logistics number causes downstream validation failure When logistics numbers are not yet assigned, FCarriageNO is empty. If CRM marks this as required, it will reject the record. During configuration, change the downstream required field to optional or pre-fill with a placeholder.
Pitfall 5: Status changes trigger reverse updates When a Kingdee outbound order is unapproved, FDocumentStatus changes. If downstream does not roll back status, "ghost delivery notes" appear. In Qeasy Cloud, configure state machine validation in the strategy to keep only terminal state data.
When to Use
This API suits scenarios requiring real-time ERP outbound data sync to CRM, such as retail-distribution integration, O2O convergence, and batch traceability. The boundary is: if only T+1 summaries (not real-time details) are needed, consider the inventory API instead to reduce sync frequency and data volume.