销售退货聚水潭·奇门数据集成到金蝶云星空
在实际业务处理中，销售退货信息的准确、高效传递是企业财务与库存管理中至关重要的一环。为了实现这一流程的自动化，我们选用了轻易云数据集成平台，成功将聚水潭·奇门的数据无缝对接到金蝶云星空。本案例以“销售退货聚水潭=>金蝶”为方案名称，通过API接口实现了两大系统间的数据同步，并确保整个过程中的可靠性和高性能。
首先，为了从聚水潭·奇门获取销售退货数据，我们调用了其提供的API接口 jushuitan.refund.list.query。该接口支持分页查询，能够有效避免单次请求过多导致的问题。通过设置合理的分页参数及处理限流策略，我们确保每次抓取均能成功返回所需的数据，不漏单。
然后，将获取的大量数据快速且批量地写入到金蝶云星空系统中，则是第二个关键步骤。这里我们使用的是金蝶云星空提供的批量保存API batchSave 进行操作，该接口允许一次性提交多个记录，高效地完成大规模数据写入。在此过程中，对接前需要进行一定的数据格式转换，以适应目标系统要求。
在具体实施过程中，还必须特别注意以下几个技术细节：
-
分布式架构下定时抓取：通过配置定时任务机制，相应地调用
jushuitan.refund.list.query接口定期拉取最新数据，并保证任务运行的可靠性。 -
错误重试机制：对于网络波动或临时异常情况，通过建立健全的错误处理和重试机制，使得服务更具鲁棒性。当出现异常时，可以根据预定义规则重新尝试直至成功。
-
实时监控与日志记录：利用轻易云平台内置功能，实现对整个集成过程中的实时监控及详细日志记录，有助于及时发现并解决可能存在的问题。
-
数据映射与格式转换：由于聚水潭·奇门和金蝶云星空之间的数据结构差异，需要针对不同字段进行自定义映射，从而确保写入目标系统后的数据完整一致。
-
优化性能和吞吐量：采用先进的方法，在不影响其它业务操作情况下，高速稳定地完成大量数据迁移任务，提高整体效率。此外，通过限流控制、防止数据库超载等一系列优化措施，也是确保整合流程顺畅的重要保障。
本篇文章将详细介绍如何基于上述思路，实现从聚水潭·奇门到金蝶云星空的销售退货信息自动化对接。在后
调用聚水潭·奇门接口获取并加工数据
在轻易云数据集成平台中，调用聚水潭·奇门接口jushuitan.refund.list.query是数据生命周期的第一步。该步骤主要涉及从源系统获取销售退货数据，并对其进行初步加工，以便后续的数据转换与写入操作。
接口概述
接口jushuitan.refund.list.query用于查询销售退货列表。通过POST请求方式，传递多个参数来筛选和获取所需的退货信息。以下是该接口的元数据配置：
{
"api": "jushuitan.refund.list.query",
"effect": "QUERY",
"method": "POST",
"number": "as_id",
"id": "as_id",
"name": "as_id",
"idCheck": true,
"request": [
{"field": "page_index", "label": "页码", "type": "string", "describe": "页码", "value": "1"},
{"field": "page_size", "label": "页数", "type": "string", "describe": "页数", "value": "50"},
{"field": "start_time", "label": "修改起始时间", "type": "datetime", "describe": "开始时间",
"value":"{{LAST_SYNC_TIME|datetime}}"},
{"field": "end_time", "label":"修改结束时间","type":"datetime","describe":"结束时间","value":"{{CURRENT_TIME|datetime}}"},
{"field":"so_ids","label":"线上单号列表","type":"string","describe":"线上单号列表"},
{"field":"date_type","label":"时间类型","type":"string","describe":"时间类型"},
{"field":"status","label":"售后单状态","type":"string","describe":"售后单状态","value":"Confirmed"},
{"field":"good_status","label":"货物状态","type":"string","describe":
"BUYER_NOT_RECEIVED:买家未收到货,BUYER_RECEIVED:买家已收到货,BUYER_RETURNED_GOODS:买家已退货,SELLER_RECEIVED:卖家已收到退货"},
{"field":"type","label":"售后类型","type":"string","describe":
"普通退货，其它，拒收退货，仅退款，投诉，补发，换货，维修","value":"普通退货"}
],
...
}请求参数解析
- page_index 和 page_size：用于分页查询，默认值分别为1和50。
- start_time 和 end_time：指定查询的时间范围。
start_time采用上次同步时间，而end_time则为当前时间。 - so_ids：可选参数，用于指定特定的线上单号列表。
- date_type：可选参数，用于指定时间类型。
- status：默认值为“Confirmed”，表示只查询确认状态的售后单。
- good_status：用于筛选不同的货物状态，如买家未收到货、买家已收到货等。
- type：默认值为“普通退货”，表示只查询普通退货类型的售后单。
数据请求与清洗
在调用该接口时，需要确保请求参数的正确性和完整性。以下是一个示例请求：
{
"page_index": 1,
"page_size": 50,
"start_time": "{{LAST_SYNC_TIME|datetime}}",
"end_time": "{{CURRENT_TIME|datetime}}",
...
}返回的数据需要经过初步清洗，以确保格式一致性和数据完整性。例如，可以使用轻易云平台提供的数据清洗工具，对返回的数据进行去重、格式转换等操作。
自动填充与接管机制
为了提高数据集成过程的自动化程度，该接口配置了自动填充响应（autoFillResponse）和接管机制（omissionRemedy）。自动填充响应确保了返回的数据能够自动映射到目标字段，而接管机制则通过定时任务（crontab）来处理可能遗漏的数据请求。
接管机制示例：
{
...
“omissionRemedy”: {
“crontab”: “2 0 * * *”,
“takeOverRequest”: [
{
“field”: “start_time”,
“value”: “_function from_unixtime({CURRENT_TIME}-86400,'%Y-%m-%d %H:%i:%s')”,
“type”: “string”,
...
}
]
}
}该配置表示每天凌晨0点2分执行一次任务，将start_time设置为当前时间前一天，以确保没有遗漏的数据被及时获取。
条件过滤
在实际应用中，可以根据业务需求设置条件过滤。例如，只查询订单状态为“Sent”和店铺状态为“SUCCESS”的记录：
{
...
“condition_bk”: [
[
{“field”: “order_status”, “logic”: “eqv2”, “value”: “Sent”},
{“field”: “shop_status”, “logic”: “eqv2”, “value”: “SUCCESS”}
]
]
}通过上述配置，可以有效过滤出符合条件的数据，提高数据集成的准确性和效率。
综上所述，通过合理配置和调用聚水潭·奇门接口，可以高效地获取并加工销售退货数据，为后续的数据转换与写入奠定基础。
使用轻易云数据集成平台将销售退货数据转换并写入金蝶云星空API接口
在数据集成的过程中，ETL（提取、转换、加载）是一个关键步骤。本文将详细探讨如何使用轻易云数据集成平台，将源平台（例如聚水潭）的销售退货数据转换为金蝶云星空API接口所能接收的格式，并最终写入目标平台。
配置元数据
在进行ETL操作之前，我们需要配置好元数据，以确保数据能够正确地映射和转换。以下是我们配置的元数据：
{
"api": "batchSave",
"method": "POST",
"idCheck": true,
"operation": {
"rowsKey": "array",
"rows": 20,
"method": "batchArraySave"
},
"request": [
{"field":"FBillTypeID","label":"单据类型","type":"string","describe":"单据类型","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"XSTHD01_SYS"},
{"field":"FBillNo","label":"单据编号","type":"string","describe":"单据编号","value":"{as_id}"},
{"field":"FSaleOrgId","label":"销售组织","type":"string","describe":"销售组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{shop_id}","mapping":{"target":"64abc6ccb0695b5829466abe","direction":"positive"}},
{"field":"FDate","label":"日期","type":"string","describe":"日期","value":"{modified}"},
{"field":"FStockOrgId","label":"库存组织","type":"string","describe":"库存组织","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value":"{shop_id}","mapping":{"target":"64abc6ccb0695b5829466abe"}},
{"field":"FRetcustId","label":"退货客户","type":"string","describe":"","parser":{"name":"ConvertObjectParser","params":"FNumber"},"value\":\"{shop_id}\",\"mapping\":{\"target\":\"6481809d99cb703832272f51\",\"direction\":\"positive\"}},
{"field\":\"FSALESMANID\",\"label\":\"销售员\",\"type\":\"string\",\"value\":\"{shop_id}\",\"parser\":{\"name\":\"ConvertObjectParser\",\"params\":\"FNumber\"},\"mapping\":{\"target\":\"64abd35844666e7686383510\",\"direction\":\"positive\"}},
{"field\":\"FSettleCurrId\",\"label\":\"结算币别\",\"type\":\"string\",\"describe\":\"结算币别\",\"parser\":{\"name\":\"ConvertObjectParser\",\"params\":\"FNumber\"},\"value\":\"PRE001\"},
{"field\":\"FHeadNote\",\"label\":\"备注\",\"type\":\"string\",\"describe\":\"备注\"},
{
\"field\": \"FEntity\",
\"label\": \"明细信息\",
\"type\": \"array\",
\"describe\": \"明细信息\",
\"children\": [
{\"field\": \"FMaterialId\", \"label\": \"物料编码\", \"type\": \"string\", \"describe\": \"物料编码\", \"parser\":{\"name\": \"ConvertObjectParser\", \"params\": \"FNumber\"}, \"value\": \"{{items.sku_id}}\", \"parent\": \"FEntity\"},
{\"field\": \"FRealQty\", \"label\": \"实退数量\", \"type\": \"string\", \"describe\": \"实退数量\", \"value\": \"{{items.r_qty}}\", \"parent\": \"FEntity\"},
{\"field\": \"FPRICE\", \”label\”: \”单价\”, \”type\”: \”string\”, \”value\”: \”{{items.price}}\”},
{\"field\": \”FTaxPrice\”, \”label\”: \”含税单价\”, \”type\”: \”string\”, \”describe\”: \”含税单价\”, \”value\”: \”{{items.price}}\”, \”parent\”: \”FEntity\”},
{\"field\": \”FAllAmount\”, \”label\”: \“价税合计”， “type”： “string”， “描述”： “含税单价”， “值”： “{{items.amount}}”， “父级”： “实体”
},
{“字段”： “是否免费”， “标签”： “是否赠品”， “类型”： “字符串”， “描述”： “是否赠品”， “父级”： “实体”
},
{“字段”： “FOwnerTypeId”， 标签： ‘货主类型’， 类型： ‘字符串’， 描述： ‘货主类型’， 值： ‘BD_OwnerOrg’， 父级： ‘实体’
},
{“字段”： ‘FOwnerId’， 标签： ‘货主’， 类型： ‘字符串’， 描述： ‘货主’， 解析器： {'名称': 'ConvertObjectParser', '参数': '数字'}, '值': '115', '父级': '实体'
},
{‘字段’：“仓库”， 标签：“仓库”， 类型：“字符串”， 描述：“仓库”， 解析器：{'名称':'ConvertObjectParser','参数':'数字'},'值':'{wms_co_id}','父级':'实体','映射':{'目标':'6479b78d40ac5e714f39f40a','方向':'正向'}},
{‘字段’：“备注”，“标签”，“备注”，“类型”，“字符串”，“描述”，“备注”，“父级”，“实体”
},
{‘字段’：“源单编号”，“标签”，“源单编号”，“类型”，“字符串”，“值”，“{o_id}”
},
{‘字段’：“订单号”，“标签”，“订单号”，“类型”，“字符串”，“值”，“{so_id}”
}
],
‘值’:’项目’
},
{
‘字段’:’子头实体’，
标签:‘财务信息’，
类型:‘对象’，
描述:‘财务信息’，
子项:[
{
字段:‘结算组织’，
标签:‘结算组织’，
类型:‘字符串’，
描述:‘结算组织’，
解析器:{'名称':'ConvertObjectParser','参数':'数字'},'值':'{shop_id}','父级':'子头实体','映射':{'目标':'64abc6ccb0695b5829466abe','方向':'正向'}
}
]
}
],
'其他请求':[
{'字段':'表单ID','标签':'业务对象表单ID','类型':'字符串','描述':'必须填写金蝶的表单ID如:PUR_PurchaseOrder','值':'SAL_RETURNSTOCK'},
{'字段':'操作','标签':'执行的操作','类型':'字符串','值':'批量保存'},
{'字段':'自动提交并审核','标签':'提交并审核','类型':'布尔型','值':true},
{'字段'：'验证基础资料'，'标签'：'验证基础资料'，'类型'：'布尔型'，'描述'：'是否验证所有的基础资料有效性，布尔类，默认false（非必录）', '值':true}
]
}数据转换过程
-
提取源数据： 从聚水潭系统中提取销售退货的数据。这些数据通常包含订单编号、商品SKU、退货数量等。
-
转换为目标格式： 使用轻易云的数据集成工具，根据上面配置的元数据，将提取到的数据进行转换。主要包括以下几个步骤：
-
基本信息映射： 将订单编号（
as_id）、销售组织（shop_id）、日期（modified）等基本信息映射到相应的金蝶云API字段。 -
明细信息处理： 对于每个退货商品，提取其SKU（
items.sku_id）、实退数量（items.r_qty）、价格（items.price）等，并映射到金蝶云API中的相应字段。 -
财务信息处理： 映射结算组织等财务相关的信息。
-
-
加载到目标系统： 使用配置好的API接口，将转换后的数据通过POST请求发送到金蝶云星空系统。确保请求中包含所有必要的字段和正确的数据格式。
实际案例
假设我们从聚水潭系统中提取到以下销售退货数据：
{
"as_id": "TH20230901",
"shop_id": "S001",
"modified": "2023-09-01",
"items": [
{
"sku_id": "SKU12345",
"r_qty": 10,
"price": 100,
"amount": 1000
}
],
"o_id": "O20230901",
"so_id": "SO20230901"
}根据上述元数据配置和转换规则，我们将生成如下符合金蝶云星空API要求的请求体：
{
"FormId": "SAL_RETURNSTOCK",
"Operation": {
...
},
...
}通过以上步骤，我们成功地将聚水潭系统中的销售退货数据转换并写入到了金蝶云星空系统，实现了不同系统间的数据无缝对接。这一过程不仅提高了业务效率，还确保了数据的一致性和准确性。
