轻易云平台实现金蝶云星辰V2API接口的ETL转换

  • 轻易云集成顾问-谢楷斌

新版订单-出库单- （Life-Space）厦门众之健：汤臣倍健营销云数据集成到金蝶云星辰V2案例分享

在对接和整合企业多元化业务系统的技术挑战中，如何确保数据流转的准确与高效，是每一个系统集成项目不可回避的问题。本次分享的是我们在轻易云数据集成平台上成功实施的一例经典案例——汤臣倍健营销云的数据无缝对接到金蝶云星辰V2。

本次项目名为“新版订单-出库单- （Life-Space）厦门众之健”，主要任务是通过调用汤臣倍健营销云提供的API接口 /api/openapi/v1/erp/order/honour/agreement/header，定时抓取新生成的订单数据，并将其快速写入至金蝶云星辰V2指定API接口 /jdy/v2/scm/sal_out_bound 中。为了保障整个流程中的数据不遗漏、实时监控及异常处理，我们采取了一系列先进技术手段并制定了可靠性策略。

首先，在接口调用层面，为最小化网络波动带来的影响，我们设计了精细的分页机制和限流策略。这不仅有效避免了因大量请求导致接口超时或阻塞，还确保所有待处理订单均能被逐一抓取。此外，大量数据批量写入功能则保证了高效的数据传输速率。

其次，在跨系统的数据格式转换方面，我们通过定制化的数据映射方案，使得汤臣倍健营销云中的复杂字段能够灵活适配金蝶云星辰V2要求。同时，每一步关键操作均设有实时监控与详细日志记录，从而实现全过程透明管理，可追溯每个环节，对潜在问题早发现、早解决。

最后，针对于可能出现的异常情况，本方案还引入了一套全自动错误重试机制。一旦某批次操作失败，会立即触发预设警报并进行重复尝试，这大大增强了整体系统对突发事件的应变能力和持续运行稳定性。

本文将深入探讨上述各项技术措施及其具体应用实例，通过实际案例解析，希望能够为其他类似需求提供有价值参考。 钉钉与ERP系统接口开发配置

调用汤臣倍健营销云接口获取并加工数据

在轻易云数据集成平台的生命周期中，调用源系统接口获取数据是至关重要的第一步。本文将详细探讨如何通过调用汤臣倍健营销云接口/api/openapi/v1/erp/order/honour/agreement/header来获取并加工订单数据。

接口概述

该接口采用POST方法进行数据请求，主要用于查询订单头信息。以下是该接口的元数据配置：

{
  "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":"c5a3b3974fc54308800a38c77bfa187b"},
    {"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_DELIVERY,PART_DELIVERY,ALL_DELIVERY,WAIT_OUT_STORAGE,PART_OUT_STORAGE,ALL_OUT_STORAGE,PART_CONFIRM,CONFIRM,AUDIT_SUCCESS,FINISH"},
    {"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 "}
  ],
  autoFillResponse: true
}

请求参数解析

在请求参数中，有几个关键字段需要特别注意：

  • orgId: 固定值，用于标识组织。
  • page: 页码，默认值为1。
  • orderStatus: 多种状态组合，用于筛选不同状态的订单。
  • nature: 单据类型，固定值为1表示订单。
  • lastStartDt 和 lastEndDt: 分别表示最后修改时间的开始和结束，这两个字段使用动态变量{{LAST_SYNC_TIME|datetime}}和{{CURRENT_TIME|datetime}}来自动填充。

这些字段确保了我们能够精确地筛选出所需的订单数据。

数据请求与清洗

在轻易云平台上，我们可以通过配置上述元数据来自动生成请求报文，并发送到汤臣倍健营销云接口。以下是一个示例请求报文：

{

![打通企业微信数据接口](https://pic.qeasy.cloud/S22.png~tplv-syqr462i7n-qeasy.image)
### 利用轻易云数据集成平台实现金蝶云星辰V2API接口的ETL转换

在数据集成生命周期的第二步中，我们需要将已经从源平台获取的数据进行ETL（Extract, Transform, Load）转换，最终写入目标平台金蝶云星辰V2API接口。本文将详细介绍如何通过轻易云数据集成平台配置元数据，实现这一过程。

#### 配置元数据

在进行ETL转换之前，我们首先需要配置好元数据，以确保数据能够正确地映射到目标平台的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":"{{financeApproveDt|date}}"},
    {"field":"customer_id","label":"客户id","type":"string","describe":"客户信息","value":"_findCollection find id from 617d3b33-162f-3e9f-be59-14e1953bc4a0 where number={clientAppNo}"},
    {"field":"remark","label":"单据备注","type":"string","value":"{remark}"},
    {"field":"contact_linkman","label":"联系信息-联系人","type":"string","value":"{contacts}"},
    {"field":"contact_phone","label":"联系信息-联系方式","type":"string","value":"{phone}"},
    {"field":"contact_address","label":"联系信息-详细地址","type":"string","value":"{shippingAddress}"},
    {"field":"custom_field","label":"自定义字段","type": "object", "children":[{"field": "custom_field__1__2xietiob41d0jia2", "label": "营销云单号", "type": "string", "value": "{no}"}]},
    {
      "field": "material_entity",
      "label": "商品分录",
      "type": "array",
      "describe": "商品分录",
      "value": "details",
      "children":[
        {"field": "material_number",   "label": "商品",     "type": "string",   "describe":   商品",   value: "{{details.easNo}}"},
        {"field":   stock_id",   label:   仓库",   type:   string",   describe:   仓库",   value:   1277528119946811392},
        {"field" : qty, label : 数量, type : string, describe : 数量, value : {{details.quantity}}},
        {
          field : unit_id,
          label : 单位id,
          type : string,
          describe : 单位（只能填商品关联的单位，来源于商品单位查询接口或商品详情中的baseunitid_id、fixunit1_id等）,
          value : _findCollection find base_unit_id from 72029be6-c558-39a7-8084-4b75796fcba1 where number={{details.easNo}}
        },
        { field: price, label: 含税单价, type: string, describe: 单价（如果在“系统参数”的“基础资料参数”中勾选了“商品价格为含税单价”，则price指示含税单价）, value: {{details.price}} },
        { field: discount2, label: 折扣, type: string, value: _findCollection find clevel_discount from 617d3b33-162f-3e9f-be59-14e1953bc4a0 where number={clientAppNo} },
        { field: is_free, label: 是否赠品, type: string, describe: 是否赠品；true-是，false-否（默认）, value: false },
        { field: batch_no, label: 批次, type: string, describe: 库位_id,value="{{details._Flot}}" },
        { field:kf_date,label:"生产日期",type:"string",describe:"生产日期",value:"{{details._Fmfg}}" },
        { field:"valid_date",label:"有效日期",type:"string",describe:"有效日期",value:"{{details._Fexp}}" },
        { field:"kf_period",label:"保质期天数",type:"string",describe:"保质期天数"，value："730" },
        { field："kf_type"，label："保质期类型"，type："string"，describe："保质期类型"，value："1" },
        {
          field：custom_entity_fiel，
          label：自定义字段，
          type：object，
          children：[{"field"："custom_entity_field__1__2czrot3grac0"，"label"："到期日(备用)"，"type"："string"，"value"："{{giveDate|date}}"}]
        }
      ]
    }
  ]
}

数据清洗与转换

在数据清洗阶段，我们需要确保源平台的数据符合目标平台的要求。利用轻易云的数据清洗功能，可以对原始数据进行必要的处理，如格式转换、字段映射等。

例如，将出库日期bill_date从源平台的时间戳格式转换为目标平台所需的YYYY-MM-DD格式：

{"field": “bill_date”, “value”: “{{financeApproveDt|date}}”}

数据写入

完成数据清洗和转换后，我们可以通过配置好的API接口将处理后的数据写入金蝶云星辰V2。以下是一个具体的HTTP POST请求示例：

POST /jdy/v2/scm/sal_out_bound HTTP/1.1
Host: api.kingdee.com
Content-Type: application/json

{
  “bill_source”: “ISV”,
  “bill_date”: “2023-10-15”,
  “customer_id”: “1234567890”,
  “remark”: “这是一个测试备注”,
  “contact_linkman”: “张三”,
  “contact_phone”: “13800000000”,
  “contact_address”: “厦门市思明区软件园二期”,
  “custom_field”: {
    “custom_field__1__2xietiob41d0jia2”: “YX123456”
  },
  “material_entity”: [
    {
      “material_number”: “ABC123”,
      “stock_id”: “1277528119946811392”,
      “qty”：10，
      ”unit_id”：”100000001”，
      ”price”：100.00，
      ”discount2”：10.00，
      ”is_free”：false，
      ”batch_no”：”BATCH001”，
      ”kf_date”：”2023-10-01”，
      ”valid_date”：”2025-10-01”，
      ”kf_period”：730，
      ”kf_type”：1，
      ”custom_entity_fiel”：{
         custom_entity_field__1__2czrot3grac0：“2025-09-30”
       }
     }
   ]
}

通过以上步骤，我们成功地将源平台的数据经过ETL转换后写入了金蝶云星辰V2API接口。这一过程不仅提高了数据处理效率，还确保了不同系统间的数据一致性和准确性。 如何开发企业微信API接口

版权声明

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

轻易云AI数据分析
更多系统对接方案