### 正常线上退货对接销售退货单---奇门
在本案例中，我们将详细分析如何实现聚水潭·奇门数据集成到金蝶云星空，并具体探讨两个系统对接的技术细节。本次任务的核心是通过轻易云平台，高效、可靠地实现正常线上退货的数据从聚水潭·奇门自动传输至金蝶云星空，生成相应的销售退货单。
#### 确保集成不漏单
首先，通过调用聚水潭·奇门API `jushuitan.refund.list.query` 获取退款信息。为了确保每一笔退款都被准确抓取，我们需要定时可靠地轮询接口，同时处理分页和限流问题。特别是在大批量数据获取过程中，合理设置分页参数并加入限流机制，以避免超出接口请求限制。
```json
{
"method": "jushuitan.refund.list.query",
...
}
```
#### 批量快速写入金蝶云星空
取得数据后，下一步是利用金蝶云星空提供的 `batchSave` API 将这些数据迅速写入到目标系统。这一步不仅要考虑效率，更要注意数据格式差异的映射与转换。例如，表字段命名不一致或日期格式不同的问题，都需提前在映射规则中妥善处理。
```json
{
"method": "batchSave",
...
}
```
#### 实施实时监控与错误重试机制
为保证整个流程透明可视且具备高容错性，在集成过程中我们采取了实时监控和日志记录手段，对每一步骤进行动态追踪。当发生异常时，立即触发错误重试机制，使流程能够自愈。例如，当连接失败或写入冲突时，会自动重新尝试操作直至成功，这样有效增加了系统的鲁棒性和稳定性。
此过程不仅解决了企业在日常运营中的诸多痛点，还为以后的扩展提供了坚实基础。在文章后续部分，我们将深入解析每一步骤中的关键技术实现及优化方案，包括详细代码示例和注意事项等。
### 调用聚水潭·奇门接口jushuitan.refund.list.query获取并加工数据
在数据集成的生命周期中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用聚水潭·奇门接口`jushuitan.refund.list.query`来获取并加工数据。
#### 接口概述
`jushuitan.refund.list.query`接口用于查询退货单信息。通过该接口，我们可以获取到售后单的详细信息，包括售后类型、货物状态等。以下是元数据配置中的关键字段和参数：
- **api**: `jushuitan.refund.list.query`
- **method**: `POST`
- **number**: `as_id`
- **id**: `as_id`
- **request**: 请求参数列表
- **condition**: 数据过滤条件
#### 请求参数配置
在调用接口时，需要配置一系列请求参数，以确保能够准确地获取所需的数据。以下是主要的请求参数及其配置：
1. **page_index（页码）**
- 类型：string
- 描述：页码默认1
- 值：`{PAGINATION_START_PAGE}`
2. **page_size（页数）**
- 类型：string
- 描述：页数
- 值：`{PAGINATION_PAGE_SIZE}`
3. **start_time（开始时间）**
- 类型：datetime
- 描述：开始时间
- 值：`{{LAST_SYNC_TIME|datetime}}`
4. **end_time（结束时间）**
- 类型：datetime
- 描述：结束时间
- 值：`{{CURRENT_TIME|datetime}}`
5. **status（售后单状态）**
- 类型：string
6. **type（售后类型）**
- 类型：string
7. **good_status（货物状态）**
- 类型：string
- 值：`SELLER_RECEIVED`
这些参数确保了我们能够分页获取特定时间段内的退货单信息，并且可以根据售后单状态、售后类型和货物状态进行筛选。
#### 数据过滤条件
为了确保数据的准确性和有效性，我们需要设置一些过滤条件。元数据配置中定义了两个主要的过滤条件：
1. **condition_bk**
2. **condition**
这两个条件实际上是相同的，具体如下：
```json
[
{"field":"o_id","logic":"neq","value":-1},
{"field":"items.r_qty","logic":"gt","value":0}
]
```
这些条件确保了我们只获取有效的订单，即订单ID不等于-1，并且退货数量大于0。
#### 数据处理与清洗
在获取到原始数据后，需要对数据进行清洗和转换，以便后续的数据写入操作。在轻易云平台上，可以利用自动填充响应功能（autoFillResponse），将API返回的数据直接映射到目标系统中。
例如，对于返回的退货单信息，可以根据业务需求进行如下处理：
1. 提取必要字段，如订单ID、商品名称、退货数量等。
2. 对日期格式进行标准化处理。
3. 根据业务规则，对某些字段进行计算或转换。
#### 实践案例
假设我们需要从聚水潭·奇门系统中获取2023年10月1日至2023年10月31日之间所有已收到货物的退货单信息，并将其写入到我们的销售退货单系统中。具体步骤如下：
1. 配置请求参数：
```json
{
"page_index": "1",
"page_size": "100",
"start_time": "2023-10-01T00:00:00",
"end_time": "2023-10-31T23:59:59",
"good_status": "SELLER_RECEIVED"
}
```
2. 设置过滤条件：
```json
[
{"field":"o_id","logic":"neq","value":-1},
{"field":"items.r_qty","logic":"gt","value":0}
]
```
3. 调用接口并处理返回的数据，根据业务需求进行清洗和转换。
通过上述步骤，我们可以高效地从聚水潭·奇门系统中获取所需的退货单信息，并将其无缝集成到我们的销售退货单系统中。这不仅提升了数据处理效率，还保证了数据的一致性和准确性。
### 利用轻易云数据集成平台将源数据转换为金蝶云星空API接口格式并写入目标平台
在数据集成生命周期的第二阶段，我们需要将已经集成的源平台数据进行ETL（提取、转换、加载）处理，转化为金蝶云星空API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨这一过程中的技术细节和实现方法。
#### 1. 数据请求与清洗
首先，我们需要从源系统中提取相关数据，并进行初步清洗。假设我们已经完成了这一步，接下来进入关键的ETL转换阶段。
#### 2. 数据转换与写入
在数据转换阶段，我们利用轻易云的数据集成平台，将提取到的数据按照金蝶云星空API接口的要求进行格式化处理。以下是具体的元数据配置示例：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 1,
"method": "batchArraySave"
},
"request": [
{
"field": "FBillTypeID",
"label": "单据类型",
"type": "string",
"describe": "单据类型",
"parser": {
"name": "ConvertObjectParser",
"params": "FNumber"
},
"value": "XSXSTHD"
},
{
...
}
],
...
}
```
#### 核心字段解析与转换
1. **单据类型 (FBillTypeID)**：
- 类型：字符串
- 描述：单据类型
- 转换器：`ConvertObjectParser`
- 参数：`FNumber`
- 值：`XSXSTHD`
2. **单据编号 (FBillNo)**：
- 类型：字符串
- 描述：单据编号
- 值：`{bfn_num}`
3. **销售组织 (FSaleOrgId)**：
- 类型：字符串
- 描述：组织
- 转换器：`ConvertObjectParser`
- 参数：`FNumber`
- 值：`_findCollection find F_XC_Base_Fnumber from ... where FNumber={shop_id}`
4. **日期 (FDate)**：
- 类型：字符串
- 描述：日期
- 值：`{items_receive_date}`
5. **库存组织 (FStockOrgId)**：
- 类型：字符串
- 描述：组织
- 转换器：`ConvertObjectParser`
- 参数：`FNumber`
- 值：`100`
6. **退货客户 (FRetcustId)**：
- 类型：字符串
- 描述：基础资料
- 转换器：`ConvertObjectParser`
- 参数：`FNumber`
- 值：`{shop_id}`
7. **备注 (FHeadNote)**：
- 类型：字符串
- 描述：多行文本
- 值：`{remark}`
8. **业务员 (F_XC_Text)**：
- 类型：字符串
- 描述：多行文本
- 值: `_findCollection find so_id from ... where o_id={o_id}`
#### 明细信息（FEntity）
明细信息部分包含多个子字段，每个子字段都需要进行相应的转换和映射。例如：
- **物料编码 (FMaterialId)**：
```json
{
"field": "FMaterialId",
"label": "物料编码",
...
"value": "{items_sku_id}",
...
}
```
- **实退数量 (FRealQty)**：
```json
{
...
"field": "FRealQty",
...
"value": "{items_r_qty}",
...
}
```
- **含税单价 (FTaxPrice)**：
```json
{
...
"field": "FTaxPrice",
...
"value": "_function {items_amount}/{items_r_qty}",
...
}
```
- **批号 (FLot)** 和**生产日期 (FProduceDate)**:
```json
{
...
{
...
field: 'FLot',
value: '_function case \'{wms_co_id}\' when \'12926523\' then \'230605\' else \'{items_batch_no}\' end',
parser: { name: 'ConvertObjectParser', params: 'FNumber' }
parent: 'FEntity'
},
{
field: 'FProduceDate',
value: '_function case \'{wms_co_id}\' when \'12926523\' then \'2023-06-06\' else \'{items_product_date}\' end',
parent: 'FEntity'
},
{
field: 'FExpiryDate',
value: '_function case \'{wms_co_id}\' when \'12926523\' then \'2026-06-05\' else \'{items_expiration_date}\' end'
},
}
```
这些字段通过条件判断和函数计算来确保不同仓库ID对应不同的批号、生产日期和有效期。
#### 财务信息（SubHeadEntity）
财务信息部分同样包含多个子字段，例如：
- **结算组织 (FSettleOrgId)**：
```json
{
"field":"FSettleOrgId",
"label":"结算组织",
"type":"string",
"describe":"组织",
"parser":{"name":"ConvertObjectParser","params":"FNumber"},
"value":"_findCollection find F_XC_Base_Fnumber from ... where FNumber={shop_id}",
"parent":"SubHeadEntity"
}
```
- **结算币别 (FSETTLECURRID)**：
```json
{
"field":"FSETTLECURRID",
"label":"结算币别",
"type":"string",
"describe":"基础资料",
"parser":{"name":"ConvertObjectParser","params":"FNumber"},
"value":"PRE001",
"parent":"SubHeadEntity"
}
```
#### 执行操作与写入目标平台
最后，通过配置以下参数来执行保存操作并自动提交审核：
```json
{
"otherRequest":[{"field":"FormId","label":"业务对象表单Id","type":"string","describe":"必须填写金蝶的表单ID如:PUR_PurchaseOrder","value":"SAL_RETURNSTOCK"},{"field":"Operation","label":"执行的操作","type":"string","value":"Save"},{"field":"IsAutoSubmitAndAudit","label":"提交并审核","type":"bool","value":"true"},{"field":"IsVerifyBaseDataField","label":"验证基础资料","type":"bool","describe":"是否验证所有的基础资料有效性，布尔类，默认false（非必录）","value":"false"},{"field":"SubSystemId","label":"系统模块","type":"string","describe":"默认仓库模块","value":"21"}]
}
```
通过以上配置，我们可以确保数据按照金蝶云星空API接口要求进行正确的格式化和转换，并成功写入目标平台。
