### 汤臣倍健营销云数据集成到金蝶云星辰V2：新版订单-出库单（佰嘉）杭州佰健盛庆方案
在本技术案例中，我们将详细介绍如何通过轻易云平台完成汤臣倍健营销云与金蝶云星辰V2的系统对接，实现数据的无缝高效集成。具体涉及到从汤臣倍健营销云获取订单数据并写入到金蝶云星辰V2，以及处理过程中所需关注的各种关键点和技术细节。
首先，针对汤臣倍健营销云的数据抓取，由于其接口`/api/openapi/v1/erp/order/honour/agreement/header`可能存在分页及限流问题，我们需要配置相应的定时任务，以确保可以可靠地、批量化地获取最新订单信息。同时，通过实时监控与日志记录，能够保证整个数据抓取过程不会遗漏任何一条有效信息，从而提升集成质量和可靠性。
在成功获取到原始订单数据后，需要考虑如何快速且稳定地将大量数据写入到目标系统金蝶云星辰V2。为了实现这一目的，可以调用其API `/jdy/v2/scm/sal_out_bound` 并进行适当的数据格式转换。特别是要注意解决两者之间的数据格式差异，这包括字段映射、类型转换以及可能出现的不一致性处理。
此外，为了防止由于网络波动或其他不可预见因素导致的数据传输错误，本方案还设计了异常处理与错误重试机制。一旦检测到某次操作失败，会自动触发重试逻辑，并且每一步操作都会有详细日志记录，方便事后追查和问题定位。
我们将在后续部分进一步深入探讨各个步骤中的具体实施方法，包括代码示例和配置截图等内容，以便为读者提供一个全面而清晰的指导路径。
### 调用汤臣倍健营销云接口获取并加工数据
在轻易云数据集成平台的生命周期中，调用源系统接口是数据处理的第一步。本文将深入探讨如何通过调用汤臣倍健营销云接口`/api/openapi/v1/erp/order/honour/agreement/header`来获取并加工数据。
#### 接口概述
该接口用于查询订单头信息，支持POST请求。元数据配置如下：
```json
{
"api": "/api/openapi/v1/erp/order/honour/agreement/header",
"effect": "QUERY",
"method": "POST",
"number": "no",
"id": "id",
"idCheck": true,
"request": [
{"field":"orgId","label":"组织ID","type":"string","describe":"111","value":"c7b1682f913f40148886045cc47aed9a"},
{"field":"page","label":"页码","type":"string","describe":"111","value":"1"},
{"field":"id","label":"订单id","type":"string","describe":"111"},
{"field":"applyerId","label":"要货方id","type":"string","describe":"111"},
{"field":"supplierId","label":"供货方id","type":"string","describe":"111"},
{"field":"no","label":"订单号","type":"string","describe":"111"},
{"field":"distributionType","label":"分销类型","type":"string","describe":"111"},
{"field":"distributorId","label":"分销商id","type":"string","describe":"111"},
{"field":"orderStatus","label":"订单状态","type":"string","describe":"111", "value": "WAIT_FINANCE_AUDIT,WAIT_DELIVERY,PART_DELIVERY,ALL_DELIVERY,WAIT_OUT_STORAGE,PART_OUT_STORAGE,ALL_OUT_STORAGE,PART_CONFIRM,CONFIRM,AUDIT_SUCCESS,FINISH,CLOSE"},
{"field":"createDt","label":"创建时间","type":"string","describe":"111"},
{"field":"orderTypeCode","label":"订单类型,如普通订单、直运销售","type":"string","describe":"111"},
{"field": "isDeliveryFreezed", "label": "是否暂停发货", "type": "string", "describe": "111"},
{"field": "nature", "label": "单据类型1订单、2退货", "type": "string", "describe": "111", "value": "1"},
{"field": "relatedApplyerId", "label": "关联交易经销商id", "type": "string", "describe": "111"},
{"field": "saleDistribution", "label": "销售渠道", "type": string," describe ":" 111" },
{“ field ”：“ disApplyerId ”，“ label ”：“ 分销商id ”，“ type ”：“ string ”，“ describe ”：“ 111” },
{“ field ”：“ startDt ”，“ label ”：“ 订单时间（开始）”，“ type ”：“ string ”，“ describe ”：“ 111” },
{“ field ”：“ endDt ”，“ label ”：“ 订单时间（结束）”，“ type ”：“ string ”，“ describe ”：“ 111” },
{“ field ”：“ appStartDt ”，“ label ”：“ 审批时间（开始）”，“ type ”：“ string ”，“ describe ":" 111" },
{“ field ":" appEndDt "," label ":" 审批时间（结束） "," type ":" string "," describe ":" 111" },
{“ field ":" lastStartDt "," label ":" 最后修改时间（开始） "," type ":" string "," describe ":" 111 "," value ":" {{LAST_SYNC_TIME | datetime}} “},
{“ field ":" lastEndDt "," label ":" 最后修改时间（结束） "," type ":" string "," describe ":" 111 "," value ":" {{CURRENT_TIME | datetime}} "}
],
“ autoFillResponse”：true
}
```
#### 请求参数详解
- **orgId**: 固定值`c7b1682f913f40148886045cc47aed9a`，表示组织ID。
- **page**: 页码，默认值为`1`。
- **orderStatus**: 多个状态值，用逗号分隔，表示需要查询的订单状态。
- **nature**: 单据类型，固定值为`1`，表示查询的是订单而非退货。
- **lastStartDt**和**lastEndDt**: 分别表示最后修改时间的开始和结束，用于增量同步数据。
其他字段如`applyerId`, `supplierId`, `no`, `distributionType`, `distributorId`, `createDt`, `orderTypeCode`, `isDeliveryFreezed`, `relatedApplyerId`, `saleDistribution`, `disApplyerId`, `startDt`, `endDt`, `appStartDt`, 和`appEndDt`等均为可选参数，根据实际需求填充。
#### 数据请求与清洗
在调用该接口时，需要构建一个POST请求体，其中包含上述参数。示例如下：
```json
{
“ orgId”: “ c7b1682f913f40148886045cc47aed9a”,
“ page”: “1”,
“ orderStatus”: “ WAIT_FINANCE_AUDIT,WAIT_DELIVERY,PART_DELIVERY,ALL_DELIVERY,WAIT_OUT_STORAGE,PART_OUT_STORAGE,ALL_OUT_STORAGE,PART_CONFIRM,CONFIRM,AUDIT_SUCCESS,FINISH,CLOSE”,
“ nature”: “1”,
“ lastStartDt”: “2023-01-01T00:00:00Z”,
“ lastEndDt”: “2023-01-31T23:59:59Z”
}
```
通过发送该请求，可以获取到符合条件的订单头信息。返回的数据通常是一个JSON数组，每个元素代表一条订单记录。
#### 数据转换与写入
获取到原始数据后，需要对其进行清洗和转换，以便写入目标系统。例如，可以将日期格式标准化，将字段名映射到目标系统的字段名等。以下是一个简单的转换示例：
```json
[
{
“ order_id”: “123456”,
“ order_no”: “ORD001”,
“ create_date”: “2023-01-15T10:30:00Z”,
...
}
]
```
转换后的数据可以直接写入目标数据库或通过API推送到其他系统。
#### 自动填充响应
配置中的`autoFillResponse`设置为true，这意味着平台会自动处理响应数据并填充到相应的数据模型中。这一步骤极大简化了开发工作，使得数据集成过程更加高效和可靠。
通过以上步骤，我们完成了从汤臣倍健营销云接口获取并加工数据的全过程。这只是轻易云数据集成平台生命周期管理的一部分，但却是至关重要的一步，为后续的数据处理奠定了基础。
### 使用轻易云数据集成平台将订单数据转换并写入金蝶云星辰V2 API接口
在数据集成生命周期的第二步中，我们需要将已经集成的源平台数据进行ETL转换，转为目标平台金蝶云星辰V2 API接口所能够接收的格式，并最终写入目标平台。本文将详细探讨如何利用轻易云数据集成平台完成这一过程。
#### 1. 数据请求与清洗
首先，从源平台获取原始订单数据，并进行必要的清洗和预处理。这一步骤确保了数据的完整性和准确性，为后续的ETL转换打下基础。假设我们已经完成了这一步，现在进入ETL转换阶段。
#### 2. ETL转换与写入
在ETL转换过程中，我们需要根据金蝶云星辰V2 API接口的要求，将清洗后的数据进行格式化处理。以下是具体的元数据配置和字段映射：
```json
{
"api": "/jdy/v2/scm/sal_out_bound",
"effect": "EXECUTE",
"method": "POST",
"number": "id",
"id": "id",
"name": "id",
"idCheck": true,
"request": [
{
"field": "bill_source",
"label": "单据来源，固定传入ISV",
"type": "string",
"describe": "单据来源，固定传入APP",
"value": "ISV"
},
{
"field": "bill_date",
"label": "出库日期,格式：2019-01-01",
"type": "datetime",
"describe": "出库日期,格式：2019-01-01",
"value": "{{approveDt|date}}"
},
{
...
}
]
}
```
##### 核心字段映射解析
1. **单据来源** (`bill_source`): 固定传入值 `ISV`。
2. **出库日期** (`bill_date`): 使用模板语法 `{{approveDt|date}}` 格式化日期。
3. **单据编码** (`bill_no`): 映射到 `{no}`。
4. **客户ID** (`customer_id`): 利用 `_findCollection` 函数从特定集合中查找客户ID。
5. **备注** (`remark`): 映射到 `{remark}`。
6. **联系信息**:
- 联系人 (`contact_linkman`): 映射到 `{contacts}`。
- 联系方式 (`contact_phone`): 映射到 `{phone}`。
- 地址 (`contact_address`): 映射到 `{shippingAddress}`。
##### 商品分录字段映射解析
商品分录部分是一个数组，每个商品条目包含多个字段：
1. **商品编号** (`material_number`): 映射到 `{productNo}`。
2. **仓库ID** (`stock_id`): 固定值 `1320321070951062528`。
3. **数量** (`qty`): 使用模板语法 `{{details.quantity}}` 获取数量。
4. **单位ID** (`unit_id`): 利用 `_findCollection` 函数从特定集合中查找单位ID。
5. **含税单价** (`tax_price`): 使用模板语法 `{{details.basePrice}}` 获取单价。
6. **是否赠品** (`is_free`): 固定值 `false`。
7. **批次、生产日期、有效日期、保质期天数、保质期类型、折扣额、税率等字段**: 分别使用相应的模板语法或固定值进行映射。
##### 自定义字段
自定义字段部分可以根据实际需求添加，例如：
```json
{
...
{
"field": "custom_field__1__2xietiob41d0jia2",
"label": "营销云备注",
"type": "string",
"value": "{no}"
}
}
```
#### 实际操作步骤
1. 配置元数据：在轻易云数据集成平台上，根据上述配置文件创建相应的数据请求和映射规则。
2. 数据转换：通过轻易云平台内置的ETL工具，将源数据按照配置文件中的规则进行转换，确保所有字段都符合金蝶云星辰V2 API接口的要求。
3. 数据写入：调用金蝶云星辰V2 API接口，将转换后的数据通过POST方法写入目标系统。
通过上述步骤，我们可以实现从源平台到金蝶云星辰V2 API接口的数据无缝对接，确保每个环节的数据准确性和一致性。这一过程不仅提升了业务效率，也为后续的数据分析和决策提供了坚实的数据基础。
