Kingdee Cloud PUR_ReceiveBill API Field Manual & Engineering Tutorial

What This Interface Solves

In retail and distribution supply-chain integrations, the procurement receiving step is the most common source of mismatches: supplier deliveries, receiving inspections, and stock-in postings often live separately in the ERP and the commerce platform. The PUR_ReceiveBill (Material Receiving Notice / Purchase Receive Bill) interface lets us paginate and pull detailed receiving records from Kingdee Cloud, then reconcile them with upstream purchasing orders and delivery notes in platforms such as WanDianTong. It is the foundation for building an end-to-end "delivery → inspection → stock-in" pipeline.

Interface Capability Overview

• Authentication: Kingdee Cloud WebAPI, authenticated with an application ticket/signature issued by the tenant identity service.
• Request structure: POST executeBillQuery, Form ID PUR_ReceiveBill, supporting field filters (default FApproveDate>='{{LAST_SYNC_TIME}}' and FDocumentStatus='C'), pagination (Limit/StartRow), and field selection.
• Response structure: A flattened header+entry rowset. Each record corresponds to one receiving line; header fields (e.g., FBillNo, FSupplierId) are repeated on every row.
• Pagination / incremental: Uses FApproveDate as the incremental cursor, combined with status C (approved) to avoid drafts or cancelled documents. High-frequency scenarios commonly poll every 3 minutes.

Typical Field Mapping

Configuring It on QeasyCloud

On the QeasyCloud data integration platform, Kingdee Cloud WebAPI is typically accessed via an adapter plus field mapper combo:

• Adapter: Pick the Kingdee Cloud WebAPI adapter, fill in the tenant endpoint and ticket, choose action executeBillQuery, and set Form ID to PUR_ReceiveBill.
• Field mapper: QeasyCloud's field mapper automatically generates primary-key fields based on metadata.id (FDetailEntity_FEntryID) and metadata.number (FBillNo); no manual assembly needed. The filter panel can directly emit FApproveDate>='{{LAST_SYNC_TIME}}' and FDocumentStatus='C'.
• Write side: Target is configured as a "no-op write", indicating a pure query strategy that only lands data into the middle platform or pushes it to downstream listeners (e.g., a WanDianTong reconciliation task).
• Scheduling: You can configure crontab directly inside the platform (e.g., 1-59/3 7-23 * * *). QeasyCloud tracks strategy watermarks to prevent duplicate consumption.

Cross-Scenario Engineering Highlights

1. Prefer line-level PK over header PK: Multiple customer projects hit "headers match, lines mismatch" reconciliation drift. The most stable idempotency key is FDetailEntity_FEntryID.
2. Incremental must combine approve-date + status: Filtering on FModifyDate alone misses the case where an approved document is not modified. Pair it with FDocumentStatus='C' to only fetch effective documents.
3. Slice by org in multi-org setups: FStockOrgId / FPurOrgId slicing prevents double-counting across ledgers—a common pain point in multi-ledger retail customers.
4. Distinguish the four qty fields: FActlandQty (arrival), FActReceiveQty (delivery), FInStockQty (stock-in), FInStockJoinQty (qualified stock-in). Misusing them inflates or deflates stock.
5. Mind tax-included vs. tax-exclusive and LCY: FTaxPrice / FAllAmount_LC are critical for downstream settlement. Ignoring the LCY fields causes end-of-month variance in multi-currency projects.
6. Delivery note is the last resort in disputes: FSendBillNo is often the only anchor in supplier paper-doc disputes—always preserve it and write it to logs.

Pitfalls & Fixes

• Pitfall 1: Pulling drafts/cancelled docs — Only filtering on FModifyDate yields ghost documents. Fix: always pin FDocumentStatus='C' and re-validate on the write side.
• Pitfall 2: Pagination boundary data loss — Kingdee paging is sensitive to total-count drift; the last page may duplicate on long incremental runs. Fix: QeasyCloud applies watermark-based idempotent compensation; engineers should also write an id+number composite dedupe.
• Pitfall 3: Multi-UOM qty mismatch — Matching on FInStockQty only and ignoring FAuxUnitQty breaks auxiliary-UOM reconciliation. Fix: route by UOM type.
• Pitfall 4: Supplier code length drift — FSupplierId lengths vary across ledgers; naive string concat misaligns. Fix: map through supplier master data.
• Pitfall 5: LCY fields ignored — Cross-border/multi-currency projects that only use FAmount and skip FAmount_LC discover variances only at month-end. Fix: always settle against LCY fields.

When to Use

Use this when you need to bulk-pull detailed Kingdee Cloud receiving documents at line granularity and reconcile them with external commerce/WMS systems. It is not suitable for write-back flows—this is a read-only interface and must be paired with other write strategies to close the full business loop.