Kingdee Cloud Payment Bill (AP_PAYBILL) API Field Handbook Tutorial

What This Interface Solves

In the supply chain integration between MySQL and Kingdee Cloud, the Payment Bill (AP_PAYBILL) is the key document connecting the business front-end and the financial back-end. We need to reliably pull payment details, actual paid amounts, contact units, and bank account information from Kingdee into MySQL for payment reconciliation, payable balance verification, cross-system document tracing, and financial audit. This interface is essentially a query-only adapter—it only reads data from Kingdee and does not write back to the target system.

Interface Capabilities Overview

• Access Method: Kingdee Cloud WebAPI based on HTTP(S), requiring an application credential configured on the Kingdee side.
• API Method: ExecuteBillQuery (POST), with FormId fixed as AP_PAYBILL.
• Authentication: Uses Kingdee Cloud API authentication (typically App ID + App Secret + tenant info), managed uniformly by the Qeasy adapter.
• Request Structure: Filter string + field collection + pagination parameters (SQL-style SELECT/FROM/WHERE/LIMIT).
• Response Structure: Returns a two-dimensional result set where field names correspond to field entries in the metadata.
• Pagination/Incremental: Pagination via LIMIT/OFFSET; incremental sync typically uses FModifyDate as the cursor field with a rolling time window.
• Strategy Type: QUERY_ONLY — does not write to the target system, only supports data synchronization and reconciliation.

Typical Field Mappings

The following table summarizes high-frequency fields used across multiple customer projects, with sensitive information generalized.

How to Configure on Qeasy

In the Qeasy Data Integration Platform, AP_PAYBILL is packaged as a Kingdee Cloud query adapter. We typically configure it as follows:

1. Data Source Selection: Choose "Kingdee Cloud" and fill in the API endpoint, account set, and application credentials (managed by the adapter).
2. Form and Fields: Select AP_PAYBILL as the FormId, then use Qeasy's "Field Mapper" to tick the fields to be synced. The platform automatically retrieves field types and base data reference relationships based on Kingdee metadata.
3. Filter Conditions: Use Kingdee SQL-style strings, e.g., filter by FModifyDate >= last sync time and document status.
4. Incremental Strategy: Qeasy's "Incremental Recognizer" performs upserts based on the primary key (FPAYBILLENTRY_FEntryID) to avoid duplicate writes.
5. Target Side: When writing to MySQL, the platform automatically creates tables and executes INSERT/UPDATE based on the field mapper. Field naming follows generic concepts (see mapping table above) for easier secondary development.
6. Exception Handling: Qeasy's "Fault Tolerance Strategy" supports network retries, pagination resumption, and Kingdee throttling backoff—an essential engineering safeguard.

Cross-Scenario Best Practices

Based on multiple customer projects, we have distilled the following common lessons:

1. Always use FModifyDate as the incremental cursor, not FCreateDate—many scenarios involve back-dated or modified bills, and using creation time will miss data.
2. Store both original and local currency amounts. Kingdee's amount fields come in pairs (original _FOR_H, local _H); the integration side must store both sets and never re-convert, to avoid rate inconsistency.
3. Decompose base data fields for storage. Fields like FCONTACTUNIT and FSETTLEORGID return composite objects with FNumber from Kingdee; be sure to extract FNumber separately in ETL and store only the code on the target side.
4. Do not check totals alone. In multiple projects we found that actual paid, payable, write-off, and handling fee amounts must be verified separately—checking only the sum hides individual discrepancies.
5. Third-party document number (FTHIRDBILLNO) is the bridge for cross-system reconciliation. If the MySQL-side business document number is well-maintained, it can be precisely correlated with this field, making reverse lookup easy.
6. Treat cancelled documents as "reversal events". In Kingdee, bills with FCancelStatus='B' are not physically deleted; the integration side must write them as "cancellation" events to the target database, otherwise reconciliation will show "vanishing" amounts.

Troubleshooting

• Pitfall 1: Using SQL-style * for SelectField in ExecuteBillQuery causes Kingdee to return 200+ fields, leading to timeouts. Solution: Select only the fields actually needed by the business, typically 30–50.
• Pitfall 2: Using FCreateDate directly for incremental sync results in missing data when bills are back-dated or modified. Solution: Use FModifyDate uniformly as the cursor, and look back 5–10 extra minutes each run to handle time-window boundaries.
• Pitfall 3: Counterparty bank accounts contain special characters or full-width spaces, causing matching failures after storage. Solution: Apply trim and half-width normalization in ETL, and unify the character set to UTF-8.
• Pitfall 4: Local currency amounts get re-converted on the target side, resulting in 0.01 rounding discrepancies. Solution: Pull both original and local currency directly from Kingdee, with no rate conversion on the target side.
• Pitfall 5: Subsequent pages get truncated when the Kingdee pagination parameter exceeds the single-return limit. Solution: Enable pagination resumption in the Qeasy adapter, with each page limited to 500–1000 rows to avoid triggering Kingdee timeouts.

When to Use

This interface is suitable for "Kingdee Cloud → MySQL" query-only supply chain integration, especially payment reconciliation, payable balance verification, cross-system document tracing, and bank-to-payment matching. It is not suitable for writing or modifying payment bills, since the strategy type is fixed as QUERY_ONLY; if two-way synchronization is needed, it should be paired with a payment bill write strategy.