### 案例分享：旺店通销售退货单与金蝶云星空退货通知单的系统对接
在企业日常运营中，数据集成和管理的复杂性日益增加。为了确保业务流程高效、数据准确，系统间的数据对接显得尤为重要。本案例将聚焦于如何利用轻易云数据集成平台，实现旺店通·企业奇门销售退货单的数据精准无误地集成到金蝶云星空。
首先，我们需要调用**旺店通·企业奇门接口wdt.stockin.order.query.refund**来获取最新的销售退货单信息。在这个过程中，我们必须解决分页和限流的问题，以避免因大量数据请求而导致接口超时或失败。同时，通过定时任务可靠抓取这些接口数据，可以保证我们获取到最新、最全的信息，从而不漏单。
接下来，为了将获取到的数据快速且批量写入金蝶云星空，我们要使用其提供的**batchSave API**。这一步要求我们处理好两端不同的数据格式差异及映射关系。例如，针对字段名、数据类型等不同点，需要进行相应转换。此外，还需要注意对接过程中的异常情况处理，如网络问题或服务端响应错误。这就涉及到了实现错误重试机制，以尽可能减少人工干预，提高自动化程度。
整个流程会受到实时监控与日志记录支持，这样能确保每个环节都清晰透明，同时可以及时发现并解决潜在问题，提升整体效率和稳定性，并能够在需要时追溯具体操作步骤。从此角度出发，可极大提高业务透明度并降低运维成本。
这种集成方案通过精细设计和有效执行，不仅优化了跨系统之间的数据流转，更增强了各业务环节间的协同能力，为后续扩展功能奠定坚实基础。在本文随后的章节中，将详细探讨从API调用参数配置，到语言脚本编写，再到实际运行效果反馈的一整套实施细节。
### 调用源系统旺店通·企业奇门接口wdt.stockin.order.query.refund获取并加工数据
在数据集成生命周期的第一步，我们需要调用源系统的API接口以获取原始数据，并对其进行初步处理。本文将详细探讨如何通过轻易云数据集成平台调用旺店通·企业奇门接口`wdt.stockin.order.query.refund`，并对返回的数据进行加工处理。
#### 接口调用配置
首先，我们需要配置元数据，以便正确调用API接口。以下是元数据配置的关键字段及其含义：
- `api`: `"wdt.stockin.order.query.refund"` - 指定要调用的API接口。
- `effect`: `"QUERY"` - 表示这是一个查询操作。
- `method`: `"POST"` - 使用POST方法进行请求。
- `number`, `id`, `name`: 分别指定了订单号和入库单ID等字段，用于标识和关联数据。
- `idCheck`: `true` - 启用ID检查，确保数据唯一性。
- `formatResponse`: 定义了返回结果中需要格式化的字段，例如将`created_time`转换为新的字段`created_time_new`并格式化为日期类型。
- `joinBatch`: `"wdt.stockin.batch.detail"` - 指定批量处理时使用的关联表。
- `request`: 定义了请求参数，包括开始时间、结束时间、状态和店铺编号等。
- `otherRequest`: 包含分页参数，如每页大小和页号。
- `autoFillResponse`: `true` - 自动填充响应结果中的缺失字段。
- `beatFlat`: 定义了需要扁平化处理的嵌套列表字段，如`details_list`和`_batch_list`。
- `condition`: 定义了过滤条件，例如只获取价格为0的数据。
#### 请求参数设置
在实际调用过程中，我们需要设置请求参数，以确保获取到符合要求的数据。以下是主要的请求参数及其设置：
1. **开始时间 (`start_time`)** 和 **结束时间 (`end_time`)**:
```json
{
"field": "start_time",
"label": "开始时间",
"type": "datetime",
"describe": "增量获取数据，start_time作为开始时间，格式：yyyy-MM-dd HH:mm:ss",
"value": "{{LAST_SYNC_TIME|datetime}}"
},
{
"field": "end_time",
"label": "结束时间",
"type": "datetime",
"describe": "增量获取数据，end_time作为结束时间，格式：yyyy-MM-dd HH:mm:ss",
"value": "{{CURRENT_TIME|datetime}}"
}
```
这些参数用于指定查询的时间范围，通过模板变量动态生成。
2. **状态 (`status`)**:
```json
{
"field": "status",
"label": "状态",
"type": "string",
"describe": "入库单状态 10已取消20编辑中30待审核60待结算80已完成（默认查询80已完成单据）",
"value": "80"
}
```
默认查询已完成的单据（状态码80）。
3. **店铺编号 (`shop_nos`)**:
```json
{
"field": "shop_nos",
"label": "店铺编号（批量）",
"type": "string",
"describe": "代表店铺所有属性的唯一编码，用于店铺区分，ERP内支持自定义（ERP店铺界面设置），用于获取指定店铺单据数据信息",
"value": ["002", ... ,0093]
}
```
用于指定多个店铺编号，以获取相关店铺的数据。
4. **分页参数 (`page_size`, `page_no`)**:
```json
{
"field": "page_size",
...
...
}
```
#### 数据处理与转换
在成功获取到原始数据后，需要对其进行初步处理和转换。以下是一些关键步骤：
1. **格式化响应字段**:
将返回结果中的`created_time`字段转换为新的字段`created_time_new`并格式化为日期类型：
```json
{
...
{"old":"created_time","new":"created_time_new","format":"date"}
...
}
```
2. **扁平化嵌套列表**:
对嵌套列表如`details_list`和`_batch_list`进行扁平化处理，以便后续的数据处理更加方便：
```json
{
...
["details_list","_batch_list"]
...
}
```
3. **过滤条件**:
仅保留价格为0的数据：
```json
{
...
[{"field":"details_list.src_price","logic":"eqv2","value":"0"}]
...
}
```
通过上述步骤，我们可以高效地从旺店通·企业奇门接口中获取所需的数据，并对其进行初步加工，为后续的数据转换与写入阶段打下坚实基础。
### 将源平台数据转换并写入金蝶云星空API接口的技术案例
在轻易云数据集成平台中，ETL（提取、转换、加载）过程是数据集成生命周期的关键步骤之一。本文将详细探讨如何将已经集成的源平台数据进行ETL转换，转为金蝶云星空API接口所能够接收的格式，并最终写入目标平台。
#### 数据转换与写入配置
在这个案例中，我们需要将旺店通销售退货单的数据转换为金蝶云星空退货通知单的数据格式。元数据配置如下：
```json
{
"api": "batchSave",
"effect": "EXECUTE",
"method": "POST",
"operation": {
"method": "merge",
"field": "shop_no,created_time_new",
"bodyName": "list",
"bodySum": ["details_list__batch_list_num"],
"header": ["shop_no", "created_time_new", "logistics_no", "refund_remark"],
"body": ["details_list_goods_no", "details_list__batch_list_num",
"details_list_goods_unit", "details_list_remark",
"warehouse_no", "details_list__batch_list_batch",
"details_list_src_price"]
},
"idCheck": true,
...
}
```
#### 请求字段解析与映射
在配置中，我们定义了多个字段的解析和映射规则。以下是几个关键字段的解析示例：
- **FBillTypeID**: 单据类型，固定值为`THTZD01_SYS`。
- **FRetorgId**: 库存组织，通过`ConvertObjectParser`解析器，将`shop_no`映射到库存组织编码。
- **FSaleOrgId**: 销售组织，同样通过`ConvertObjectParser`解析器，将`shop_no`映射到销售组织编码。
- **FDate**: 日期，直接使用源数据中的`created_time_new`。
这些字段的解析和映射规则确保了源数据能够正确转换为目标系统所需的格式。
#### 明细信息处理
对于明细信息，我们使用了嵌套结构来处理。每个明细项包含多个字段，如物料编码、销售数量、基本单位等。这些字段通过类似的解析和映射规则进行处理。例如：
```json
{
...
{
"field": "FMaterialId",
"label": "物料编码",
"type": "string",
...
"value": "{{list.details_list_goods_no}}"
},
{
...
}
}
```
这种嵌套结构允许我们灵活地处理复杂的数据结构，并确保每个明细项都能正确映射到目标系统。
#### 特殊字段处理
某些字段需要特殊处理，例如销售组和仓库字段。我们使用了函数表达式来根据不同条件设置这些字段的值：
```json
{
...
{
...
{
...
"_function case when '{shop_no}' in ('005', '006', '007','0081', '0091') then 'dz1.2.3.01' when '{shop_no}' in ('002', '003', '004','0072') then '1.2.3.01' when '{shop_no}' in ('0082','0093') then 'rz1.2.3.01' end"
...
}
},
{
...
"_function case '{warehouse_no}' when 'CK077' then 'CK077' when 'CK078' then 'CK078' else '{warehouse_no}' end"
...
}
}
```
这种方式确保了根据不同条件动态生成目标值，从而满足业务需求。
#### 数据请求与提交
最后，我们将所有配置好的数据通过POST请求提交到金蝶云星空API接口：
```json
{
...
{
...
{"field":"FormId","label":"表单对象","type":"string","describe":"表单对象","value":"SAL_RETURNNOTICE"},
{"field":"Operation","label":"执行的操作","type":"string","describe":"执行的操作","value":"BatchSave"},
{"field":"IsAutoSubmitAndAudit","label":"提交并审核","type":"bool","describe":"提交并审核","value":"true"},
{"field":"IsVerifyBaseDataField","label":"验证基础资料","type":"bool","describe":"是否验证所有的基础资料有效性，布尔类，默认false（非必录）","value":"true"}
}
}
```
这些配置确保了数据能够自动提交并审核，同时验证所有基础资料的有效性。
通过上述步骤，我们成功地将源平台的数据转换为金蝶云星空API接口所需的格式，并顺利写入目标平台。这一过程不仅提高了数据处理效率，还保证了数据的一致性和准确性。
