Authoritative Tutorial on Kingdee Cosmic Supplier Query API Field Handbook: Practical Guide for JuShuitan Supply Chain Integration

What This API Solves

In JuShuitan–Kingdee Cosmic supply chain integration, supplier master data is the foundation for purchase orders, goods receipts, purchase returns, and payments. The /jdy/v2/bd/supplier endpoint lets us pull supplier records from Kingdee in a paginated, incremental fashion, enabling code mapping, status synchronization, supplier-field mapping on purchase documents, and invoice info write-back. It is the canonical pattern of a "query-only strategy."

API Capability Overview

• Authentication: Kingdee Cosmic V2 WebAPI standard auth (AppKey/AppSecret); access token carried in headers.
• HTTP Method: GET /jdy/v2/bd/supplier; detail endpoint is GET /jdy/v2/bd/supplier_detail (by id).
• Request Params: enable (1 active / 0 inactive / -1 all), modify_start_time / modify_end_time (millisecond timestamps), page (default 1), page_size (default 100).
• Response Structure: List-type payload. Each record contains id, number, name, enable, plus organization, invoicing, banking, address, contact, and custom field extensions.
• Pagination / Incremental Mode: Standard page/page_size pagination; incremental uses modification-time ms timestamps as cursor.
• Strategy Type: QUERY. Target is "write empty operation" — pure read, no target write.
• Scheduled Task: Default */10 * * * *, every 10 minutes.

Typical Field Mappings

How to Configure on Qeasy

On the Qeasy data integration platform, Kingdee Cosmic V2 ships as a built-in adapter that wraps /jdy/v2/bd/supplier with auth, pagination, and timestamp conversion. Typical setup:

1. In "Data Source," pick "Kingdee Cosmic V2," enter tenant credentials, and Qeasy's adapter auto-refreshes tokens.
2. In the strategy canvas, select the "Query Cosmic Supplier" template, set Target to "Write Empty Operation" to mark it as a pure query strategy.
3. In the field mapper, id is the primary key, number is the code key; incremental cursor defaults to modify_time, auto-resuming each round.
4. If results need to flow to JuShuitan, add a downstream write strategy; Qeasy auto-maps number ↔ supplier_code.
5. Default schedule is */10 * * * *, adjustable in Qeasy's scheduler panel.

Cross-Scenario Practical Points

1. number over name as correlation key: codes are stable and unique; names drift due to abbreviations, mergers, and renames.
2. Use modify_time as incremental cursor, not create_time: new suppliers are rare; ~99% of changes are modifications.
3. Keep page_size ≤ 100: Cosmic V2 rate-limits or truncates beyond 100; 50-100 is the safe range.
4. enable=-1 only for initial load: after full pull, switch to enable=1 to avoid re-writing inactive suppliers downstream.
5. Multi-account via account_entity: flat fields bank/bank_account only represent the first account; parse the array for multi-account cases.
6. Preserve admin-region ids: cross-system, ids outlast names; Qeasy's mapper keeps both by default.

Pitfall Retrospective

1. Misaligned source metadata response fields: templates retain material-API leftovers like stock_id, barcode, base_unit_id that don't match supplier responses. Calibrate to actual API responses, otherwise Qeasy's mapper reports "field not found."
2. ms vs s timestamp confusion: Cosmic V2 uses milliseconds; teams used to seconds end up with empty incremental windows and full reloads. Qeasy auto-detects units, but hand-written scripts must validate.
3. invoice_type enum drift: fully-digital invoices added 5 and 6, legacy clients only know 1-4, causing invoicing failures. Add an enum-compat layer in Qeasy mapper, default unknowns to "0 none" and raise alerts.
4. bom_entity empty array crashes downstream: empty contact lists may be treated as null objects by some writers. Add an "empty array → empty string" cleansing rule on the target side in Qeasy.
5. enable=0 suppliers still referenced by POs: inactive suppliers leak into historical documents. Add enable=1 filter in Qeasy; route inactive items to a separate archive strategy.

When to Use

/jdy/v2/bd/supplier fits scenarios where supplier master data needs to flow one-way from Kingdee Cosmic to JuShuitan or other downstream systems — typical use cases include multi-system supplier code unification, status synchronization, and invoice info write-back. It is not suited for: bidirectional supplier editing, cross-org multi-book bulk migration, or real-time per-document supplier validation (use the detail endpoint or document endpoints instead).