Authoritative Tutorial: Querying Jiandaoyun Material Form Data API Field Reference

What Problem This API Solves

In sales-order integration, material master data is the four-in-one foundation of "code-name-spec-unit" that nearly every downstream document (orders, outbound shipments, invoices) depends on. Jiandaoyun often serves as the front-end business entry, while Kingdee Cloud Cosmic acts as the formal ERP ledger. This API is responsible for pulling material form data from Jiandaoyun by entry in batches, providing the query substrate for downstream Kingdee material sync and sales-order mapping.

Interface Capability Overview

• Authentication: Jiandaoyun API Key (Authorization header), which is automatically injected by the platform once configured in Qeasy Cloud's credential management.
• Request Structure: GET /api/v2/app/{app_id}/entry/{entry_id}/data. Core parameters are fields (comma-separated field list), limit (1~100, default 10), and filter (optional filtering).
• Response Structure: A JSON object containing a data array (each record is one material row) and data.total (the total count matching the criteria), facilitating full reconciliation.
• Pagination / Incremental: The native API does not provide a direct cursor. In real projects, we paginate through limit to fetch everything, then use filter for incremental conditions (such as last-modified time). In Qeasy Cloud, this is typically encapsulated as "pagination + primary-key deduplication" into an observable query strategy.
• Strategy Type: Target is configured as "write-empty operation", i.e., QUERY_ONLY, which does not write back to the target system.

Typical Field Mapping

How to Configure on Qeasy Cloud

In the Qeasy Cloud Data Integration Platform, this API is typically encapsulated as a "Jiandaoyun Form Data Query Adapter":

• Adapter: Select "Jiandaoyun - Form Data Query", fill in appId and entryId, and choose "Material" as the data object.
• Field Mapper: The platform reads metadata and marks _id as id and _widget_1669962898406 as number. The field mapper automatically expands all _widget_* fields; just drag them onto target fields.
• Strategy Configuration: Set Target to "write-empty operation" to indicate a pure query; enable idCheck for primary-key validation; the scheduled task (e.g., */17 2-23 * * *) controls the fetch frequency to avoid overwhelming the source.
• Dependency Orchestration: It typically acts as a prerequisite query node for "Kingdee Material Sync to Jiandaoyun" and "Modify Jiandaoyun Material Data". Qeasy Cloud's strategy orchestration diagram can explicitly declare depends_on.

Cross-Solution Best Practices

1. Treat _id as the primary key, not as a "value field": Jiandaoyun primary keys are system-generated strings; do not mix them with business codes, otherwise updates cannot find the record.
2. Material code must strictly match Kingdee FNumber: Both sides should trim leading whitespace and normalize case; this is the foundation for cross-system reconciliation.
3. Choose one spec field based on the business: The same Chinese label may correspond to both a single-line and a multi-line widget. In real projects, we usually pick one, otherwise Kingdee's FSpecification will conflict.
4. Use pagination together with filter: For large forms, you must narrow down with filter; otherwise repeatedly pulling the full dataset is slow and expensive.
5. Enable idCheck together with the scheduled task: Without primary-key validation, scheduled data may cause "same code producing multiple records" failures in subsequent sync strategies.
6. Explicitly declare query-only nodes: Select "write-empty operation" as Target to avoid mistakenly treating query results as write actions that trigger downstream updates.

Pitfall Retrospective

• Pitfall 1: Treating _id as the material code. Jiandaoyun's _id is the system primary key; it should not be directly mapped to Kingdee's FNumber. The safe approach is to use _widget_1669962898406 as the business code mapping.
• Pitfall 2: Mapping both spec fields. The two widgets share the same Chinese name; mapping both to Kingdee FSpecification causes "same field with inconsistent values" alerts.
• Pitfall 3: Forgetting that limit defaults to 10. One-off business syncs easily miss data due to the small default page size; explicitly pass limit=100 and paginate.
• Pitfall 4: Writing the wrong field name in the filter expression. Jiandaoyun's filter only recognizes widget IDs, not Chinese names; once the field name is wrong, an empty set is returned. Dump a sample record first when troubleshooting.
• Pitfall 5: Misconfiguring a query strategy as a sync strategy. Without the "write-empty operation" configuration, query results may be treated as incremental write-backs, generating dirty data on the Jiandaoyun side.

When to Use This API

This API is suitable for pure query scenarios where "Jiandaoyun materials need to be provided as master data to downstream systems (Kingdee, ERP, MES)", such as material linkage selection in sales orders or outbound documents. If the business needs to write materials into Jiandaoyun from another system, a "write/update material" strategy should be used instead of this query API.