汤臣倍健营销云数据集成到金蝶云星辰V2的技术实施案例
在实际项目中，企业往往需要面对不同系统之间的数据对接与集成挑战。本文分享了一个通过轻易云平台实现汤臣倍健营销云数据（退货入库/ Life-Space）自动化导入到金蝶云星辰V2系统的具体实施案例。本次方案主要解决以下几个关键问题：确保数据不漏单、处理接口分页及限流、应对数据格式差异以及高效写入目标系统。
首先需要介绍的是如何通过调用汤臣倍健营销云提供的API接口/erp/api/order/query/saleReturnOrder来可靠地抓取销售退货订单数据。这一过程不仅涉及到定时任务调度，还需要考虑API响应中的分页处理和限流规则。在每一次请求中，我们采用了灵活的策略以确保全部待处理记录能够被顺利拉取，无遗漏或重复。
其次，在获取到完整的数据集后，需要将这些原始数据快速且准确地批量写入至金蝶云星辰V2，对此我们利用了其开放API /jdy/v2/scm/sal_in_bound。针对大规模数据操作，特别设计了一套高效并行执行机制，从而显著提升整个传输过程中的性能表现。
除此之外，本案例还涉及到了两种系统间的数据格式转换问题。由于汤臣倍健营销云输出的数据结构和金蝶标准输入有较大差异，为此我们开发了专门的数据映射模块，以保证从源头提取的信息能无缝对应目标字段。此外，在实际运行过程中，对于可能出现的异常如网络故障或接口超时等情况，也实现了完善的错误重试机制，以最大程度确保业务连续性与稳定性。同时，通过实时监控与日志记录功能，可以随时掌握每一步操作进展，提高透明度并方便日后追溯分析。
调用源系统汤臣倍健营销云接口/erp/api/order/query/saleReturnOrder获取并加工数据
在数据集成生命周期的第一步中，调用源系统的API接口是至关重要的一环。本文将深入探讨如何通过调用汤臣倍健营销云的接口 /erp/api/order/query/saleReturnOrder 来获取并加工数据，以实现退货入库（Life-Space）亿倍盛的集成方案。
API接口配置与调用
首先，我们需要配置并调用汤臣倍健营销云的API接口。该接口采用POST方法进行数据请求，主要用于查询销售退货订单。以下是元数据配置的详细信息：
{
"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
}请求参数解析
在请求参数中，有几个关键字段需要特别注意：
tenantId：这是经销商ID，是必填项，用于标识具体的经销商。yxyNumber和number：分别代表营销云销售订单号和系统订单号，这两个字段如果填写了其中一个，则其他时间状态等条件将无效。status：表示订单状态，这里我们设置为“已审核（已出库）”。beginTime和endTime：用于指定查询的时间范围。如果不传单号，这两个字段是必填项。pageNo和pageSize：用于分页查询，这里默认设置为第一页，每页30条记录。timeType：用于标识查询时间段类型，这里设置为最后更新时间。
数据请求与清洗
在完成API调用后，我们会得到一组原始数据。这些数据需要经过清洗和转换，以便后续处理和写入目标系统。在清洗过程中，我们通常会进行以下操作：
- 数据过滤：根据业务需求过滤掉不必要的数据。例如，只保留状态为“已审核”的订单。
- 字段映射：将原始数据中的字段映射到目标系统所需的字段。例如，将原始数据中的“order_id”映射到目标系统中的“order_number”。
- 格式转换：对日期、金额等字段进行格式转换，以符合目标系统的要求。
实际应用案例
假设我们从汤臣倍健营销云获取到以下原始数据：
[
{
"order_id": "XOUT0000000293",
"tenant_id": "34cc4109705e4c058b7b3b0352e57d31",
"status": "1",
"create_time": "2023-10-01 12:34:56",
"update_time": "2023-10-02 14:56:78"
},
...
]经过清洗和转换后，我们可能得到如下结构的数据：
[
{
"order_number": "XOUT0000000293",
"dealer_id": "34cc4109705e4c058b7b3b0352e57d31",
"order_status": "approved",
"created_at": "2023-10-01T12:34:56Z",
"updated_at": "2023-10-02T14:56:78Z"
},
...
]这些清洗后的数据即可用于后续的数据转换与写入阶段，从而完成整个数据集成过程。
通过上述步骤，我们实现了从汤臣倍健营销云获取并加工销售退货订单数据，为后续的数据处理奠定了基础。这一过程不仅提高了业务透明度和效率，也确保了不同系统间的数据无缝对接。
使用轻易云数据集成平台将数据转换并写入金蝶云星辰V2 API接口
在数据集成的生命周期中，ETL（提取、转换、加载）过程是关键的一步。本文将详细探讨如何使用轻易云数据集成平台，将源平台的数据进行ETL转换，并最终写入目标平台金蝶云星辰V2 API接口。
数据请求与清洗
在进行数据转换之前，我们首先需要从源系统提取数据，并进行必要的清洗和预处理。这一步骤确保了我们获取的数据是准确且符合要求的。假设我们已经完成了这一步，接下来我们将重点放在如何将这些清洗后的数据转换为金蝶云星辰V2 API所能接收的格式。
数据转换与写入
为了将数据写入金蝶云星辰V2，我们需要遵循其API接口规范。以下是一个具体的元数据配置示例，用于退货入库（Life-Space）亿倍盛集成方案：
{
"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":"BM00005"},
{
"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":
"1320321598552587264"
},
{"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:
保质期类型，
1：
天，
2：
月，
3：
年,
type:
string,
describe:
保质期类型，1：天，2：月，3：年,
value:
1
}
]
}
]
}元数据配置解析
-
API接口路径与方法：
api字段定义了目标API接口路径为/jdy/v2/scm/sal_in_bound。method字段指定了HTTP请求方法为POST。
-
基本字段映射：
bill_source: 固定值“ISV”，表示来源。bill_date: 使用模板表达式{{auditTime|date}}将审核时间格式化为标准日期格式。customer_id: 使用_findCollection函数从特定集合中查找客户ID。
-
联系信息：
- 包括详细地址、联系人和联系方式等字段，直接从源数据中映射过来。
-
商品分录：
material_entity是一个数组类型字段，包含多个子字段，如商品ID、仓库ID、数量、含税单价等。- 每个子字段都通过模板表达式或查找函数从源数据中获取相应的值。
-
保质期相关字段：
- 包括生产日期、有效日期、保质期天数和类型等，通过模板表达式直接映射。
通过上述配置，我们可以确保源平台的数据被正确地转换为目标平台所需的格式，并通过API接口写入到金蝶云星辰V2中。这个过程充分利用了轻易云数据集成平台的强大功能，实现了高效的数据转换与集成。
