### 旺店通·旗舰奇门数据集成到金蝶云星空：柏为采购退料单08.03技术方案分享
在本案例中，重点介绍如何通过轻易云数据集成平台，将旺店通·旗舰奇门的数据高效且无缝地集成到金蝶云星空系统中。具体来说，我们将利用wdt.wms.stockout.purchasereturn.querywithdetail这个API接口，从旺店通·旗舰奇门获取采购退料单的详细信息，并通过batchSave API接口写入到金蝶云星空，实现跨系统的数据同步。
#### 主要挑战与解决方案
1. **定时可靠的抓取和大量数据快速写入**：
我们设置了定时任务，以确保能够实时从旺店通·旗舰奇门接口抓取最新的采购退料数据。此外，通过轻易云的平台支持的大吞吐量数据写入能力，大批量的数据可以迅速、高效地注入到金蝶云星空，提高了整体处理效率。
2. **分页和限流问题**：
在调用wdt.wms.stockout.purchasereturn.querywithdetail API时，必须考虑分页机制以及接口的限流策略。我们采用了自动分页处理逻辑，并结合重试机制，确保每一次调用都能成功获取完整的数据，而不会因超出API限制而导致漏单情况发生。
3. **数据格式差异与自定义转换逻辑**：
由于两个系统之间存在较大的数据结构差异，我们设计了一套自定义的数据转换规则。在这一过程中，通过可视化的数据流设计工具，使得整个映射过程变得直观，可控。同时，还对某些字段进行了特定业务需求下的个性化转换，以满足多样化的应用场景。
4. **异常检测与错误重试机制**：
为保证系统稳定性及容错能力，我们引入了全面的监控和告警体系。一旦出现任何异常，无论是网络问题还是其他故障，都能第一时间捕捉并触发预设的错误重试机制。这不仅减少了人为干预，更提升了任务执行的一致性和可靠性。
5. **实时监控与日志记录**：
利用集中式监控系统，对整个数据集成流程进行实时跟踪，包括每次API请求响应时间、状态码等关键指标。同时，还实现了详尽的日志记录功能，为后续的问题排查提供有力依据。
此开篇部分阐述了一些核心技术要点及解决方案，接下来将逐步展开具体操作步骤和技术细节。
### 调用旺店通·旗舰奇门接口wdt.wms.stockout.purchasereturn.querywithdetail获取并加工数据
在数据集成的生命周期中，调用源系统API接口是至关重要的一步。本文将深入探讨如何通过轻易云数据集成平台调用旺店通·旗舰奇门接口`wdt.wms.stockout.purchasereturn.querywithdetail`，并对获取的数据进行初步加工。
#### 接口配置与调用
首先，我们需要配置元数据以便正确调用接口。根据提供的元数据配置，我们可以看到该接口使用POST方法，并且需要传递查询参数和分页信息。
```json
{
"api": "wdt.wms.stockout.purchasereturn.querywithdetail",
"method": "POST",
"number": "order_no",
"id": "stockout_id",
"idCheck": true,
"request": [
{
"field": "params",
"label": "查询参数",
"type": "object",
"describe": "查询参数",
"children": [
{"field": "status", "label": "出库单状态", "type": "string",
"describe": "由逗号分隔的整数数组\n\n出库单状态: \n5已取消 \n48 未确认 \n50 待审核\n77 拣货中,PDA拣货后\n110已完成",
"parent":"params"},
{"field": "stockout_no", "label": "出库单号",
"type": "string",
"describe":"出库单号",
"parent":"params"},
{"field":"out_start_time","label":"开始时间","type":"string","describe":"起始时间（出库时间），若无出库单号或采购退货单号，则为必填。","value":"{{LAST_SYNC_TIME|datetime}}","parent":"params"},
{"field":"warehouse_no","label":"仓库编号","type":"string","describe":"限普通仓库","parent":"params"},
{"field":"src_order_no","label":"采购退货单号","type":"string","describe":"采购退货单号","parent":"params"},
{"field":"out_end_time","label":"结束时间","type":"string","describe":"结束时间（出库时间），上同开始时间","value":"{{CURRENT_TIME|datetime}}","parent":"params"},
{"field":"create_start_time","label":"开始时间","type":"string","describe":"起始时间（出库单创建时间），若无出库单号或采购退货单号，则为必填。","parent":"params"},
{"field":"create_end_time","label":"结束时间","type":"string","describe":"结束时间（出库单创建时间），上同开始时间","parent":"params"},
{"field":"position","label":"是否按货位分组","type":"string","describe":"等于0为否，不等于0为是，不填为否","parent":"params"}
]
},
{
"field": "pager",
"label": "分页",
"type": "object",
"describe": "分页",
...
}
]
}
```
#### 查询参数设置
为了确保我们能够准确地获取所需数据，查询参数的设置至关重要。以下是一些关键字段及其含义：
- `status`: 出库单状态，可以是多个状态值的组合，例如`"48,50,77"`表示未确认、待审核和拣货中。
- `stockout_no`: 出库单号，用于精确查询特定的出库单。
- `out_start_time` 和 `out_end_time`: 出库操作的起止时间，通常使用上次同步时间和当前时间来限定范围。
- `warehouse_no`: 仓库编号，仅限普通仓库。
- `src_order_no`: 采购退货单号，用于精确查询特定的采购退货记录。
- `create_start_time` 和 `create_end_time`: 出库单创建的起止时间。
例如，我们可以设置如下参数来获取最近一次同步后的所有待审核和拣货中的采购退料记录：
```json
{
...
{
field: 'params',
value: {
status: '50,77',
out_start_time: '{{LAST_SYNC_TIME|datetime}}',
out_end_time: '{{CURRENT_TIME|datetime}}'
}
},
...
}
```
#### 分页处理
由于返回的数据量可能较大，需要进行分页处理。分页信息包括：
- `page_size`: 每页返回的数据条数，默认值为50。
- `page_no`: 页码，从0开始。
在实际应用中，可以通过循环调用接口并递增`page_no`来获取所有数据。例如：
```json
{
...
{
field: 'pager',
value: {
page_size: '50',
page_no: '0'
}
},
...
}
```
#### 数据清洗与转换
在成功获取数据后，需要对原始数据进行清洗和转换，以便后续处理。例如，可以对日期格式进行标准化，对数值字段进行单位转换等。
假设我们获取到如下JSON格式的数据：
```json
{
...
data: [
{
stockout_id: '12345',
order_no: 'PO123456789',
status: '50',
warehouse_no: 'WH001',
create_time: '2023-08-03T10:00:00Z'
},
...
]
}
```
我们可以将`create_time`字段转换为本地时区，并将状态码转换为对应的描述文本：
```python
import datetime
def transform_data(data):
for record in data:
# 转换日期格式
utc_dt = datetime.datetime.strptime(record['create_time'], '%Y-%m-%dT%H:%M:%SZ')
local_dt = utc_dt.astimezone()
record['create_time'] = local_dt.strftime('%Y-%m-%d %H:%M:%S')
# 转换状态码
status_map = {'50': '待审核', '77': '拣货中'}
record['status'] = status_map.get(record['status'], record['status'])
return data
```
通过上述步骤，我们可以确保从旺店通·旗舰奇门接口获取的数据经过清洗和转换后，能够满足业务需求，并为后续的数据写入和分析奠定基础。
### 使用轻易云数据集成平台将采购退料单数据转换并写入金蝶云星空API接口
在轻易云数据集成平台中，数据处理的第二步是将已经集成的源平台数据进行ETL转换，并转为目标平台所能接收的格式。本文将详细探讨如何将采购退料单的数据转换为金蝶云星空API接口所能接收的格式，并最终写入目标平台。
#### API接口配置
首先，我们需要配置金蝶云星空的API接口。根据元数据配置，我们使用的是`batchSave` API，方法为`POST`。以下是具体的配置参数：
```json
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 20,
"method": "batchArraySave"
},
"request": [
{
"field": "FBillTypeID",
"label": "单据类型",
"type": "string",
...
},
...
],
...
}
```
#### 数据字段映射与转换
在ETL过程中，我们需要将源数据字段映射到目标平台所需的字段，并进行必要的转换。例如，`FBillTypeID`字段需要从源系统中查找并转换为金蝶云星空所需的格式：
```json
{
"field": "FBillTypeID",
"label": "单据类型",
"type": "string",
"describe": "单据编号",
"value": "_findCollection find FBillTypeID_Fnumber from 8cb4eb44-4a1c-3ce3-8baf-06119d676182 where FBillNo={src_order_no}",
...
}
```
这里使用了`_findCollection`函数，通过指定条件从源系统中查找相应的数据，并使用`ConvertObjectParser`进行解析和转换。
#### 明细信息处理
对于明细信息（如物料编码、实退数量等），我们需要逐条处理并映射到目标系统的相应字段。例如，物料编码（FMATERIALID）的配置如下：
```json
{
"field": "FMATERIALID",
"label": "物料编码",
"type": "string",
...
}
```
通过指定父节点（FPURMRBENTRY），我们可以确保这些明细信息被正确地嵌套在主记录中。
#### 特殊字段处理
某些字段可能需要特殊处理，例如货主（FOWNERID）和税率（FENTRYTAXRATE）。这些字段通常需要从多个条件中查找并组合结果：
```json
{
...
{
"field": "FOWNERID",
...
"value": "_findCollection find FRequireOrgId_Fnumber from ... where FBillNo={src_order_no} FMATERIALID_Fnumber={{details_list.spec_no}}"
},
{
...
{
"field": "FENTRYTAXRATE",
...
"value": "_findCollection find FEntryTaxRate from ... where FBillNo={src_order_no} FMATERIALID_Fnumber={{details_list.spec_no}}"
}
}
```
#### 提交与审核
最后，在完成所有数据转换后，我们可以通过设置`IsAutoSubmitAndAudit`参数来自动提交并审核这些数据：
```json
{
...
{
"field": "IsAutoSubmitAndAudit",
...
{"value":"true"}
}
```
#### 完整请求示例
以下是一个完整的请求示例，用于将采购退料单的数据写入金蝶云星空：
```json
{
"FormId":"PUR_MRB",
"Operation":"batchSave",
"IsAutoSubmitAndAudit":"true",
"IsVerifyBaseDataField":"false",
"SubSystemId":"21",
"InterationFlags":"STK_InvCheckResult"
...
}
```
通过上述配置和操作，我们可以确保源系统的数据被正确地转换并写入到金蝶云星空，实现不同系统间的数据无缝对接。
