简介

第三方系统将数据传输到企企后，单据生效后，第三方系统需要修改单据，此时企企中不支持使用/v1/update 更新接口对数据进行修改。这种情况下，需要进行单据变更。本教程将介绍果将已生效的单据进行变更。

变更适用对象

项目，合同

变更原理

新增一条单据生效后，该单据称为原单据，需要对原单据进行更新，这时要新增一条单据，该单据称为变更单，将修改后的原单据的数据全量作为变更单的参数，新增变更单，变更单提交后需要重新走审批流程，变更单生效后。企企后台会将变更单的数据移到原单据上，以此达到原单据更新的效果。

注意：一个变更单，同一时间未生效的变更单只能有1个

操作流程

本教程通过 API 实现企企已生效单据的变更，操作时序图如下所示：

案例实现

项目变更

先新增原项目单据，然后进行项目变更。大概流程如下：

• 新增原项目
• 新增项目变更单
• 提交项目变更单

新增原项目

a. 使用接口，POST https://api2.77hub.com/v1/add 新增接口。

b. 在请求体（Body）中，以 JSON 格式填写请求参数。

{
  "json": "{\"objectType\":\"Project\",\"data\":{\"createdOrg.code\":\"qq-bjqq\",\"createdOrg.name\":\"北京企企\",\"webEditTemplate.name\":\"项目\",\"financialOrg.code\":\"qq-bjqq\",\"financialOrg.name\":\"北京企企\",\"billType.name\":\"项目\",\"code\":\"0001\",\"name\":\"测试开发项目\",\"businessType.name\":\"项目\",\"category.code\":\"001\",\"category.name\":\"分类A\",\"projectProperties\":\"ProjectProperties.develop\",\"projectGroup.code\":\"xmfz01\",\"projectGroup.name\":\"项目分组一\",\"salesOrg.code\":\"qq-bjqq\",\"salesOrg.name\":\"北京企企\",\"customer.name\":\"客户1\",\"ownerDept.name\":\"bj财务部\",\"ownerUser.name\":\"双双\",\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"planStartDate\":\"2022-11-15\",\"planEndDate\":\"2022-12-13\",\"scheduledDuration\":31,\"enableStage\":true,\"stageGroup.name\":\"项目阶段1-3\",\"businessDate\":\"2022-11-03\",\"enableChangeApprove\":true,\"stages\":[{\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"stage.code\":\"0000001\",\"stage.name\":\"需求阶段\",\"planStartDate\":\"2022-11-18\",\"planEndDate\":\"2022-11-29\",\"scheduledDuration\":8,\"outcome\":\"需求阶段准备\",\"ownerUser.name\":\"周小七\",\"description\":\"需求准备\"}],\"members\":[{\"department.name\":\"bj财务部\",\"user.name\":\"曹操\"}],\"deliverOrgs\":[{\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\"}],\"externalObjectId\":\"2100004112\",\"externalObjectType\":\"Project\",\"externalSystemCode\":\"210004\"}}"
}

body参数,json 的value 值如下：

{
  "objectType": "Project",
  "data": {
    "createdOrg.code": "qq-bjqq",
    "createdOrg.name": "北京企企",
    "webEditTemplate.name": "项目",
    "financialOrg.code": "qq-bjqq",
    "financialOrg.name": "北京企企",
    "billType.name": "项目",
    "code": "0001",
    "name": "测试开发项目",
    "businessType.name": "项目",
    "category.code": "001",
    "category.name": "分类A",
    "projectProperties": "ProjectProperties.develop",
    "projectGroup.code": "xmfz01",
    "projectGroup.name": "项目分组一",
    "salesOrg.code": "qq-bjqq",
    "salesOrg.name": "北京企企",
    "customer.name": "客户1",
    "ownerDept.name": "bj财务部",
    "ownerUser.name": "双双",
    "projectOrg.code": "qq-bjqq",
    "projectOrg.name": "北京企企",
    "planStartDate": "2022-11-15",
    "planEndDate": "2022-12-13",
    "scheduledDuration": 31,
    "enableStage": true,
    "stageGroup.name": "项目阶段1-3",
    "businessDate": "2022-11-03",
    "enableChangeApprove": true,
    "stages": [
      {
        "projectOrg.code": "qq-bjqq",
        "projectOrg.name": "北京企企",
        "stage.code": "0000001",
        "stage.name": "需求阶段",
        "planStartDate": "2022-11-18",
        "planEndDate": "2022-11-29",
        "scheduledDuration": 8,
        "outcome": "需求阶段准备",
        "ownerUser.name": "周小七",
        "description": "需求准备"
      }
    ],
    "members": [
      {
        "department.name": "bj财务部",
        "user.name": "曹操"
      }
    ],
    "deliverOrgs": [
      {
        "projectOrg.code": "qq-bjqq",
        "projectOrg.name": "北京企企"
      }
    ],
    "externalObjectId": "2100004112",
    "externalObjectType": "Project",
    "externalSystemCode": "210004"
  }
}

c. 使用sdk,新增时自动提交付款单示例如下

public void testAdd() {
  PostAddRequest request = new PostAddRequest();
  ApiParams apiParams = new ApiParams();
  apiParams.setJson("{\"objectType\":\"Project\",\"data\":{\"createdOrg.code\":\"qq-bjqq\",\"createdOrg.name\":\"北京企企\",\"webEditTemplate.name\":\"项目\",\"financialOrg.code\":\"qq-bjqq\",\"financialOrg.name\":\"北京企企\",\"billType.name\":\"项目\",\"code\":\"0001\",\"name\":\"测试开发项目\",\"businessType.name\":\"项目\",\"category.code\":\"001\",\"category.name\":\"分类A\",\"projectProperties\":\"ProjectProperties.develop\",\"projectGroup.code\":\"xmfz01\",\"projectGroup.name\":\"项目分组一\",\"salesOrg.code\":\"qq-bjqq\",\"salesOrg.name\":\"北京企企\",\"customer.name\":\"客户1\",\"ownerDept.name\":\"bj财务部\",\"ownerUser.name\":\"双双\",\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"planStartDate\":\"2022-11-15\",\"planEndDate\":\"2022-12-13\",\"scheduledDuration\":31,\"enableStage\":true,\"stageGroup.name\":\"项目阶段1-3\",\"businessDate\":\"2022-11-03\",\"enableChangeApprove\":true,\"stages\":[{\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"stage.code\":\"0000001\",\"stage.name\":\"需求阶段\",\"planStartDate\":\"2022-11-18\",\"planEndDate\":\"2022-11-29\",\"scheduledDuration\":8,\"outcome\":\"需求阶段准备\",\"ownerUser.name\":\"周小七\",\"description\":\"需求准备\"}],\"members\":[{\"department.name\":\"bj财务部\",\"user.name\":\"曹操\"}],\"deliverOrgs\":[{\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\"}],\"externalObjectId\":\"2100004112\",\"externalObjectType\":\"Project\",\"externalSystemCode\":\"210004\"}}");
  request.sdkRequestConfig(getSdkRequestConfig(request, true, true));
  request.setApiParams(apiParams);
  PostAddResult postAddResult = openapi().postAdd(request);
  ApiResponse apiResponse = postAddResult.getApiResponse();
  System.out.println(apiResponse);
}

d. 返回结果：

{
  "json": "{\"id\":\"8RPN3261UAT00A0\"}"
}

新增项目变更单

原单据只能有一张未生效的变更单，变更单生效后后才能新建新的变更单，变更单的版本号为V1.0，V2.0, 一次类推，版本号控制字段为：customVersion

a. 使用接口 POST add 新增接口。

b. 在请求体（Body）中，以 JSON 格式填写请求参数。

{
  "json": "{\"objectType\":\"Project\",\"data\":{\"createdOrg.code\":\"qq-bjqq\",\"createdOrg.name\":\"北京企企\",\"webEditTemplate.name\":\"项目\",\"financialOrg.code\":\"qq-bjqq\",\"financialOrg.name\":\"北京企企\",\"billType.name\":\"项目\",\"code\":\"0001\",\"name\":\"测试开发项目\",\"businessType.name\":\"项目\",\"category.code\":\"001\",\"category.name\":\"分类A\",\"projectProperties\":\"ProjectProperties.develop\",\"projectGroup.code\":\"xmfz01\",\"projectGroup.name\":\"项目分组一\",\"salesOrg.code\":\"qq-bjqq\",\"salesOrg.name\":\"北京企企\",\"customer.name\":\"客户1\",\"ownerDept.name\":\"bj财务部\",\"ownerUser.name\":\"双双\",\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"planStartDate\":\"2022-11-15\",\"planEndDate\":\"2022-12-13\",\"scheduledDuration\":31,\"enableStage\":true,\"stageGroup.name\":\"项目阶段1-3\",\"businessDate\":\"2022-11-03\",\"enableChangeApprove\":true,\"baseBillId\":\"8RPN3261UAT00A0\",\"changeBizReasonId\":\"8B89ER50QFU1007\",\"changeDate\":\"2022-11-05 20:03:55\",\"isChangeBill\":true,\"stages\":[{\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"stage.code\":\"0000001\",\"stage.name\":\"需求阶段\",\"planStartDate\":\"2022-11-18\",\"planEndDate\":\"2022-11-29\",\"scheduledDuration\":8,\"outcome\":\"前期准备过半\",\"ownerUser.name\":\"周小七\",\"description\":\"需求准备\",\"basebillId\":\"8RPN3261UAT00A0\",\"basebillItemId\":\"8RPN3261UAT00A3\"},{\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"stage.name\":\"上线阶段\",\"planStartDate\":\"2022-11-30\",\"planEndDate\":\"2022-12-10\",\"scheduledDuration\":8,\"outcome\":\"前期准备过半\",\"ownerUser.name\":\"周小七\",\"description\":\"需求准备\"}],\"members\":[{\"department.name\":\"bj财务部\",\"user.name\":\"曹操\",\"basebillId\":\"8RPN3261UAT00A0\",\"basebillItemId\":\"F63Q3261UAT007W\"}],\"deliverOrgs\":[{\"basebillId\":\"8RPN3261UAT00A0\",\"basebillItemId\":\"8RPN3261UAT00A4\",\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\"}],\"changeTypes\":[{\"changeTypeId\":\"VPTEHU50J680001\",\"objectType\":\"Project\"},{\"changeTypeId\":\"VPTEHU50J680002\",\"objectType\":\"Project\"},{\"changeTypeId\":\"0FBW1U50JEC0001\",\"objectType\":\"Project\"},{\"changeTypeId\":\"0FBW1U50JEC0002\",\"objectType\":\"Project\"},{\"changeTypeId\":\"9GBW1U50JEC0001\",\"objectType\":\"Project\"},{\"changeTypeId\":\"9GBW1U50JEC0002\",\"objectType\":\"Project\"},{\"changeTypeId\":\"NAGALW515KX001N\",\"objectType\":\"Project\"}],\"externalObjectId\":\"2100004112\",\"externalObjectType\":\"Project\",\"externalSystemCode\":\"210004\"}}"
}

c. 使用sdk,新增项目变更单单示例如下

public void testAdd() {
  PostAddRequest request = new PostAddRequest();
  ApiParams apiParams = new ApiParams();
  apiParams.setJson("{\"objectType\":\"Project\",\"data\":{\"createdOrg.code\":\"qq-bjqq\",\"createdOrg.name\":\"北京企企\",\"webEditTemplate.name\":\"项目\",\"financialOrg.code\":\"qq-bjqq\",\"financialOrg.name\":\"北京企企\",\"billType.name\":\"项目\",\"code\":\"0001\",\"name\":\"测试开发项目\",\"businessType.name\":\"项目\",\"category.code\":\"001\",\"category.name\":\"分类A\",\"projectProperties\":\"ProjectProperties.develop\",\"projectGroup.code\":\"xmfz01\",\"projectGroup.name\":\"项目分组一\",\"salesOrg.code\":\"qq-bjqq\",\"salesOrg.name\":\"北京企企\",\"customer.name\":\"客户1\",\"ownerDept.name\":\"bj财务部\",\"ownerUser.name\":\"双双\",\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"planStartDate\":\"2022-11-15\",\"planEndDate\":\"2022-12-13\",\"scheduledDuration\":31,\"enableStage\":true,\"stageGroup.name\":\"项目阶段1-3\",\"businessDate\":\"2022-11-03\",\"enableChangeApprove\":true,\"baseBillId\":\"8RPN3261UAT00A0\",\"changeBizReasonId\":\"8B89ER50QFU1007\",\"changeDate\":\"2022-11-05 20:03:55\",\"isChangeBill\":true,\"stages\":[{\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"stage.code\":\"0000001\",\"stage.name\":\"需求阶段\",\"planStartDate\":\"2022-11-18\",\"planEndDate\":\"2022-11-29\",\"scheduledDuration\":8,\"outcome\":\"前期准备过半\",\"ownerUser.name\":\"周小七\",\"description\":\"需求准备\",\"basebillId\":\"8RPN3261UAT00A0\",\"basebillItemId\":\"8RPN3261UAT00A3\"},{\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\",\"stage.name\":\"上线阶段\",\"planStartDate\":\"2022-11-30\",\"planEndDate\":\"2022-12-10\",\"scheduledDuration\":8,\"outcome\":\"前期准备过半\",\"ownerUser.name\":\"周小七\",\"description\":\"需求准备\"}],\"members\":[{\"department.name\":\"bj财务部\",\"user.name\":\"曹操\",\"basebillId\":\"8RPN3261UAT00A0\",\"basebillItemId\":\"F63Q3261UAT007W\"}],\"deliverOrgs\":[{\"basebillId\":\"8RPN3261UAT00A0\",\"basebillItemId\":\"8RPN3261UAT00A4\",\"projectOrg.code\":\"qq-bjqq\",\"projectOrg.name\":\"北京企企\"}],\"changeTypes\":[{\"changeTypeId\":\"VPTEHU50J680001\",\"objectType\":\"Project\"},{\"changeTypeId\":\"VPTEHU50J680002\",\"objectType\":\"Project\"},{\"changeTypeId\":\"0FBW1U50JEC0001\",\"objectType\":\"Project\"},{\"changeTypeId\":\"0FBW1U50JEC0002\",\"objectType\":\"Project\"},{\"changeTypeId\":\"9GBW1U50JEC0001\",\"objectType\":\"Project\"},{\"changeTypeId\":\"9GBW1U50JEC0002\",\"objectType\":\"Project\"},{\"changeTypeId\":\"NAGALW515KX001N\",\"objectType\":\"Project\"}],\"externalObjectId\":\"2100004112\",\"externalObjectType\":\"Project\",\"externalSystemCode\":\"210004\"}}");
  request.sdkRequestConfig(getSdkRequestConfig(request, true, true));
  request.setApiParams(apiParams);
  PostAddResult postAddResult = openapi().postAdd(request);
  ApiResponse apiResponse = postAddResult.getApiResponse();
  System.out.println(apiResponse);
}

• 参数说明

  • Header 中的参数. Save-As-Draft 设置为true

  • 将原来的项目变更后的数据全量写在新增的变更单中，并在新的变更单中添加以下参数

{
   "objectType": "Project",
   "data": {
       "enableChangeApprove":true, // 启用变更审批，固定为true
       "baseBillId":"8RPN3261UAT00A0", // 原项目单据id
       "changeBizReasonId":"8B89ER50QFU1007", // 变更原因
       "changeDate":"2022-11-04 19:03:55", // 变更日期
       "isChangeBill":true, // 是否为变更单，固定为true
       "customVersion":"v1.0", //  变更单版本号
       "stages":[
        {
          "basebillId":"8RPN3261UAT00A0", // 原项目单据id
          "basebillItemId":"8RPN3261UAT00A3" // 原项目阶段明细id 
        } 
       ],
       "members":[
        {
          "basebillId":"8RPN3261UAT00A0", // 原项目单据id
          "basebillItemId":"F63Q3261UAT007W" // 原项目团队成员明细id
        }
       ],
       "deliverOrgs":[
        {
          "basebillId":"8RPN3261UAT00A0", // 原项目单据id
          "basebillItemId":"8RPN3261UAT00A4" // 原项目交付组织明细id
        }
       ],
       "changeTypes":[  //变更类型字表，固定
        {
          "changeTypeId":"VPTEHU50J680001",
          "objectType":"Project"
        },
        {
          "changeTypeId":"VPTEHU50J680002",
          "objectType":"Project"
        },
        {
          "changeTypeId":"0FBW1U50JEC0001",
          "objectType":"Project"
        },
        {
          "changeTypeId":"0FBW1U50JEC0002",
          "objectType":"Project"
        },
        {
          "changeTypeId":"9GBW1U50JEC0001",
          "objectType":"Project"
        },
        {
          "changeTypeId":"9GBW1U50JEC0002",
          "objectType":"Project"
        },
        {
          "changeTypeId":"NAGALW515KX001N",
          "objectType":"Project"
        }
       ]
      }
    }

• 新的变更单中添加以下参数说明

字段名称	字段含义	是否固定
enableChangeApprove	启用变更审批	固定为true
baseBillId	原合同id,即需要变更的合同id	否
changeBizReasonId	变更原因	可固定
changeDate	变更日期	否
isChangeBill	是否是变更单	固定值 true
baseBillItemId	为原合同的标的明细对应的id	否
changeTypes	变更类型	固定
customVersion	变更版本	否

d. 返回结果：

{
  "json": "{\"id\":\"8RPN3261UMN00D1\"}"
}

提交项目变更单

a. 使用接口，POST https://api2.77hub.com/v1/batchDo t同步任务接口。

b. 使用接口，POST https://api2.77hub.com/v1/asyncBatchDo 异步任务接口。

单据状态是未提交，已撤回，已退回，可以提交单据，同步异步接口任选其一。