### 汤臣倍健营销云与金蝶云星辰V2的退货入库系统对接案例分享
在本文中，我们将解析如何实现汤臣倍健营销云数据集成到金蝶云星辰V2，实现退货入库（佰嘉）杭州佰健嘉庆的业务场景。通过高效的数据写入能力、集中监控和告警系统以及灵活的数据转换逻辑，我们成功解决了数据集成中的关键问题，确保业务流程顺畅运行。
首先，利用汤臣倍健营销云提供的API接口`/erp/api/order/query/saleReturnOrder`，我们定时可靠地抓取销售退货订单数据。这一步至关重要，因为它涉及到分页处理和限流控制。在确保数据不漏单方面，我们设计了一套完善的数据质量监控机制，一旦检测到数据异常，即刻触发告警并执行错误重试机制。
其次，在将抓取到的数据批量写入金蝶云星辰V2之前，需要处理两者之间的数据格式差异。此时，自定义的数据转换逻辑显得尤为重要，通过精细化映射规则，将汤臣倍健营销云获取到的复杂多样的数据结构准确转化为金蝶云星辰V2所要求的标准格式，并通过API `/jdy/v2/scm/sal_in_bound`进行批量提交。
在整个过程中，可视化操作界面帮助我们追踪每一个环节，从数据提取、转换，再到最终写入，不仅大幅提升了工作效率，还极大程度上降低了出错概率。此外，我们还配置了实时监控和日志记录功能，对整体流程进行全方位跟踪，一旦出现任何异常情况，都能快速定位并修复，确保系统平稳运行。
接下来章节会详细介绍具体配置步骤及技术要点，让您深入了解这套完整、高效、安全的数据集成方案。
### 调用汤臣倍健营销云接口获取并加工数据
在数据集成的生命周期中，调用源系统接口是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用汤臣倍健营销云的`/erp/api/order/query/saleReturnOrder`接口，获取并加工退货入库数据。
#### 接口配置与请求参数
首先，我们需要配置元数据，以便正确调用API接口。以下是该接口的元数据配置：
```json
{
"api": "/erp/api/order/query/saleReturnOrder",
"effect": "QUERY",
"method": "POST",
"number": "number",
"id": "id",
"idCheck": true,
"request": [
{"field":"tenantId","label":"经销商id","type":"string","describe":"经销商id(必填,营销云id)如：34cc4109705e4c058b7b3b0352e57d31","value":"xxx"},
{"field":"yxyNumber","label":"营销云销售订单号","type":"string","describe":"如：YD1215710122031701，传此参数时，其他时间状态等条件无效"},
{"field":"number","label":"系统订单号","type":"string","describe":"如：XOUT0000000293，传此参数时,其他时间状态等条件无效"},
{"field":"status","label":"订单状态","type":"string","describe":"0:未审核 1：已审核（已出库）","value":"1"},
{"field":"beginTime","label":"开始时间","type":"string","describe":"timeType为空或者0，基于创建时间查询，timeType为1，基于更新时间查询，格式：0000-00-00或0000-00-00 00:00:00，如果不传单号此字段必填","value":"{{LAST_SYNC_TIME|datetime}}"},
{"field":"endTime","label":"结束时间","type":"string","describe":"timeType为空或者0，基于创建时间查询，timeType为1，基于更新时间查询，格式：0000-00-00或0000-00-00 00:00:00，如果不传单号此字段必填","value":"{{CURRENT_TIME|datetime}}"},
{"field":"pageNo","label":"页码","type":"string","describe":"默认1","value":"1"},
{"field":"pageSize","label":"每页条数","type":"string","describe":"默认30","value":"30"},
{"field":"timeType","label":"时间段标志","type":"string","describe":"查询时间段标识，0:创建时间（默认），1：最后更新时间","value":"1"}
],
"autoFillResponse": true
}
```
#### 请求参数详解
在调用API时，需要提供一系列请求参数：
- `tenantId`: 经销商ID，这是一个必填项，用于标识具体的经销商。
- `yxyNumber`: 营销云销售订单号，当传递此参数时，其它条件将被忽略。
- `number`: 系统订单号，同样地，当传递此参数时，其它条件将被忽略。
- `status`: 订单状态，这里我们设置为`1`表示已审核（已出库）。
- `beginTime`和`endTime`: 时间范围，用于限定查询的起止时间。这里使用动态变量`{{LAST_SYNC_TIME|datetime}}`和`{{CURRENT_TIME|datetime}}`来自动填充。
- `pageNo`: 页码，默认为`1`。
- `pageSize`: 每页条数，默认为`30`。
- `timeType`: 时间段标志，用于指定查询基于创建时间还是最后更新时间。
#### 数据请求与清洗
在发送请求后，我们会收到一组原始数据。这些数据需要经过清洗和转换，以便后续处理。以下是一个简单的数据清洗示例：
```python
import requests
import json
# 定义请求URL和头信息
url = 'https://api.example.com/erp/api/order/query/saleReturnOrder'
headers = {'Content-Type': 'application/json'}
# 构建请求体
payload = {
'tenantId': '34cc4109705e4c058b7b3b0352e57d31',
'status': '1',
'beginTime': '2023-01-01 00:00:00',
'endTime': '2023-01-31 23:59:59',
'pageNo': '1',
'pageSize': '30',
'timeType': '1'
}
# 发起POST请求
response = requests.post(url, headers=headers, data=json.dumps(payload))
# 检查响应状态码
if response.status_code == 200:
data = response.json()
# 数据清洗示例
cleaned_data = []
for order in data['orders']:
cleaned_order = {
'order_id': order['id'],
'order_number': order['number'],
'status': order['status'],
# 添加更多字段清洗逻辑...
}
cleaned_data.append(cleaned_order)
print(cleaned_data)
else:
print(f"Error: {response.status_code}")
```
#### 数据转换与写入
在完成数据清洗后，我们需要将其转换为目标系统所需的格式，并写入到相应的数据库或文件中。以下是一个简单的数据转换示例：
```python
import pandas as pd
# 将清洗后的数据转换为DataFrame
df = pd.DataFrame(cleaned_data)
# 转换为目标系统所需的格式，例如CSV文件
df.to_csv('cleaned_orders.csv', index=False)
```
通过上述步骤，我们成功实现了从汤臣倍健营销云获取退货入库数据，并进行了必要的数据清洗和转换，为后续的数据处理奠定了基础。
### 使用轻易云数据集成平台实现退货入库数据的ETL转换并写入金蝶云星辰V2
在数据集成的生命周期中，ETL（提取、转换、加载）是至关重要的一环。本文将详细探讨如何利用轻易云数据集成平台，将已集成的源平台数据进行ETL转换，并转为金蝶云星辰V2 API接口所能接收的格式，最终写入目标平台。
#### 1. 数据请求与清洗
在进行数据转换之前，首先需要确保从源系统获取的数据是准确和完整的。这一步骤包括了对数据的清洗和初步处理，以确保后续转换过程中的顺利进行。假设我们已经完成了这一阶段，接下来我们将重点放在数据转换与写入阶段。
#### 2. 数据转换与写入
为了将退货入库的数据正确地写入到金蝶云星辰V2，我们需要按照其API接口规范进行数据格式的转换。以下是具体的元数据配置及其应用解析：
```json
{
"api": "/jdy/v2/scm/sal_in_bound",
"effect": "EXECUTE",
"method": "POST",
"number": "id",
"id": "id",
"name": "id",
"idCheck": true,
"request": [
{"field":"bill_source","label":"来源","type":"string","value":"ISV"},
{"field":"bill_date","label":"出库日期","type":"string","describe":"出库日期,格式：2019-01-01","value":"{{auditTime|date}}"},
{"field":"customer_id","label":"客户","type":"string","describe":"客户","value":"_findCollection find id from b41660e7-fa00-318f-bbee-1395e229ee6b where number={extCusCode}"},
{"field":"remark","label":"单据备注","type":"string","describe":"上传的附件url","value":"{remark}-来自营销云-{number}"},
{"field":"contact_address","label":"联系信息-详细地址","type":"string","describe":"联系信息-详细地址","value":"{shippingAddress}"},
{"field":"contact_linkman","label":"联系信息-联系人","type":"string","describe":"联系信息-联系人","value":"{contacts}"},
{"field":"contact_phone","label":"联系信息-联系方式","type":"string","describe":"联系信息-联系方式","value":"{phone}"},
{"field":"dept_number","label":"部门编码","type":"string","describe":"业务员","value":"BM00003"},
{
"field": "material_entity",
"label": "商品分录",
"type": "array",
"describe": "商品分录",
"value": "itemList",
"children": [
{"field": "material_id", "label": "商品id", "type": "string", "describe": "商品id",
"value": "_findCollection find id from 395d1591-aee0-3f10-ad09-d5593167af48 where number={extMaterialNo}"},
{"field": "stock_id", "label": "仓库id",
"type": "string",
"describe": "仓库id",
"value":
"1320319669004973056"},
{"field":
"qty",
"label":
"数量",
"type":
"int",
"describe":
"数量",
"value":
"{{itemList.opernumber}}"},
{"field":
"tax_price",
"label":
"含税单价",
"type":
"int",
"describe":
"含税单价",
"value":
"{{itemList.taxunitprice}}"},
{"field":
"is_free",
"label":
"是否赠品",
"type":
"bool",
"describe":
"是否赠品",
"value":
false},
{"field":
"unit_id",
"label":
单位id, type: string, describe: 单位id, value: _findCollection find base_unit_id from 395d1591-aee0-3f10-ad09-d5593167af48 where number={extMaterialNo}},
{ field: batch_no, label: 批次号, type: string, describe: 批次号, value: {{itemList._Flot}}},
{ field: comment, label: 行备注, type: string, describe: 行备注, value: {{itemList.remark}}},
{ field: kf_date, label: 生产日期, type: string, describe: 生产日期, value: {{itemList._Fmfg}}},
{ field: valid_date, label: 有效日期, type: string, describe: 有效日期, value: {{itemList._Fexp}}},
{ field:
kf_period,
label:
保质期天数,
type:
string,
describe:
保质期天数,
value:
730},
{ field:
kf_type,
label:
保质期类型,
type:
string,
describe:
保质期类型，1：天，2：月，3：年,
value:
1}
]
}
]
}
```
#### 元数据配置解析
1. **基本字段**：
- `bill_source`：固定值`ISV`。
- `bill_date`：通过模板引擎将审核时间`auditTime`格式化为指定格式。
- `customer_id`：通过查找集合方法，根据外部客户编码`extCusCode`获取对应ID。
- `remark`：组合备注信息和营销云编号。
- `contact_address`, `contact_linkman`, `contact_phone`: 分别对应详细地址、联系人和联系方式。
2. **部门编码**：
- 固定值`BM00003`。
3. **商品分录**：
- 包含多个子字段，如商品ID、仓库ID、数量、含税单价等。每个子字段都通过模板引擎或查找集合方法获取具体值。例如：
- `material_id`: 根据外部物料编号`extMaterialNo`查找集合获取ID。
- `qty`: 从项列表中提取操作数量。
- `tax_price`: 从项列表中提取含税单价。
#### 数据写入
经过上述配置后，利用轻易云的数据集成平台，可以将处理后的数据通过POST请求发送到金蝶云星辰V2 API接口，实现退货入库的数据写入。
通过这种方式，我们不仅能够确保数据格式符合目标平台的要求，还能实现不同系统间的数据无缝对接，大大提升了业务流程的效率和透明度。
