Authoritative Tutorial: Kingdee YXC Logistics Company Query API Field Manual

What This API Solves

In retail cross-system integrations, logistics company master data is shared between sales-out, shipping, and freight settlement. The partner retail platform needs stable logistics codes and contacts, while Kingdee YXC is typically the system of record. By exposing the query endpoint /jdy/v2/bd/logistics_company, logistics master data can flow reliably into the partner platform, supporting shipment mapping, freight settlement, and code cross-reference, eliminating dual manual maintenance.

API Capability Overview

• Authentication: Kingdee YXC V2 standard OpenAPI auth. Obtain an AccessToken via /jdy/v2/oauth/token using AppKey/AppSecret, then pass it through request headers.
• Request Structure: GET /jdy/v2/bd/logistics_company, with two pagination parameters: page and page_size. Detail records are fetched via otherRequest.detailAPI pointing to /jdy/v2/bd/logistics_company_detail.
• Response Structure: Standard JSON containing a data array and pagination metadata (total rows, total pages). Each record exposes both id (primary key) and number/bill_no (business code).
• Pagination / Incremental Mode: Page-based pagination (default page_size=10). Scheduled jobs typically use the crontab */5 * * * *. Incremental checks rely on modify_time timestamps.
• Strategy Type: effect: QUERY — a read-only master data strategy. The Target side is configured as a no-op write.

Typical Field Mapping

How to Configure in Qeasy

1. Adapter: In Qeasy's "Data Source Management", create a "Kingdee YXC V2" connection, fill in tenant ID, AppKey/AppSecret, and call /jdy/v2/oauth/token to retrieve the AccessToken.
2. API Wrapper: Pick the "Logistics Company Query" template under "Kingdee YXC · Business Documents". The default method is GET, and page/page_size are appended automatically.
3. Metadata Mapping: In metadata, map id to the id field and number to bill_no, and enable idCheck: true and autoFillResponse: true. The Qeasy field mapper auto-expands contact_* and dispatcher_* groups and supports a "province/city/district + detail → full address" merge rule.
4. Detail Drill-Down: Enable detailAPI under "Other Request" so that /jdy/v2/bd/logistics_company_detail is invoked per id after the list query.
5. Write Strategy: Since this is a query-only strategy, the Target is configured as a no-op write. It normally runs as a master data prerequisite, with downstream tasks (such as sales-out sync) chained via depends_on.

Cross-Scenario Best Practices

1. Dual-Track Primary Key + Code: Kingdee returns both id and bill_no. In Qeasy we always use id as the idempotency key and bill_no as the business code, so downstream matching stays stable even if codes change.
2. Handle Address Groups Separately: contact_* (contact address) and dispatcher_* (dispatch address) share the same structure but differ semantically. Never merge them into one target field, or dispatch data will overwrite contact data.
3. Parse Objects on Demand: payment_entry, cus_bear_fee_entry, attachments_url, and custom_field are structured objects. Qeasy supports JSONPath extraction, but always inspect the response shape in the preview panel before writing expressions.
4. Use modify_time for Incremental Sync: Across multiple retail projects, logistics companies change rarely but do change. Using modify_time for incremental filtering is far more stable than full scans; a 5-minute schedule works well.
5. Unify BigDecimal for Money: total_amount, all_debt, etc. are strings. Always parse with BigDecimal during cross-system transmission to avoid floating-point discrepancies in reconciliation.
6. Typo Compatibility: recevice_delivery is a known typo preserved by the Kingdee API. Keep both receive_delivery and recevice_delivery valid on the target side to survive upgrades.

Pitfall Retrospective

1. Default page_size=10 causing first-sync data loss: Kingdee defaults to 10 records per page. With more than 10 logistics companies, paging silently truncates results. The safe approach in Qeasy is to explicitly set page_size to 50 or 100, and cap maximum pages in the paginator.
2. Using id as the business code: Mapping Kingdee id directly into the partner platform's logistics code breaks downstream lookups whenever Kingdee rebuilds primary keys. We always use bill_no as the business code and reserve id for internal idempotency.
3. Dispatch address overwritten by contact address: Both addresses are literally "address" in the source, which is easy to misconfigure. The Qeasy field mapper separates them by the dispatcher_* prefix; engineers only need to align groups.
4. Objects written as raw strings: payment_entry and similar objects, written without expansion, become [object Object] on the target. Use Qeasy's JSONPath or a script node to flatten them before mapping.
5. Missing incremental field forces full reloads: Some clients skip modify_time, causing repeated full loads. Mark modify_time as the "incremental field" in Qeasy's field settings and enable "increment by modify time" in the filter.

When to Use This API

Pick it when you need Kingdee YXC as the source of truth for logistics master data and want to synchronize it into an e-commerce ERP, retail middle platform, or WMS. If you only read logistics info from a single Kingdee sales-out document, reuse the sales-out API directly. If the target system already owns logistics master data, this API can be skipped.