### 销售出库单对接（非一件代发）-新组织：从旺店通·企业奇门到金蝶云星空的系统集成实践
在本次技术案例分享中，我们将聚焦于销售出库单数据如何通过轻易云数据集成平台，从旺店通·企业奇门无缝对接至金蝶云星空。此方案力求解决业务中的多个关键难点，包括确保数据不漏单、快速写入大量数据、以及处理接口分页和限流问题。
首先，需要实时获取从旺店通·企业奇门端导出的销售出库单信息。为了实现这一目标，我们使用了`wdt.stockout.order.query.trade` API接口，定时抓取相关数据，确保业务过程中的每一个订单都被准确记录。
紧接着，对于如何高效地将这些批量获取的数据集成到金蝶云星空，我们采用了其提供的`batchSave` API接口进行大规模的数据写入操作。在这一过程中，一方面需要处理两者间不同的数据格式差异，另一方面也需要应对潜在的系统异常。
针对异常处理与错误重试机制，该方案设计了一系列保障措施。当检测到API调用失败或网络故障时，会触发重试机制，以保证最终的一致性。同时，为便于后续问题追踪和优化调整，每一步操作都进行了详细日志记录，实现了全过程可监控管理。
本文所述技术方案不仅有效应对了跨系统间的大量数据同步需求，也极大提升了整体业务流程的可靠性和效率。以下章节将详细描述具体实施步骤，并介绍相关代码示例及配置细节。
### 调用旺店通·企业奇门接口wdt.stockout.order.query.trade获取并加工数据
在数据集成生命周期的第一步，我们需要调用源系统的API接口以获取原始数据。本文将详细探讨如何通过轻易云数据集成平台调用旺店通·企业奇门接口`wdt.stockout.order.query.trade`，并对获取的数据进行初步加工。
#### 接口调用配置
首先，我们需要配置API接口的元数据。根据提供的metadata，我们可以看到该接口使用POST方法进行请求，主要用于查询销售出库单信息。以下是关键字段及其配置：
- **api**: `wdt.stockout.order.query.trade`
- **method**: `POST`
- **number**: `order_no`
- **id**: `stockout_id`
- **name**: `order_no`
- **idCheck**: `true`
#### 请求参数
请求参数主要分为两类：时间范围和状态过滤，以及其他辅助参数。以下是详细配置：
1. **时间范围和状态过滤**
- **start_time**: 开始时间，格式为`yyyy-MM-dd HH:mm:ss`，用于增量获取数据。
- **end_time**: 结束时间，格式为`yyyy-MM-dd HH:mm:ss`。
- **status**: 状态过滤，包括已取消、已审核、已发货、部分打款、已完成和异常发货。
2. **其他辅助参数**
- **src_order_no**: 系统订单编号
- **src_tid**: 原始单号
- **stockout_no**: 出库单号
- **shop_no**: 店铺编号，用于区分不同店铺的数据。
- **warehouse_no**: 仓库编号，用于区分不同仓库的数据。
- **is_by_modified**: 是否按修改时间查询
分页参数也需要设置，以确保能够处理大批量数据：
- **page_size**: 每页返回的数据条数，默认值为40。
- **page_no**: 页号，从0页开始。
#### 数据请求与清洗
在发送请求后，我们会收到包含多个销售出库单的信息。这些信息需要经过初步清洗和转换，以便后续处理。以下是一些常见的清洗步骤：
1. **字段映射与转换**
将API返回的数据字段映射到目标系统所需的字段。例如，将`order_no`映射到目标系统的订单编号字段。
2. **数据过滤**
根据业务需求，对返回的数据进行过滤。例如，只保留特定状态（如已发货、已完成）的订单。
3. **去重处理**
对于重复的数据记录，需要进行去重处理，以确保数据的一致性和准确性。
#### 示例代码
以下是一个示例代码片段，用于调用API并处理返回的数据：
```python
import requests
import datetime
# 配置请求参数
params = {
"start_time": (datetime.datetime.now() - datetime.timedelta(days=1)).strftime('%Y-%m-%d %H:%M:%S'),
"end_time": datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
"status": "95,105,110,113",
"page_size": 40,
"page_no": 0,
}
# 发送请求
response = requests.post("https://api.wangdiantong.com/wdt.stockout.order.query.trade", data=params)
data = response.json()
# 数据清洗与转换
cleaned_data = []
for record in data['orders']:
if record['warehouse_no'] != 'WH' and record['fullname'] != '穆思乐' and record['shop_no'] in ['202009', '203003', '202006']:
cleaned_record = {
"订单编号": record['order_no'],
"出库单号": record['stockout_no'],
"店铺编号": record['shop_no'],
# 添加更多字段映射...
}
cleaned_data.append(cleaned_record)
# 输出清洗后的数据
print(cleaned_data)
```
通过上述步骤，我们成功地从旺店通·企业奇门接口获取了销售出库单信息，并进行了初步的数据清洗和转换，为后续的数据处理和写入做好了准备。这一步骤在整个数据集成生命周期中至关重要，确保了后续环节能够基于高质量的原始数据进行进一步操作。
### 数据集成生命周期中的ETL转换与写入：对接金蝶云星空API接口
在数据集成生命周期的第二步中，关键任务是将已经集成的源平台数据进行ETL（提取、转换、加载）转换，使其符合目标平台金蝶云星空API接口所能接收的格式，并最终写入目标平台。以下是详细的技术实现过程。
#### API接口配置
在本案例中，我们使用金蝶云星空的`batchSave` API接口，通过POST方法将销售出库单数据写入目标系统。元数据配置如下：
```json
{
"api": "batchSave",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{"field":"FBillTypeID","label":"单据类型","type":"string","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"XSCKD09_SYS"},
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","value":"{order_no}"},
{"field":"FDate","label":"日期","type":"string","describe":"日期","value":"{consign_time}"},
{"field":"FStockOrgId","label":"发货组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{shop_no}"},
{"field":"FSaleOrgId","label":"销售组织","type":"string","describe":"组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{shop_no}"},
{"field": "FOwnerTypeIdHead", "label": "货主类型", "type": "string", "describe": "货主类型", "value": "BD_OwnerOrg"},
{"field": "FOwnerIdHead", "label": "货主", "type": "string", "describe": "货主", "parser":{"name": "ConvertObjectParser", "params": "FNumber"}, "value": "{shop_no}"},
{"field": "FCustomerID", "label": "客户", "type": "string",
...
```
#### 数据字段解析与映射
1. **单据类型** (`FBillTypeID`): 使用固定值 `XSCKD09_SYS`，通过 `ConvertObjectParser` 转换为目标系统的编码。
2. **单据编号** (`FBillNo`): 从源数据中提取 `order_no` 字段。
3. **日期** (`FDate`): 提取 `consign_time` 字段。
4. **发货组织** (`FStockOrgId`) 和 **销售组织** (`FSaleOrgId`): 提取 `shop_no` 字段，并通过 `ConvertObjectParser` 转换为目标系统编码。
5. **货主类型** (`FOwnerTypeIdHead`) 和 **货主** (`FOwnerIdHead`): 固定值 `BD_OwnerOrg` 和 `shop_no`。
#### 子实体处理
1. **财务信息** (`SubHeadEntity`):
- **结算组织** (`FSettleOrgID`) 和 **结算币别** (`FSETTLECURRID`): 提取 `shop_no` 并转换，币别固定为人民币 `PRE001`。
2. **明细信息** (`FEntity`):
- 包含多个子字段，如物料编码、实发数量、含税单价等。每个字段都从源数据的 `details_list` 中提取并映射。例如:
- **物料编码** (`FMaterialID`) 从 `details_list.spec_no`
- **实发数量** (`FRealQty`) 从 `details_list.num`
- **含税单价** (`FTaxPrice`) 从 `details_list.sell_price`
- 特殊处理如是否赠品(`FIsFree`)和税率(`FEntryTaxRate`)需要根据条件动态计算。
#### 特殊处理逻辑
1. **是否赠品**: 根据价格判断，如果价格为0，则标记为赠品。
```json
{"field": "FIsFree",
...
```
2. **关联关系表**:
- 通过 `_mongoQuery` 动态查询源单内码和分录内码，实现数据关联。
```json
{"field":
...
```
#### 操作参数配置
- 表单ID(`FormId`)：设置为金蝶的业务对象表单ID，如 `SAL_OUTSTOCK`
- 执行操作(`Operation`)：设置为保存操作 `Save`
- 提交并审核(`IsAutoSubmitAndAudit`)：设置为true，确保数据提交后自动审核
- 验证基础资料(`IsVerifyBaseDataField`)：设置为true，确保所有基础资料有效性
- 系统模块(`SubSystemId`)：默认仓库模块21
- 允许负库存(`InterationFlags`)：设置为允许负库存 `STK_InvCheckResult`
通过上述配置和处理逻辑，可以实现从源平台到金蝶云星空的数据无缝对接，确保每个字段的数据准确传递和转换。这种全生命周期管理和透明化操作界面极大提升了业务效率和透明度。
