京翎云享
  • 操作手册
  • 数据接口对接
京翎云享
2023-08-14
目录

数据接口对接

# 园区方数据接口对接

# 一、文档概述

# 1、对接须知

（1）需先联系商务申请测试环境数据；

（2）使用前请注意区分生产环境和测试环境；

（3）生产环境参数将在联调通过后提供；

（4）接口调用顺序：获取平台可配置的园区→新增商户→获取商户可使用的园区→新增个人→新增任务→申请发票

（5）对接此接口需客户系统拥有资金结算体系，通过内部结算体系将资金发放给个人后，调用下方接口将发放数据推送至京翎云享；

（6）正式上线前须联系业务申请园区（要使用的园区）公户（所属银行为客户内部系统使用的银行）。

# 二、通用信息

# 1、环境地址

名称 地址
测试环境 https://devyun.jinglingyunxiang.com/ (opens new window)
生产环境 https://yun.jinglingyunxiang.com/ (opens new window)

# 2、接口调用

请在调用接口中统一添加Header

参数名 必选 类型 说明
appID Y String 企业唯一标识
appSecret Y String 验签串

# 三、接口列表

# 1、查询平台绑定园区

# （1）接口描述

查询当前平台已配置的园区列表，后续用于创建商户时，为商户绑定园区。

# （2）请求URL

task_platform/api/v1/getThird

# （3）请求方式

POST JSON

# （4）请求参数

无

# （5）请求示例

无

# （6）返回参数

参数名 类型 说明
success Boolean 请求是否成功
message String 请求是否成功
Code Integer 请求码
data Object 响应信息

data参数说明

参数名 类型 说明
bussinessType Object 业务类型
thirdId String 园区id
name Object 园区名称

# （7）返回示例

{
    "success": true,
    "message": "succeed",
    "code": 200,
    "data": [
        {
            "bussinessType": "差额普",      
            "thirdId": 92,                 
            "name": "九江林旺科技有限公司"     
        },
        {
            "bussinessType": "灵活用工",
            "thirdId": 55,
            "name": "淅川县豹骑网络科技有限公司"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 2、新增/更新商户信息

# （1）接口描述

填写公司基本信息，新增商户获取平台商户ID，后续需要使用此ID更新商户信息、新增任务、新增用户、申请发票。

# （2）请求URL

task_platform/api/v1/addOrUpdateCompanyInfo

# （3）请求方式

POST JSON

# （4）请求参数

参数名 必选 类型 说明
id N Integer 平台商户ID，不填写此项为新增，填写ID则为更新信息
companyName Y String 公司名称
companyType Y String 企业类型
industry Y String 行业
foundTime Y Date 成立时间
issuingAuthority Y String 发证机构
businessAddress Y String 企业经营地址
companyProfile Y String 企业简介信息
taxType Y Integer 公司类型：1一般人，2小规模
taxpayerIdentificationNumber Y String 统一社会信用代码，15/18/20位
registeredAddress Y String 企业注册地址（发票）
registrationPhone Y String 注册固定电话（发票）
accountName Y String 开户银行名称（发票）
accountNo Y String 开户银行账号（发票）
received Y String 收件人姓名（纸质发票邮寄）
receivedPhone Y String 收件人电话（纸质发票邮寄）
receivedAddress Y String 收件人地址（纸质发票邮寄）
responsibleName Y String 负责人姓名
responsiblePhone Y String 负责人电话
responsibleEmail Y String 负责人邮箱
customerPoint Y String 客户点位：8%
legalIdcard Y String 法人身份证人像面（文件URL）
legalIdcardNational Y String 法人身份证国徽面（文件URL）
businessLicense Y String 营业执照扫描件（文件URL）
openingPermit Y String 开户许可证（文件URL）
cooperationAgreement Y String 合作协议（文件URL）
serviceInvoiceType Y Inteage 服务费发票类型 1-普票，2-专票
thirdIds Y ListInteger 园区id（通过平台可配置园区接口获得）

# （5）请求示例

{
    "id": 95,
    "companyName": "北京爱牛保洁服务有限公司",
    "companyType": "国有企业",
    "industry": "教育",
    "foundTime": "2022-04-29 00:00:00",
    "issuingAuthority": "北京市场监督管理局",
    "businessAddress": "企业经营地址",
    "companyProfile": "公司简介信息",
    "taxType": 1,
    "taxpayerIdentificationNumber": "91110117MA7EKJ2651",
    "registeredAddress": "企业注册地址",
    "registrationPhone": "zhucegudingdianhua",
    "accountName": "开户银行名称",
    "accountNo": "kaihuyinhangzhanghao",
    "received": "收件人姓名",
    "receivedPhone": "14410000011",
    "receivedAddress": "收件人地址",
    "responsibleName": "负责人名称",
    "responsiblePhone": "17600009999",
    "responsibleEmail": "ls@jlkg.com",
    "customerPoint": "8%",
    "legalIdcard": "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg",
    "legalIdcardNational": "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg",
    "businessLicense": "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg",
    "openingPermit": "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg",
    "cooperationAgreement": "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg",
    "serviceInvoiceType": 1,
    "thirdIds": [
        92,
        55
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# （6）返回参数

参数名 类型 说明
success Boolean 请求是否成功
message String 请求是否成功
Code Integer 请求码
data Object 响应信息

data参数说明

参数名 类型 说明
data String 平台商户ID

# （7）返回示例

{
    "success": true,
    "message": "succeed",
    "code": 200,
    "data": 51    
}
1
2
3
4
5
6

# 3、查询商户园区

# （1）接口描述

查询当前商户已绑定的园区列表，后续用于推送任务数据时使用

# （2）请求URL

task_platform/api/v1/getCompanyThird

# （3）请求方式

POST JSON

# （4）请求参数

参数名 必选 类型 说明
companyInfoId Y Integer 商户ID

# （5）请求示例

{
    "companyInfoId": 51
}
1
2
3

# （6）返回参数

参数名 类型 说明
success Boolean 请求是否成功
message String 请求是否成功
Code Integer 请求码
data Object 响应信息

data参数说明

参数名 类型 说明
bussinessType Object 业务类型
thirdId String 园区id
name Object 园区名称

# （7）返回示例

{
    "success": true,
    "message": "succeed",
    "code": 200,
    "data": [
        {
            "bussinessType": "差额普",         
            "thirdId": 92,                    
            "name": "九江林旺科技有限公司"     
        },
        {
            "bussinessType": "灵活用工",
            "thirdId": 55,
            "name": "淅川县豹骑网络科技有限公司"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 4、新增用户信息

# （1）接口描述

调用接口新增用户，获取用户ID，此用户ID后续用于更新用户信息

# （2）请求URL

task_platform/api/v1/addOrUpdatePerrsonal

# （3）请求方式

POST JSON

# （4）请求参数

参数名 必选 类型 说明
id N Integer 用户ID，不填写此项为新增，填写ID则为更新信息
companyId Y Integer 公司ID
name Y String 姓名
idNumber Y String 身份证号
phone Y String 手机号
bankCard Y String 银行卡号
idcardPhoto N String 身份证人像（文件URL）
idcardNational N String 身份证国徽（文件URL）
serviceAgreement Y String 服务协议（文件URL）

# （5）请求示例

{
    "companyId": 1,
    "name": "张三",
    "idNumber": "42032219600118042X",
    "phone": "17347590334",
    "bankCard": "6214858783240112",
    "idcardPhoto": "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg",
    "idcardNational": "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg",
    "serviceAgreement": "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg"
}
1
2
3
4
5
6
7
8
9
10

# （6）返回参数

参数名 类型 说明
success Boolean 请求是否成功
message String 请求是否成功
Code Integer 请求码
data Object 响应信息

data参数说明

参数名 类型 说明
data String 平台用户ID

# （7）返回示例

{
    "success": true,
    "message": "succeed",
    "code": 200,
    "data": 3     
}
1
2
3
4
5
6

# 5、新增任务信息

# （1）接口描述

根据实际业务需求，创建符合要求的任务，获取任务流水号，后续使用该任务流水号申请发票

# （2）请求URL

task_platform/api/v1/taskWarehousing

# （3）请求方式

POST JSON

# （4）请求参数

参数名 必选 类型 说明
companyId Y Integer 平台商户ID
taskName Y String 任务名称
taskDetail Y String 任务描述
numberOfPeople Y Integer 需求人数 (需求人数=个人任务集合总人数 )
taskAmount Y BigDecimal 任务金额 (任务金额=个人任务集合任务金额总和)
serviceCharge Y BigDecimal 服务费金额 (服务费金额=个人任务集合服务费金额总和)
totalTaskAmount Y BigDecimal 任务总金额 (任务总金额=任务金额+服务费金额)
businessAddress Y String 业务实际发生地址
releaseTime Y Date 创建时间
completionTime Y Date 完成时间
thirdId Y Integer 园区id
taskInfoDTOList Y List 个人任务集合

taskInfoDTOList

参数名 必选 类型 说明
name Y String 用户姓名
idCard Y String 身份证号
bankCard Y String 银行卡号
taskContent Y String 工作内容
taskAmount Y BigDecimal 任务金额（实际发放金额）
serviceCharge Y BigDecimal 服务费
taskCreateTime Y Date 个人任务创建时间
taskCompleteTime Y Date 个人任务完成时间
paySuccessTime Y Date 个人任务支付时间
returnInvoiceNo N String 退票唯一标识（建议使用时间戳，避免重复）

# （5）请求示例

{
    "companyId": 1,
    "taskName": "保洁服务",
    "taskDetail": "清理别墅区卫生",
    "numberOfPeople": 2,
    "taskAmount": 100000.01,
    "serviceCharge": 600,
    "totalTaskAmount": 100600.01,
    "businessAddress": "北京-朝阳",
    "releaseTime": "2022-12-23 12:02:33",
    "completionTime": "2022-12-23 14:02:33",
    "thirdId": 55,
    "taskInfoDTOList": [
        {
            "name": "张三",
            "idCard": "42032219600118042X",
            "bankCard": "6214858783240112",
            "taskContent": "工作内容-视频剪辑",
            "taskAmount": 90000.01,
            "serviceCharge": 540,
            "taskCreateTime": "2022-12-23 12:02:33",
            "taskCompleteTime": "2022-12-23 13:02:33",
            "paySuccessTime": "2022-12-23 14:02:33"
        },
        {
            "name": "张三",
            "idCard": "42032219600118042X",
            "bankCard": "6214858783240112",
            "taskContent": "内容-垃圾清运",
            "taskAmount": 10000,
            "serviceCharge": 60,
            "taskCreateTime": "2022-12-23 13:02:33",
            "taskCompleteTime": "2022-12-23 14:02:33",
            "paySuccessTime": "2022-12-23 15:02:33"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# （6）返回参数

参数名 类型 说明
success Boolean 请求是否成功
message String 请求是否成功
Code Integer 请求码
data Object 响应信息

data参数说明

参数名 类型 说明
data String 平台任务流水号

# （7）返回示例

{
    "success": true,
    "message": "succeed",
    "code": 200,
    "data": "20230811153414554qfg" 
}
1
2
3
4
5
6

# 6、订单退票接口

# （1）接口描述

针对退票订单进行处理，调用该接口后，相关个人订单状态变更为退票

# （2）请求URL

task_platform//api/v1/taskReturnInvoice

# （3）请求方式

POST JSON

# （4）请求参数

参数名 必选 类型 说明
taskSerial Y String 任务流水号
returnInvoiceList Y List 退票人员列表

returnInvoiceListL：

参数名 必选 类型 说明
returnInvoiceNo Y String 退票唯一标识（新增任务接口taskInfoDTOList中传输的returnInvoiceNo字段）
returnInvoiceTime Y Date 退票时间

# （5）请求示例

{
    "taskSerial": "20231109220721000pns",
    "returnInvoiceList": [
        {
            "returnInvoiceNo": "222",
            "returnInvoiceTime": "2023-11-09 15:36:22"
        }
    ]
}
1
2
3
4
5
6
7
8
9

# （6）返回参数

参数名 类型 说明
success Boolean 请求是否成功
message String 请求是否成功
Code Integer 请求码
data Object 响应信息

# （7）返回示例

{
    "success": true,
    "message": "succeed",
    "code": 200,
    "data": null
}
1
2
3
4
5
6

# 7、申请发票接口

# （1）接口描述

调用此接口为当前商户已完成的任务申请发票。

# （2）请求URL

task_platform/api/v1/requestInvoice

# （3）请求方式

POST JSON

# （4）请求参数

参数名 必选 类型 说明
companyId Y Integer 平台商户ID
thirdId Y Integer 园区ID
startTime N Date 开始时间
endTIme N Date 结束时间
taskSerials N ListString 任务流水号
invoiceType Y String 发票类型：1-专票、2-普票 （差额普业务当前仅支持开具普票）
invoiceCategory Y String 发票类目
invoiceAmount Y BigDecimal 发票金额
说明:
支持以下几种场景
1、companyId+thirdId+taskSerials：用于商户在某个园区单笔/批量提交发票申请
2、companyId+thirdId：用于将商户在某个园区所有已完成未开票的任务提交申请
3、companyId+thirdId+startTime+endTIme：用于将商户在某个园区时间区间(按照任务完成时间)内的任务提交发票申请
1
2
3
4
5

# （5）请求示例

{
    "companyId": 1,
    "taskSerials": [
        "20230811115836342bjq",
        "20230825645836342ova"
    ],
    "invoiceType": "专票",
    "invoiceAmount": 300,
    "invoiceCategory": "*信息技术服务*技术服务费"
}
1
2
3
4
5
6
7
8
9
10

# （6）返回参数

参数名 类型 说明
success Boolean 请求是否成功
message String 请求是否成功
Code Integer 请求码
data Object 响应信息

data参数说明

参数名 类型 说明
stauts String 开票状态
message Object 状态说明
invoiceNo String 发票编号

# （7）返回示例

{
    "success": true,
    "message": "succeed",
    "code": 200,
    "data": {
        "status": 2,
        "message": "开票中",
        "invoiceNo": "20230813121338100002"
    }
}
1
2
3
4
5
6
7
8
9
10

# 8、发票回传接口

# （1）接口描述

开票成功后可回传发票附件。

# （2）请求URL

需要贵司提供发票开出后回传发票附件的回调地址

# （3）请求方式

POST JSON

# （4）请求参数

参数名 必选 类型 说明
invoiceNo Y String 发票编号（提交发票申请后获得）
invoiceUrl Y List 发票附件下载路径（多张）

# （5）请求示例

{
    "invoiceNo": "20221218224508659oav",
    "invoiceUrl": [
        "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg",
        "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg",
        "https://yun.jinglingyunxiang.com/var/upload/logo.jpeg"
    ]
}
1
2
3
4
5
6
7
8

# （6）返回参数

无

# （7）返回示例

无

上次更新: 2024/08/22, 17:26:16
商户对接接口
SaaS服务平台

← SaaS服务平台→

Theme by Vdoing | Copyright © -2024 ©2016-2023 京翎云享平台 版权所有 ICP证： 京ICP备2023008449号-1