### 旺店通·旗舰奇门与金蝶云星空的销售退换管理对接案例分享
在本次技术案例中，我们将详细探讨如何通过轻易云数据集成平台，实现旺店通·旗舰奇门的数据无缝集成到金蝶云星空系统，尤其关注销售退换管理过程中已审核状态下的数据同步。
#### 背景及目标
为确保从旺店通·旗舰奇门接口 `wdt.aftersales.refund.refund.search` 获取的销售退换数据能够准确、高效地写入到金蝶云星空，通过API `batchSave` 进行批量处理，我们需要克服多种挑战。这包括但不限于：数据格式差异、分页和限流问题、实时监控及日志记录，以及异常处理与错误重试机制。
#### 数据获取与初步处理
首先，从旺店通·旗舰奇门接口定时可靠地抓取退款信息。由于该接口可能返回大量数据，需要有效处理分页及限流问题。具体方法是依据接口提供的分页参数，逐页请求并保存每次请求结果，同时结合速率限制防止触发API调用频率上限。
```python
# 示例代码：调用 wdt.aftersales.refund.refund.search 接口
def fetch_refund_data(api_key, page_size, max_pages):
for page in range(1, max_pages + 1):
response = requests.get(
'https://api.wangdian.cn/flagship/qimen/wdt.aftersales.refund.refund.search',
params={
'page': page,
'pageSize': page_size,
'appkey': api_key
}
)
if response.status_code == 200:
yield response.json()
else:
handle_error(response)
```
在获取这些退款信息后，需要进行必要的数据清洗和格式化，以符合金蝶云星空所需的字段要求。例如，将日期格式转换或布尔值映射等操作，为后续写入打下基础。
#### 数据批量写入与可靠性保障
为了保证高效的数据传输，我们利用了金蝶云星空支持的 `batchSave` API。此过程不仅涉及批量提交，还要考虑网络故障或者部分失败情况下的重试策略，确保整个流程中的任何一个环节都不致使潜在的数据丢失。
```python
# 示例代码：调用 batchSave 接口向金蝶云星空写入数据
def save_to_kingdee(data_batch):
response = requests.post(
'https://api.kingdee.com/starcloud/batchSave',
json=data_batch,
)
if response.status_code != 200 or not is_success(response.json()):
log_and_retry_failed_request(data_batch)
```
特别是在
### 调用旺店通·旗舰奇门接口wdt.aftersales.refund.refund.search获取并加工数据
在数据集成生命周期的第一步中，调用源系统的API接口以获取原始数据是至关重要的一环。本文将详细探讨如何使用轻易云数据集成平台配置元数据，调用旺店通·旗舰奇门接口`wdt.aftersales.refund.refund.search`来获取销售退换管理的相关数据，并进行初步加工。
#### 接口调用配置
首先，我们需要配置接口调用的元数据。根据提供的metadata，接口`wdt.aftersales.refund.refund.search`采用POST方法，主要参数包括分页参数和业务参数。
**分页参数：**
- `page_size`: 分页大小，默认值为200。
- `page_no`: 页号，默认值为1。
**业务参数：**
- `shop_nos`: 店铺编号，由英文逗号分隔。
- `tid`: 原始单号。
- `buyer_nick`: 客户网名。
- `trade_no`: 系统订单编号。
- `refund_no`: 退换单号。
- `return_logistics_no`: 物流单号（退换单上的退回物流单号）。
- `modified_from`: 修改起始时间，使用变量`{{LAST_SYNC_TIME|datetime}}`动态赋值。
- `modified_to`: 修改结束时间，使用变量`{{CURRENT_TIME|datetime}}`动态赋值。
- `settle_from`, `settle_to`: 结算时间范围。
- `agree_from`, `agree_to`: 审核时间范围。
- `status`: 退换单状态，默认值为30（已审核）。
- `stockin_status`: 入库状态。
- `type`: 退换单类型，默认值为2。
#### 数据请求与清洗
在完成元数据配置后，我们可以发起API请求以获取原始数据。由于该平台支持全异步操作，可以在后台运行多个请求，提高效率。
```json
{
"pager": {
"page_size": "200",
"page_no": "1"
},
"params": {
"shop_nos": "SHOP001,SHOP002",
"tid": "",
"buyer_nick": "",
"trade_no": "",
"refund_no": "",
"return_logistics_no": "",
"modified_from": "{{LAST_SYNC_TIME|datetime}}",
"modified_to": "{{CURRENT_TIME|datetime}}",
"settle_from": "",
"settle_to": "",
"agree_from": "",
"agree_to": "",
"status": "30",
"stockin_status": "",
"type": "2"
}
}
```
通过上述请求，我们可以获取到符合条件的销售退换管理记录。接下来，需要对返回的数据进行清洗和初步处理，以便后续的数据转换与写入阶段。
#### 数据清洗与过滤
根据元数据中的条件配置，我们需要对返回的数据进行过滤。例如，需要排除特定仓库编号的数据：
```json
"condition":[
{"field":"return_warehouse_no","logic":"neqv2","value":"CK002"},
{"field":"return_warehouse_no","logic":"neqv2","value":"110008204"},
{"field":"return_warehouse_no","logic":"neqv2","value":"110021826"},
{"field":"return_warehouse_no","logic":"neqv2","value":"110030137"},
{"field":"return_warehouse_no","logic":"neqv2","value":"CK003"},
{"field":"return_warehouse_no","logic":"neqv2","value":"04"},
{"field":"warehouse_no","logic":"neqv2","value":"CK003"},
{"field":"return_warehouse_no","logic":"notnull"}
]
```
这些条件确保了我们只保留符合业务需求的数据记录，从而提高了数据处理的准确性和效率。
#### 异常处理与补救措施
在实际操作中，不可避免地会遇到一些异常情况，如网络波动导致请求失败、部分数据缺失等。为了应对这些问题，可以设置定时任务（crontab）或接管请求（takeOverRequest）来自动补救遗漏的数据。
```json
"omissionRemedy":{
"crontab":null,
"takeOverRequest":[]
}
```
通过上述配置，可以确保即使在出现异常情况下，也能及时补充缺失的数据，保证整体数据集成过程的完整性和可靠性。
综上所述，通过合理配置元数据并调用旺店通·旗舰奇门接口`wdt.aftersales.refund.refund.search`，我们能够高效地获取并清洗销售退换管理相关的数据，为后续的数据转换与写入打下坚实基础。这一过程不仅提升了业务透明度和效率，还为实现不同系统间的数据无缝对接提供了有力支持。
### 使用轻易云数据集成平台进行ETL转换并写入金蝶云星空API接口
在数据集成生命周期的第二步，我们需要将已经集成的源平台数据进行ETL（提取、转换、加载）转换，转为目标平台金蝶云星空API接口所能够接收的格式，最终写入目标平台。以下是详细的技术实现过程。
#### 1. API 接口配置
我们首先需要配置金蝶云星空API接口的元数据。根据提供的元数据配置，我们使用`batchSave` API，通过POST方法进行数据写入。以下是主要字段和其解析方式：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 20,
"method": "batchArraySave"
},
...
}
```
#### 2. 请求参数解析
在请求参数中，我们需要特别注意字段解析和转换，这些字段包括单据类型、单据编号、库存组织、销售组织等。以下是一些关键字段及其解析方式：
- **单据类型 (`FBillTypeID`)**: 固定值 `XSTHD01_SYS`
- **单据编号 (`FBillNo`)**: 动态值 `{refund_no}`
- **库存组织 (`FStockOrgId`)** 和 **销售组织 (`FSaleOrgId`)**: 使用 `_mongoQuery` 查询来获取相应的值，并通过 `ConvertObjectParser` 转换为金蝶云星空所需格式。
```json
{
"field": "FBillTypeID",
"label": "单据类型",
"type": "string",
"describe": "单据类型",
"parser": {
"name": "ConvertObjectParser",
"params": "FNumber"
},
"value": "XSTHD01_SYS"
},
{
...
}
```
#### 3. 数据转换逻辑
对于复杂的数据结构，如明细信息（`FEntity`）和财务信息（`SubHeadEntity`），我们需要逐层解析并转换。例如，明细信息包含多个子字段，如物料编码、实退数量、含税单价等，每个子字段都需要通过特定的解析器进行处理。
```json
{
"field": "FEntity",
...
"children": [
{
...
{
"field": "FMaterialId",
...
"value": "{{details_list.spec_no}}"
},
{
...
"value": "{{details_list.refund_num}}"
},
{
...
"_function round({actual_refund_amount}/{return_goods_count},10)"
}
}
...
]
}
```
#### 4. 特殊字段处理
有些字段如日期（`FDate`）、备注（`FHeadNote`）等，需要通过特定函数或模板语言进行动态赋值。例如，日期字段可以通过模板语言 `{{modified|datetime}}` 来自动生成当前时间。
```json
{
...
{
"field": "FDate",
...
"value": "{{modified|datetime}}"
},
{
...
{
...
"_function round({actual_refund_amount}/{return_goods_count},10)"
}
...
}
```
#### 5. 最终请求生成
根据上述配置和转换逻辑，我们最终生成一个符合金蝶云星空API要求的请求体，并通过POST方法发送到目标平台，实现数据的写入。
```json
{
...
// 完整的请求体结构
}
```
以上是使用轻易云数据集成平台进行ETL转换并写入金蝶云星空API接口的详细技术实现过程。通过合理配置元数据和解析逻辑，可以确保数据准确无误地传输到目标系统，提高业务流程的自动化和效率。
