Field Manual for the Fenbeitong Travel Application Query API: From Subscription Trigger to Kingdee Cloud Cosmos

What Problem Does This API Solve

The Fenbeitong travel application query API fetches a single travel request by third_apply_id or apply_id, driven by subscription messages, and syncs it into the Kingdee Cloud Cosmos expense request form (ER_ExpenseRequest_Travel). It acts as the bridge in the "travel request → cost-bearing organization writeback" chain, avoiding the latency and redundancy of batch polling.

API Capability Overview

• Endpoint: /openapi/apply/custom_trip/v1/detail
• Method: POST (on-premise deployments usually go through an internal gateway)
• Authentication: AppKey + signature + timestamp, with access_token in the header
• Request Parameters: third_apply_id (third-party custom application ID), apply_id (Fenbeitong custom application ID), update_mode (1-create new, 2-amend existing)
• Response Structure: Standard envelope code/msg/data; business data lives in data.apply, containing nested objects for the master record, itinerary, cost attribution, and accompanying persons
• Pagination/Incremental Mode: Single-record query, no pagination; incrementality is driven by subscription messages pushing IDs

Typical Field Mapping

How to Configure on the Qeasy Data Integration Platform

On the Qeasy Data Integration Platform, this kind of "subscription-trigger + single-record query + script enrichment + target writeback" chain is typically carried by a single QUERY_ONLY strategy. The configuration roughly goes:

1. Source Adapter: Pick the Fenbeitong travel application adapter, fill in AppKey/Secret, and wire the subscription-message callback as the trigger.
2. Field Mapper: Drag standard fields like code, proposer.code, create_time to Kingdee FBillNo, FStaffID, FApplyDate. Script-enriched fields (city1_name, all_cityname, users_names, etc.) are surfaced through the "custom fields" panel and made available for mapping.
3. AfterSourceInvoke Hook: Mount a script on the source response callback to join multi_trips.citys[].city_name into all_cityname, expand cost_attributions.details into 部门_* and 费用承担公司_*, and join users[] into users_names/users_codes. The Qeasy field mapper auto-detects script-injected fields and lists them in the mapping palette.
4. Target Writeback: On the Kingdee side, use _findCollection with FBillNo={{code}} to decide create vs. amend, and set IsAutoSubmitAndAudit to true (new) or false (amend) accordingly.

Cross-Project Practical Highlights

1. Derived fields must be declared explicitly: Fields like city1_name and 部门_name do not exist in the raw response; they must be produced inside AfterSourceInvoke, otherwise the target side will see empty values.
2. code is the only Kingdee anchor: Kingdee FBillNo consumes code directly; any collision will scramble the create/amend logic.
3. multi_trips is the itinerary source: Origin, destination, and the full city list all live here; do not misread top-level data.apply fields.
4. cost_attributions is the cost-bearing key: It is an array of details[] and must be iterated; do not treat it as a flat object.
5. users[] joining must stay consistent: Accompanying persons are joined with commas, names and codes separately, mapping one-to-one to Kingdee FAccompany and F_dps_TXRNO.
6. Subscription beats polling: This single-record query API does not need a cron job; subscription-triggered calls are both real-time and quota-friendly.

Pitfall Recap

1. city1_name not found in the response: The script is missing or wired at the wrong hook. The safe move is to enrich explicitly inside AfterSourceInvoke and log it for confirmation.
2. remark alone gets overwritten: Kingdee reason needs remark + all_cityname; mapping remark only drops the itinerary context.
3. update_mode mis-set to 1 on amendments: This recreates a new doc and causes Kingdee document-number conflicts. The safe approach is to distinguish new vs. amend events in the subscription message and pass the matching mode.
4. Cost-bearing organization not enabled: Disabled org records cause write failures; add an enablement check in the script and either skip or route to manual handling.
5. Accompanying-person codes and names misaligned: Inconsistent join order scrambles FAccompany vs. F_dps_TXRNO. The safe move is to join from the same users[] array so order is naturally consistent.

When to Use It

Pick this API when you need to sync Fenbeitong travel applications into Kingdee Cloud Cosmos expense requests in near real time and latency matters. For batch reconciliation or offline analytics, prefer Fenbeitong's bulk-pull API instead; if the target is not Kingdee Cloud Cosmos, the field-enrichment patterns here still apply, but the actual mappings must be rebuilt.