聚水潭·奇门与金蝶云星辰V2数据转换和写入实战案例

  • 轻易云集成顾问-何语琴

聚水潭·奇门数据集成到金蝶云星辰V2的案例分享

在本次技术实践中，我们将详细探讨如何高效地实现聚水潭·奇门的数据集成到金蝶云星辰V2系统，具体针对销售退货单进行数据对接。本案实际采用的方案名称为：聚水潭-销售退货单-->星辰-销售退货单-恩比。

1. 确保集成不漏单

为了确保聚水潭·奇门的数据在传输过程中不出现遗漏，首先需要调用其专用接口jushuitan.refund.list.query进行数据抓取。该接口支持分页查询，这意味着我们可以分批次获取所有待处理的记录。在配置定时任务时，通过周期性的API调用，可以保证新产生的数据被实时捕获和处理。同时，为了应对网络波动或服务故障等偶发问题，还需设计重试机制来自动重新拉取失败的数据段，从而确保每个订单都能完整无误地进入后续流程。

2. 大量数据快速写入到金蝶云星辰V2

大量数据从聚水潭·奇门成功获取之后，将面临写入到金蝶云星辰V2的问题。为了解决这一难题，我们使用了/jdy/v2/scm/sal_in_bound API，该接口优化了批量导入策略，使得大规模数据能够在短时间内高效完成插入操作。此外，在执行批量写入时，还会对返回结果进行监控与验证，一旦发现异常情况即刻触发错误处理机制，以便及时修正可能存在的问题。

3. 数据格式差异及转换

不同系统之间常常存在着各自特有的数据格式，为此需设计相应的映射规则来解决格式上的差异。例如，聚水潭·奇门中的字段名称、类型以及结构可能与金蝶云星辰V2要求的不一致。因此必须通过中间件或脚本对原始数据进行预处理，包括字段映射、单位转换以及数值计算等，以使其符合目标系统的标准。这一过程不仅提升了两者之间的兼容性，也保证最终业务逻辑的一致性。

上述三点是整个项目实施过程中至关重要的步骤，它们共同保障了从源头数据提取到目标系统录入这一路径上，各环节均流畅衔接、准确交付。而针对复杂场景下遇到的一些特殊需求，例如限流管理和实时监控等细节，还有更多适配方法将在后文逐步展开阐述。 打通钉钉数据接口

调用聚水潭·奇门接口获取并加工数据

在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何使用轻易云数据集成平台配置元数据，调用聚水潭·奇门接口 jushuitan.refund.list.query 获取销售退货单数据，并进行相应的数据加工。

接口配置与请求参数

首先，我们需要配置接口的元数据，以便正确调用 jushuitan.refund.list.query 接口。以下是该接口的元数据配置：

{
  "api": "jushuitan.refund.list.query",
  "effect": "QUERY",
  "method": "POST",
  "number": "as_id",
  "id": "as_id",
  "name": "as_id",
  "idCheck": true,
  "formatResponse": [
    {"format": "string", "old": "as_id", "new": "as_id_new"},
    {"format": "string", "old": "type", "new": "type_new"}
  ],
  "request": [
    {"field": "page_index", "label": "第几页", "type": "int", 
        "describe": "从第一页开始，默认1", 
        "value":"1"},
    {"field": "page_size", 
        "label":"每页多少条", 
        "type":"int", 
        "describe":"默认30，最大50", 
        "value":"50"},
    {"field":"start_time",
        "label":"修改起始时间",
        "type":"string",
        "describe":"起始时间，和结束时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空",
        "value":"{{LAST_SYNC_TIME|datetime}}"},
    {"field":"end_time",
        "label":"修改结束时间",
        "type":"string",
        "describe":"结束时间，和起始时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空",
        "value":"{{CURRENT_TIME|datetime}}"},
    {"field":"date_type","label":"时间类型","type":"int","describe":"修改时间:0 ; 创建时间:1; 确认时间: 2;非必填,默认0"},
    {"field":"type","label":"售后类型","type":"string","describe":"普通退货，其它，拒收退货，仅退款，投诉，补发，换货，维修"},
    {"field":"status","label":"售后单状态","type":"string","describe":"（WaitConfirm:待确认,Confirmed:已确认,Cancelled:作废,Merged:被合并）"},
    {"field":"good_status","label":"货物状态","type":"string","describe":"（BUYER_NOT_RECEIVED:买家未收到货,BUYER_RECEIVED:买家已收到货,BUYER_RETURNED_GOODS:买家已退货,SELLER_RECEIVED:卖家已收到退货","value":"SELLER_RECEIVED"},
    {"field":"wms_co_id","label":"分仓编号","type":"string","value":"13599842"}
  ],
  ...
}

请求参数详解

  • page_index 和 page_size：用于分页请求，从第一页开始，每页最多50条记录。
  • start_time 和 end_time：用于指定查询的时间范围，这两个字段必须同时存在且间隔不超过七天。
  • date_type：指定查询的时间类型，可选值为修改时间、创建时间或确认时间。
  • type：售后类型，如普通退货、拒收退货等。
  • status：售后单状态，如待确认、已确认等。
  • good_status：货物状态，此处默认值为“SELLER_RECEIVED”表示卖家已收到退货。
  • wms_co_id：分仓编号，用于指定具体的仓库。

数据格式化与转换

在获取到原始数据后，需要对部分字段进行格式化和转换。根据元数据配置中的 formatResponse 字段，我们将对以下字段进行处理：

  • 将 as_id 转换为 as_id_new
  • 将 type 转换为 type_new

这种转换有助于统一不同系统之间的数据格式，提高数据处理的一致性和可读性。

自动填充响应与条件过滤

元数据配置中还包含了自动填充响应 (autoFillResponse) 和条件过滤 (condition) 的设置：

{
  ...
  "autoFillResponse": true,
  ...
}

启用自动填充响应功能，可以确保在返回的数据中自动包含所有必要字段，无需手动处理。此外，通过条件过滤，可以进一步筛选符合特定条件的数据。例如：

{
  ...
  "condition_bk":[[{"field":"items.type","logic":"in","value":"退货"}]],
  ...
}

上述条件表示仅筛选出类型为“退货”的记录。

异常处理与补救机制

为了确保数据集成过程的稳定性和可靠性，还需要设置异常处理和补救机制。例如，通过定时任务 (crontab) 定期检查并接管请求，以防止因网络或系统问题导致的数据丢失：

{
  ...
  "omissionRemedy":{
    ...
    "crontab": "*\/3 * * * *"
    ...
}

上述设置表示每三小时执行一次检查任务，以确保所有请求都能被正确处理。

通过以上步骤，我们可以高效地调用聚水潭·奇门接口获取销售退货单数据，并进行必要的数据加工和转换，为后续的数据写入和业务处理打下坚实基础。 用友BIP接口开发配置

将源平台数据转换为金蝶云星辰V2API接口格式并写入目标平台

在数据集成生命周期的第二阶段，我们将已经集成的源平台数据进行ETL转换，转为目标平台金蝶云星辰V2API接口所能够接收的格式，并最终写入目标平台。以下是具体的技术实现过程。

API接口配置

首先，我们需要了解金蝶云星辰V2API接口的配置要求。根据提供的元数据配置，目标API接口为/jdy/v2/scm/sal_in_bound，使用POST方法提交数据。以下是具体字段及其对应关系：

  • bill_date: 入库日期，对应源数据中的items.receive_date
  • customer_number: 客户，对应源数据中的shop_id
  • bill_no: 单据编码，对应源数据中的as_id
  • custom_field: 自定义字段，包括聚水潭线上单号和售后类型
    • custom_field__1__3urq4xiepxie3tbl: 聚水潭线上单号，对应源数据中的so_id
    • custom_field__1__3wioxie6qd2ffz: 售后类型，对应源数据中的type
  • operation_key: 操作类型，固定值为audit
  • remark: 备注，对应源数据中的remark
  • bill_dis_amount: 单折扣额，根据条件判断，如果free_amount大于0，则取其值，否则为0
  • material_entity: 商品分录，包括多个子字段
    • is_free: 是否赠品，根据条件判断，如果金额为0或类型为换货，则为true，否则为false
    • material_number: 商品id，对应源数据中的items.sku_id
    • price: 单价
    • qty: 数量，对应源数据中的items.r_qty
    • stock_number: 仓库id，根据条件判断，生成不同格式的仓库id
    • tax_price: 含税单价，根据条件判断，如果类型为换货，则为0，否则取原始价格
    • unit_id: 单位id，固定值为4
    • custom_entity_field: 自定义字段，包括进仓时间
    • custom_entity_field__1__3xblftg6dyhs67: 进仓时间，对应源数据中的items.receive_date

数据转换与映射

在进行ETL转换时，我们需要对以上字段进行映射和转换。以下是具体步骤：

  1. 提取并转换基本信息：

    {
   "bill_date": "{{items.receive_date}}",
   "customer_number": "{shop_id}",
   "bill_no": "{as_id}",
   "operation_key": "audit",
   "remark": "{remark}",
   "bill_dis_amount": "_function IF('{free_amount}' > 0 , '{free_amount}' , 0 )"
}

  2. 处理自定义字段：

    {
   "custom_field": {
       "custom_field__1__3urq4xiepxie3tbl": "{so_id}",
       "custom_field__1__3wioxie6qd2ffz": "{type}"
   }
}

  3. 处理商品分录：

    {
   "material_entity": [
       {
           "is_free": "_function case when '{{items.amount}}' = 0 or '{type_new}' = '换货' then 'true' else 'false' end",
           "material_number": "{{items.sku_id}}",
           "price": "{{items.price}}",
           "qty": "{{items.r_qty}}",
           "stock_number": "_function CASE '{wh_id}' WHEN 1 THEN '{wms_co_id}' ELSE '{wms_co_id}-{wh_id}' END",
           "tax_price": "_function CASE '{type_new}' WHEN '换货' THEN '0' ELSE '{{items.price}}' END",
           "unit_id": "4",
           "custom_entity_field": {
               "custom_entity_field__1__3xblftg6dyhs67": "{{items.receive_date}}"
           }
       }
   ]
}

数据写入目标平台

完成上述转换后，我们将生成的数据通过POST请求写入金蝶云星辰V2API接口。以下是示例请求体：

{
    "bill_date": "2023-10-01",
    "customer_number": "CUST001",
    "bill_no": "AS123456",
    ...
}

通过轻易云的数据集成平台，可以实现对上述过程的全生命周期管理和实时监控，确保每个环节清晰透明，从而极大提升业务效率。 用友与MES系统接口开发配置

版权声明

该文章《聚水潭·奇门与金蝶云星辰V2数据转换和写入实战案例》为原创内容，版权归 广东轻亿云软件科技有限公司 所有。 未经本公司书面授权，严禁转载、引用、复制或建立镜像等行为。 若需转载或引用本文内容，请联系本公司获取授权，并在显著位置注明作者姓名、文章出处（包括原文链接）等信息。

轻易云企业AIGC应用
更多系统对接方案