Authoritative Tutorial on the Kingdee Assembly/Disassembly Processing Fee Query Interface: Full-Stack Practice from the Aiduo Integration Scenario to Qeasy Implementation

What This Interface Solves

In manufacturing and retail cost accounting scenarios, processing fees generated by assembly and disassembly operations are often scattered across multiple systems. We need to quickly retrieve these fee details by month and warehouse dimension for cost reconciliation, expense allocation, and financial reporting. This interface is essentially a "query-only data channel"—it pulls processing fee data from Kingdee via GET and hands it off to downstream analytics or sync strategies, without writing directly into business systems.

Interface Capability Overview

Authentication & Invocation

• Path: api/kingDeeAccountBalance/getBalance
• Method: GET
• Input: month passed via otherRequest (e.g., 202406), defaulting to the current statistical month
• Auth: Inherits the standard Kingdee Cloud Galaxy private-deployment authentication, managed by the corresponding adapter on the Qeasy side

Response Structure

• Returns a list of processing fee details; core fields are listed below
• Pagination: Not configured in the original strategy; returns full data—evaluate adding pagination if the month span or business volume grows
• Incremental Mode: No explicit incremental key; relies primarily on month for monthly slicing; the scheduler triggers daily at 02:03 (crontab 3 2 * * *) and uses month-based comparison for deduplication

Typical Execution Strategy

• The strategy is marked as a query-only strategy; the Target is configured as a "write no-op", meaning read-only, allowing data to first settle in Qeasy before deciding its destination

Typical Field Mapping

How to Configure on Qeasy

In the Qeasy Data Integration Platform, this interface is typically packaged as a "Kingdee Processing Fee Query" adapter, attached to the data integration task:

1. Create a query strategy: Select Kingdee as the source system; the target system can temporarily be the Qeasy Integration Platform (corresponding to "write no-op" mode).
2. Configure request parameters: Use Qeasy-provided expressions or scheduling variables directly for month; default to a test month (e.g., 202406) for joint debugging.
3. Enable idCheck: Set sourceBillNo as the primary key; the platform's field mapper will automatically deduplicate by it, avoiding downstream duplicate postings from repeated pulls.
4. Field Mapper: For string-numeric fields like count and amount, use the toDecimal or toNumber converters built into the Qeasy field mapper to centralize type conversion rather than scattering scripts across multiple strategies.
5. Scheduling: Set the crontab to 3 2 * * * to avoid business peak hours; when crossing months, remember to adjust the month expression to "previous natural month".

Cross-Scenario Practical Highlights

1. Month as a natural slicing key: Across multiple projects we observed that as long as the month is fixed as a 6-digit string, both cross-month scheduling and data backfill run stably.
2. Treat warehouse name as a dimension, not a primary key: warehouseName changes frequently (renamed, merged)—never use it as the deduplication primary key; use it only as a statistical dimension.
3. Explicit conversion of string-numeric values is mandatory: count and amount are both strings on the Kingdee side. If the integration side treats them directly as numbers, summation misalignment and precision loss will occur; the safe approach is unified transformation at the mapping layer.
4. idCheck compares sourceBillNo: Multiple projects have verified that using the source document number as the idempotency key is the most stable approach—even if month or warehouse fields change, duplicates won't occur.
5. Target no-op write isn't truly empty: In Qeasy, "write no-op" drops data into the platform's temporary area, which can later be consumed by consumer strategies—don't mistakenly think the strategy didn't run.
6. Missing pagination requires return-volume monitoring: The original strategy has no pagination; once business volume spikes in a given month, the response body can become huge—recommend adding a return-row alert on the Qeasy side.

Pitfall Retrospective

• Pitfall 1: Using warehouseName as the deduplication primary key After a warehouse rename, all historical data was re-imported, doubling reconciliation amounts. Fix: Always use sourceBillNo as the primary key; treat warehouse as a dimension only.

• Pitfall 2: Writing month as 2024-6 Zero-padding the month caused it to fail, so the filter condition didn't take effect and full data was returned. Fix: Lock to a 6-digit string; use functions like formatDate on the Qeasy side as a safety net.

• Pitfall 3: Directly accumulating amount as a number String concatenation produced values like 100200, wrecking financial reports. Fix: toDecimal in the field mapper before aggregation.

• Pitfall 4: Ignoring scheduler timezone Daily 02:03 trigger was using UTC, so the actual effective time was 10:03 Beijing time—missing the financial closing window. Fix: Explicitly declare the timezone in Qeasy's scheduler configuration.

• Pitfall 5: Missing data on cross-month backfill The scheduler only ran for the current month; historical months were never filled. Fix: Use Qeasy's backfill script to loop through months and trigger getBalance.

When to Use

Suitable for "monthly pull of processing fee details for cost accounting" pure query scenarios, especially in manufacturing and retail with multi-warehouse and financial reconciliation needs; not suitable for high-frequency real-time calls or scenarios requiring strong transactional consistency. When writing entries into downstream business systems one by one, we recommend splitting out a dedicated sync strategy rather than reusing this query.