### 系统对接集成案例：汤臣倍健营销云数据到金蝶云星辰V2
在企业管理过程中，实时、准确的数据流动至关重要。本文将分享一个具体的技术案例，旨在展示如何实现汤臣倍健营销云与金蝶云星辰V2之间的数据集成。本次集成任务的具体方案命名为“采购入库同步（佰嘉）杭州佰健盛庆”，主要涉及两个API接口操作，即从汤臣倍健营销云获取数据的/erp/api/order/query/purInWarehsOrder接口，以及向金蝶云星辰V2写入数据的/jdy/v2/scm/pur_inbound接口。
为了有效处理这一任务，我们利用了高吞吐量的数据写入能力来确保大量采购入库数据能够快速传输。此外，通过集中监控和告警系统，我们可以实时跟踪每个步骤中的状态和性能，从而及时发现并解决潜在问题。这些特性不仅提升了整体效率，还极大地减少了漏单风险。
成功实施这个方案有几个关键技术要点：
1. **定时可靠抓取**：我们通过调度机制，定时调用汤臣倍健营销云接口，以保证源端最新的数据被持续且可靠地同步。
2. **批量数据处理**：针对大量采购订单，我们设计了一种批量处理策略，大幅提高了系统传输效率，并减少频繁请求带来的开销。
3. **分页和限流控制**：由于API请求可能存在分页和限流限制，我们特别针对这些问题进行了优化设计，以充分利用API资源，实现稳定、连续的数据采集过程。
4. **自定义转换逻辑与格式映射**：考虑到两个系统间可能存在不同的数据结构，需要应用自定义转换逻辑以适应目标端要求。在此过程中，通过可视化工具进行配置，使得复杂数据映射变得直观易懂。
5. **异常处理机制**：任何环节中出现的问题都可能导致整个流程失败，因此我们引入了完善的错误重试机制，对异常情况进行即时响应与修复。
紧接着将详细介绍各个步骤如何实现，包括代码样例、配置方法及注意事项等。此次集成项目不仅展示了强大的平台功能，更凸显出精准、高效解决业务需求的重要性。
### 调用源系统汤臣倍健营销云接口获取并加工数据
在轻易云数据集成平台的生命周期中，调用源系统接口是数据处理的第一步。本文将详细探讨如何通过调用汤臣倍健营销云的`/erp/api/order/query/purInWarehsOrder`接口来获取采购入库订单数据，并进行初步的数据加工。
#### 接口调用配置
首先，我们需要配置API接口的元数据。以下是该接口的元数据配置：
```json
{
"api": "/erp/api/order/query/purInWarehsOrder",
"effect": "QUERY",
"method": "POST",
"number": "number",
"id": "id",
"idCheck": true,
"request": [
{"field":"tenantId","label":"经销商id","type":"string","describe":"经销商id(必填,营销云id)如：08e2fd9d074f4ef7b5e6416b74d006d6","value":"xxx"},
{"field":"yxyNumber","label":"营销云销售订单号","type":"string","describe":"如：lzwhy0121012002，传此参数时，其他时间状态等条件无效"},
{"field":"number","label":"系统订单号","type":"string","describe":"如：CGDD00000003744，传此参数时,其他时间状态等条件无效"},
{"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-0000:00:00，如果不传单号此字段必填","value":"{{LAST_SYNC_TIME|datetime}}"},
{"field":"endTime","label":"结束时间","type":"string","describe":"timeType为空或者0，基于创建时间查询，timeType为1，基于更新时间查询，格式：0000-00-00或0000-00-0000: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,
"condition": [
[{"field": "itemList.materialNumber", "logic": "notlike", "value": "F.A"}]
]
}
```
#### 请求参数详解
在请求参数部分，我们需要特别注意以下几个关键字段：
1. **tenantId**: 经销商ID，这是一个必填项，用于标识具体的经销商。
2. **yxyNumber**和**number**: 分别代表营销云销售订单号和系统订单号，这两个字段如果传递，将会覆盖其他条件。
3. **status**: 用于过滤订单状态，这里我们设置为已审核（值为1）。
4. **beginTime**和**endTime**: 用于指定查询的时间范围。`beginTime`使用上次同步时间，而`endTime`使用当前时间。
5. **pageNo**和**pageSize**: 分页参数，用于控制每次请求返回的数据量。
#### 数据请求与清洗
在完成API调用后，我们将获取到原始的采购入库订单数据。接下来，需要对这些数据进行清洗和初步加工。以下是一个简单的数据清洗示例：
```python
import requests
import json
# 设置请求头
headers = {
'Content-Type': 'application/json'
}
# 构建请求体
payload = {
'tenantId': '08e2fd9d074f4ef7b5e6416b74d006d6',
'status': '1',
'beginTime': '2023-01-01T00:00:00',
'endTime': '2023-01-31T23:59:59',
'pageNo': '1',
'pageSize': '30',
'timeType': '1'
}
# 发起POST请求
response = requests.post('https://api.example.com/erp/api/order/query/purInWarehsOrder', headers=headers, data=json.dumps(payload))
# 检查响应状态码
if response.status_code == 200:
data = response.json()
# 数据清洗示例
cleaned_data = []
for item in data['items']:
if not item['materialNumber'].startswith('F.A'):
cleaned_data.append(item)
else:
print(f"Error: {response.status_code}")
# 输出清洗后的数据
print(cleaned_data)
```
在这个示例中，我们通过检查物料编号是否以“F.A”开头来过滤掉不需要的数据。
#### 数据转换与写入
经过清洗后的数据，需要进一步转换并写入目标系统。在轻易云平台中，可以通过配置相应的转换规则和目标连接器来实现这一过程。例如，可以将清洗后的数据转换为目标系统所需的格式，并通过API或数据库连接器写入到目标数据库中。
以上就是调用汤臣倍健营销云接口获取并加工采购入库订单数据的详细技术案例。通过合理配置元数据和编写清洗逻辑，可以高效地完成数据集成过程中的第一步，为后续的数据处理打下坚实基础。
### 采购入库同步至金蝶云星辰V2API接口的ETL转换与写入
在数据集成生命周期的第二步，我们需要将源平台的数据进行ETL（提取、转换、加载）处理，并最终写入目标平台——金蝶云星辰V2API接口。以下是详细的技术实现过程。
#### 数据请求与清洗
首先，我们从源平台提取原始数据，并进行必要的清洗和预处理。假设我们已经完成了这一阶段，现在我们专注于如何将这些数据转换为金蝶云星辰V2API所能接收的格式，并通过API接口写入目标平台。
#### 数据转换与写入
在这个阶段，我们使用轻易云数据集成平台提供的元数据配置来完成ETL过程。以下是具体的元数据配置及其应用细节：
```json
{
"api": "/jdy/v2/scm/pur_inbound",
"effect": "EXECUTE",
"method": "POST",
"number": "1",
"id": "1",
"name": "1",
"idCheck": true,
"request": [
{
"field": "bill_date",
"label": "单据日期",
"type": "string",
"describe": "单据日期",
"value": "{{auditTime|date}}"
},
{
"field": "bill_no",
"label": "单据编码",
"type": "string",
"describe": "单据编码"
},
{
"field": "transtype",
"label": "业务类型",
"type": "string",
"value": "2"
},
{
"field": "supplier_id",
...
}
]
}
```
##### 单据头信息字段映射
1. **单据日期（bill_date）**：
- 类型：字符串
- 描述：单据日期
- 值：`{{auditTime|date}}`
- 转换逻辑：将源数据中的审核时间字段格式化为日期字符串。
2. **单据编码（bill_no）**：
- 类型：字符串
- 描述：单据编码
- 值：直接映射源数据中的单据编码字段。
3. **业务类型（transtype）**：
- 类型：字符串
- 值：固定值`2`，表示采购入库业务类型。
4. **供应商编码（supplier_id）**：
- 类型：字符串
- 描述：供应商编码
- 值：固定值`1325910262712132608`，表示特定供应商。
5. **备注（remark）**：
- 类型：字符串
- 描述：备注信息
- 值：组合字段，格式为 `{remark}-来自营销云-{yxyNumber}`，其中 `remark` 和 `yxyNumber` 来自源数据。
##### 商品分录信息字段映射
商品分录信息是一个数组，每个元素代表一个商品条目。以下是具体字段及其映射：
1. **商品编码（material_number）**：
- 类型：字符串
- 描述：商品编码
- 值：源数据中的 `extMaterialNo` 字段。
2. **仓库编码（stock_id）**：
- 类型：字符串
- 描述：仓库编码
- 值：固定值 `1320321070951062528`。
3. **是否赠品（is_free）**：
- 类型：整数
- 描述：是否赠品
- 值：固定值 `false`，表示非赠品。
4. **数量（qty）**：
- 类型：字符串
- 描述：数量
- 值：源数据中的 `opernumber` 字段。
5. **单位（unit_id）**：
- 类型：字符串
- 描述：单位
- 值通过 `_findCollection` 函数从特定集合中查找对应的单位ID。
6. **批次号（batch_no）、生产日期（kf_date）、保质期天数（kf_period）、有效日期（valid_date）、保质期类型（kf_type）、含税单价（tax_price）、税率（cess）、价税合计（all_amount）** 等字段均根据元数据配置进行相应映射和计算。
##### API调用与写入
所有字段映射完成后，通过HTTP POST请求将转换后的JSON数据发送至金蝶云星辰V2API接口 `/jdy/v2/scm/pur_inbound`。请求体包含所有必要的字段及其对应值：
```json
{
...
}
```
通过这种方式，我们实现了从源平台到目标平台的数据无缝对接，确保每个环节的数据准确性和一致性。这不仅提高了业务效率，还增强了系统间的数据协同能力。
