PACKAGE-聚水潭销售出库单对接金蝶云星辰V2案例分享

在本次技术案例中，我们深入探讨了如何通过轻易云数据集成平台，成功将聚水潭·奇门的销售出库单数据高效地对接到金蝶云星辰V2系统。此方案名称为:PACKAGE-聚水潭销售出库单对接销售出库单。

首先，为确保从聚水潭·奇门获取的数据不漏单，我们设计了一个定时可靠的抓取机制，利用其提供的API接口/open/orders/out/simple/query每隔固定时间段查询并提取最新的订单数据。同时，通过处理分页和限流问题，实现了大规模数据的高效抓取。这些操作使得我们能实时监控订单信息，并保证所有有效订单均被准确提取。

为了应对大量数据快速写入到金蝶云星辰V2的问题，我们优化了批量处理的方法，通过调用金蝶云提供的数据写入接口/jdy/v2/scm/sal_out_bound，实现了一次性批量推送多条记录。这样既减少了网络请求次数，又提高了系统整体运行效率。

在整个集成过程中，不可避免会遇到两套系统间的数据格式差异，这一点尤为重要。我们创建了一系列自定义映射规则，将从聚水潭·奇门获取的原始数据转换为符合金蝶云星辰V2要求的数据结构。这一步骤至关重要，因其直接影响最终数据存储结果及业务流程是否顺畅。

此外，为进一步提升方案鲁棒性，我们还设计了一套完善的异常处理与错误重试机制。一旦发生任何API访问失败或数据写入异常情况，系统会自动尝试重试操作，并生成详细日志供事后分析与调优之用。

综上所述，本次技术实施不仅解决了多个关键难题，还充分体现出了轻易云平台在全生命周期内对于透明化管理和高效执行方面的大力支持。在下面部分内容中将更加详细地介绍具体实施步骤和配置细节，以帮助您更好地理解这一成功实践。

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

在轻易云数据集成平台中，调用源系统接口是数据处理生命周期的第一步。本文将详细探讨如何通过调用聚水潭·奇门接口/open/orders/out/simple/query来获取销售出库单数据，并进行初步的数据加工。

接口概述

聚水潭·奇门接口/open/orders/out/simple/query用于查询销售出库单的简要信息。该接口采用POST请求方式，支持分页查询，并且可以根据多种条件进行筛选。以下是该接口的主要参数配置：

• page_index: 页数，从第一页开始，默认值为1。
• page_size: 每页行数，默认25，最大25。
• modified_begin: 修改起始时间，与结束时间必须同时存在，时间间隔不能超过七天。
• modified_end: 修改结束时间，与起始时间必须同时存在。
• status: 单据状态，可选值包括WaitConfirm（待出库）、Confirmed（已出库）、Cancelled（作废）。
• wms_co_id: 分仓编号。
• shop_id: 店铺编号。
• so_ids: 线上单号列表，与修改时间不能同时为空。
• o_ids: 内部单号列表，与修改时间不能同时为空。
• io_ids: 销售出库单号列表，与修改时间不能同时为空。
• date_type: 时间类型，默认值为0。可选值包括0（修改时间）、1（制单日期）、2（出库时间）。

请求参数配置

在轻易云数据集成平台中，我们可以通过元数据配置来定义请求参数。以下是具体的元数据配置示例：

{
  "api": "/open/orders/out/simple/query",
  "effect": "QUERY",
  "method": "POST",
  "number": "io_id",
  "id": "io_id",
  "name": "io_id",
  "idCheck": true,
  "request": [
    {
      "field": "page_index",
      "label": "页数",
      "type": "string",
      "describe": "第几页，从第一页开始，默认1",
      "value": "1"
    },
    {
      "field": "page_size",
      "label": "每页行数",
      "type": "string",
      "describe": "每页多少条，默认25，最大25",
      "value": "25"
    },
    {
      "field": "modified_begin",
      "label": "修改开始时间",
      "type": "string",
      "describe": "修改起始时间，和结束时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空",
      "value": "{{LAST_SYNC_TIME|datetime}}"
    },
    {
      "field": "modified_end",
      "label": "修改结束时间",
      "type": "string",
      "describe": "修改结束时间，和起始时间必须同时存在，时间间隔不能超过七天，与线上单号不能同时为空",
      "$value$":"{{CURRENT_TIME|datetime}}"
    },
    {
      "$field$":"status","label":"单据状态","type":"string","describe":"单据状态: WaitConfirm=待出库; Confirmed=已出库; Cancelled=作废","value":"Confirmed"
    },
    {
     "$field$":"wms_co_id","label":"分仓编号","type":"int","describe":"分仓编号"
    },
    {
     "$field$":"shop_id","label":"店铺编号","type":"int","describe":"店铺编号"
    },
    {
     "$field$":"so_ids","label":"线上单号","type":"string","describe":"线上单号列表，与修改时间不能同时为空"
    },
    {
     "$field$":"o_ids","label":"内部单号列表","type":"int","describe":"内部单号列表，与修改时间不能同时为空"
    },
    {
     "$field$":"io_ids","label":"销售出库单号","type":"string","describe":"销售出库单号列表，与修改时间不能同时为空"
   },
   {
     "$field$"："date_type"，"label"："时间类型"，"type"："int"，"describe"："时间类型 默认0 0=修改时间 ; 1=制单日期; 2=出库时间"
   }
 ],
   "$autoFillResponse$"：true
}

数据请求与清洗

在实际操作中，我们首先需要通过上述配置向聚水潭·奇门接口发送请求，以获取销售出库单的数据。以下是一个示例请求体：

{
  "$page_index$"：1，
  "$page_size$"：25，
  "$modified_begin$"："2023-10-01T00：00：00Z"，
  "$modified_end$"："2023-10-07T23：59：59Z"，
  "$status$"："Confirmed"
}

该请求将返回符合条件的销售出库单数据。在接收到响应后，需要对数据进行初步清洗和转换，以便后续处理。例如，可以过滤掉无效字段、规范化日期格式等。

数据转换与写入

在完成初步清洗后，可以将数据转换为目标系统所需的格式，并写入到目标数据库或系统中。这一步通常涉及字段映射、数据类型转换等操作。

例如，将聚水潭·奇门返回的JSON格式数据转换为关系型数据库中的表记录：

INSERT INTO sales_orders (order_id, warehouse_id, shop_id, status, modified_time)
VALUES (?, ?, ?, ?, ?);

通过上述步骤，我们可以实现从聚水潭·奇门接口获取销售出库单数据，并进行初步加工，为后续的数据处理打下基础。这一过程充分利用了轻易云数据集成平台的强大功能，实现了高效、透明的数据集成。

将源平台数据转换并写入金蝶云星辰V2API接口的技术实现

在轻易云数据集成平台中，数据集成的第二步是将已经集成的源平台数据进行ETL（Extract, Transform, Load）转换，并转为目标平台所能够接收的格式。本文将重点探讨如何将聚水潭销售出库单的数据转换为金蝶云星辰V2 API接口所需的格式，并最终写入目标平台。

API接口配置与元数据解析

首先，我们需要理解金蝶云星辰V2 API接口的具体配置和要求。根据提供的元数据配置，目标API为/jdy/v2/scm/sal_out_bound，请求方法为POST，并且需要进行ID校验（idCheck: true）。

以下是API请求中的主要字段及其描述：

• bill_source: 单据来源，固定传入值为"ISV"。
• bill_date: 出库日期，格式为YYYY-MM-DD。
• bill_no: 单据编号。
• customer_number: 客户信息，固定值为"10364031"。
• material_entity: 商品分录，是一个数组，每个元素包含商品、仓库、数量、单位、含税单价、是否赠品以及金额等信息。

数据提取与转换

在ETL过程中，我们需要从源平台提取数据，然后按照目标API接口的要求进行转换。以下是具体步骤：

1. 提取数据： 从聚水潭系统中提取销售出库单的数据，包括出库日期（io_date）、单据编号（io_id）、商品分录（details_list）等。

2. 转换数据： 根据元数据配置，将提取到的数据映射到目标API所需的字段。例如：

   • bill_date: 映射自源平台的io_date。
   • bill_no: 映射自源平台的io_id。
   • material_entity: 需要对每个商品分录进行详细映射，包括商品编号、仓库编号、数量、单位、含税单价、是否赠品以及金额等。

3. 构建请求体： 按照API要求构建JSON请求体。示例如下：

{
  "bill_source": "ISV",
  "bill_date": "{io_date}",
  "bill_no": "{io_id}",
  "customer_number": "10364031",
  "material_entity": [
    {
      "material_number": "6721936151088",
      "stock_number": "12252",
      "qty": "{{items.qty}}",
      "unit_id": "3",
      "tax_price": "{{items.sale_price}}",
      "is_free": "_function case '{{items.sale_price}}' when '0' then 'true' else 'false' end",
      "amount": "{{items.sale_amount}}"
    }
    // ... more items
  ]
}

实现细节

为了确保数据能够正确地写入金蝶云星辰V2，我们需要关注以下几个关键点：

1. 字段映射与转换： 使用轻易云的数据转换功能，将源平台字段映射到目标平台字段。例如，通过模板语言将变量替换为实际值，如${io_date}替换为具体日期。

2. 条件逻辑处理： 对于复杂逻辑，例如判断是否赠品，可以使用条件表达式：当价格为0时设置为赠品，否则不是赠品。这里使用了 _function case '{{items.sale_price}}' when '0' then 'true' else 'false' end 表达式。

3. 数组处理： 商品分录是一个数组，需要遍历每个商品条目并进行相应的字段映射和转换。

4. 错误处理与日志记录： 在实际操作中，需要对可能出现的错误进行处理，并记录日志以便于排查问题。例如，若某个字段缺失或格式不正确，应当捕获异常并记录详细信息。

请求发送与结果处理

完成数据转换后，通过HTTP POST方法将构建好的JSON请求体发送到金蝶云星辰V2 API接口。可以使用轻易云内置的HTTP客户端功能来实现这一点。同时，需要对返回结果进行解析和处理，以确认数据是否成功写入目标系统。

import requests

url = "/jdy/v2/scm/sal_out_bound"
headers = {
    'Content-Type': 'application/json',
    # 添加其他必要的头部信息，如认证token等
}

response = requests.post(url, json=request_body, headers=headers)

if response.status_code == 200:
    print("Data successfully written to Kingdee Cloud.")
else:
    print(f"Failed to write data: {response.text}")

通过上述步骤，我们能够高效地将聚水潭销售出库单的数据转换并写入金蝶云星辰V2系统，实现不同系统间的数据无缝对接。这不仅提升了业务效率，也确保了数据的一致性和准确性。