# Finance APIs
此组api用来实现业务系统和财务预约系统的整合。
- 使用本组API前请先阅读概述，使用前的准备工作请参考此处，令牌的获取参考此处，构造请求请参考此处，返回数据请参考此处，除非特殊注明，所有开放式API有着通用的返回结构。
- 每个API的授权方式、授权范围和是否API SDK支持请查看以下每个API详细的表述。
此组api实现以下目的：
- 引导用户启动一个财务预约申请，限制用户修改预约中的部分信息项
- 撤销一个之前启动的预约申请
- 获取预约处理的状态
由此组api启动的每笔财物预约在业务系统中均需对应一业务系统业务，以businessType+businessNo唯一确定
- businessType: 业务系统内部的业务分类，最长6位字符串，由业务系统自行确定
- businessNo: 业务号，最长20位字符串。对于流程平台的应用，推荐使用流程流水号。
# 一般交互设计
1、业务系统根据自身业务规则产生报销需求后，通过PUT接口提交该财务报销的相关数据。
- 【2024-08新增】如果业务系统提交的业务为即刻提交类型，提交后将立即产生预约单号，进入财务系统审核，无需进行步骤2、3。
当前仅校内转账类型的业务支持即刻提交。
2、业务系统向用户提供进入财务预约系统补充该项预约的其他信息并提交预约的操作入口，入口地址在PUT或GET操作的响应数据中提供。
3、用户进入财务预约系统，编辑或者补充必要信息，提交预约单。预约单提交后进入财务系统审核，按常规报销流程办理。
4、业务系统通过GET接口轮询业务的办理状态。
5、如业务系统发现业务状态为已入账已审核（建议判断逻辑为：response.status.code == 30 并且更新时间response.updateTime早于当天零点），在完成自身业务处理后，通过POST接口标记业务为已完成。
6、如业务规则允许用户修改信息后重新预约，业务系统应在用户修改前，调用DELETE接口先行撤销该笔业务，如果撤销失败，业务系统应阻止用户修改。
# 获取单个业务详情
- GET https://api.sjtu.edu.cn/v1/finance/appointments/{businessType}/{businessNo} 客户端 connect_finance SDK
# 功能介绍
获取单个业务详情
# 路径请求参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| businessType | string | 自拟定业务分类 |
| businessNo | string | 业务号 |
# URL请求参数
| 参数名 | 类型 | 描述 | 备注 |
|---|---|---|---|
| history | boolean | 是否获取财务审核记录 | 默认为false，表示不获取 |
# 响应参数
所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。
- Appointment 财务预约 Structure
{
"businessType":{string}, //业务分类，长度最大6，由业务系统自定义。
"businessNo":{string}, //业务号，长度最大20，推荐使用流程流水号。businessType + businessNo应在业务系统中唯一标识一笔报销业务。
"submitInstantly":{boolean}, //是否为即刻提交的业务。默认为false，当前仅业务类型(type)为校内经费转账的业务支持即刻提交。
"attachmentCount":{int}, //附件张数。对于非即刻提交的业务，0表示不指定，如果指定，将不可修改；对于即刻提交的业务，无需提供，由attachments自动计算。
"remark":{string}, //备注初始值。操作人在财务预约系统中可以修改。
"type":{string}, //*业务类型。合法值有："日常报销", "国内差旅", "暂借", "校内经费转账", "酬金", "因公出国", "因公出国借款", "境外专家来访", "会议"
"subType1":{string}, //业务子类型1。
"subType2":{string}, //业务子类型2。业务子类型1、2的取值根据业务类型而定，酬金业务，子类型1填写酬金性质（如奖学金），子类型2填写人员性质（如本科生）
"targetType":{string}, //*支付方式。合法值有："person" 个人转卡, "external" 银行汇款, "internal" 校内经费转账, "combined" 个人转卡+银行汇款
"applyer": { //*申请人(登录财务预约系统提交预约单的用户)信息。
"id":{string}, //*工号
"name":{string}, //*姓名
"telephone":{string}, //*联系电话。
"mobile":{string}, //*联系手机
"email":{string} //*联系邮箱
},
"operator":{string}, //*实际报销人姓名
"operatorWorkNo":{string}, //实际报销人工号。仅即刻提交类型的业务需要指定。
"approverWorkNo":{string}, //业务审核人工号。仅即刻提交类型的业务可以指定。
"reviewerWorkNo":{string}, //业务复核人工号。仅即刻提交类型的业务可以指定。
"specialRemark":{string}, //特别事项说明。仅即刻提交类型的业务可以指定。
"finished":{boolean}, //业务系统是否确认该业务为已完成。一项业务只有业务系统调用"标记业务处理完成"接口明确标记为已完成后，该属性才为true。
//同时，调用"标记业务处理完成"接口时，该属性需要设置为true，且仅需设置该属性
"details":[{ //报销明细项。对于非即刻提交的校内经费转账，不支持多条明细，即刻提交的校内经费转账可以支持多条但转出财务项目号必须相同。
"sourceAccount":{string}, //*经费的转出财务项目号。非即刻提交类型的业务不提供时可在财务系统预约界面再指定，但sourceAccount和code应至少指定一项。即刻提交类型的业务必须提供。
"code":{string}, //*费用项代码。取值业务对接时咨询财计处。非即刻提交类型的业务不提供时可在财务系统预约界面再指定，但sourceAccount和code应至少指定一项。即刻提交类型的业务必须提供。
"amount":{number} //*转出金额。非即刻提交类型的业务不提供表示不限制金额，可在财务系统预约界面再指定；0表示不允许的报销项目，一般和特定的报销项代码组合使用。即刻提交类型的业务必须提供明确金额。
"budgetCode":{string}, //转出使用的预算项代码。非即刻提交类型的业务不提供，即刻提交类型的业务必须提供。
"grantId":{integer}, //申请人对应转出财务项目号的授权号。非即刻提交类型的业务不提供，即刻提交类型的业务，如果申请人为转出财务项目的授权使用人，此项必须提供。
}],
"targets":[{ //支付对象明细。每个支付对象应在person、external、internal中提供且仅提供一项，并应和支付方式（targetType）吻合
"person": { //转卡
"name":{string}, //姓名
"code":{string} //学工号
},
"external": { //汇款
"name":{string}, //对方单位名称/姓名
"identityNo":{string}, //对方身份证号。业务类型(type)为酬金时必须提供
"bankAccount": {string},//银行账号
"bankCode":{string} //银行联行号
},
"internal": { //校内转账
"targetAccount":{string}, //转入财务项目号
"targetCollegeAccount":{string} //转入的财务归集项目号。非即刻提交类型的业务不提供，即刻提交类型的业务如果转入财务项目为需归集项目，必须指定归集项目号。
},
"amount":{number}, //*支付金额。
"remark":{string} //*支付附言。
}],
"mallItems":[{ //商城物品清单。报销商城订单商品时提供，总金额不能超时根据报销明细或者支付明细确定的金额。
"mallId": {string}, //商城id
"orderNo": {string}, //商城订单号
"skuNo": {string}, //商品编号
"amount": {number} //商品金额
}],
"trips":[{ //商旅平台行程票据清单。报销商旅平台行程票据时提供，总金额不能超时根据报销明细或者支付明细确定的金额。
"tripId": {string}, //商旅平台行程票据id（TKS_ID）
"amount": {number} //金额
}],
"attachments": [{ //报销附件。暂时和attachmentCount不构成对照检查
"name":{string}, //附件文件名称。需包含文件扩展名，且仅支持pdf、odf、png、jpeg、jpg、gif。
"invoice": {boolean}, //附件是否发票。2024-04-15新增，默认false。即刻提交业务不使用此项信息。
"url":{string}, //附件下载地址。
"digest":{string} //附件内容md5。即刻提交业务不使用此项信息。
}],
/***** 以下属性只读 *****/
"amount":{number}, //总金额，由报销明细项金额或者支付明细项金额累加所得，如均未指定，此项为0。
"url":{string}, //在财务系统中打开该预约的连接。该属性仅在获取单个业务或者提交新业务时返回
"urlNew":{string}, //在财务系统（智能报销预约，推荐使用）中打开该预约的连接。该属性仅在获取单个业务或者提交新业务时返回
"createTime":{long}, //业务创建时间。Unix时间戳
/***** 以下属性由财务系统反馈。非即刻提交的业务，用户在财务系统中提交预约单后提供；即刻提交的业务，通过PUT接口提交数据后即提供。 *****/
"response": { //财务系统反馈
"appointmentNo":{string}, //预约号。
"updateTime":{long}, //反馈更新时间。Unix时间戳
"status": { //业务状态。可能的状态有：-1 已撤销, -3 已退回, 10 预约成功, 15 制单退回, 16 异常, 20 已做账未审核, 30 已做账已审核
"code":{int}, //状态码。如10
"description":{string} //状态文字描述。如"预约成功"，仅在查询单个业务时返回。
},
/**** 2024年8月调整，以下属性仅在查询单个业务时返回。 *****/
"actualAmount":{number}, //实际入账总金额。入账后提供。
"voucherNo":{string}, //凭证号。2024年8月新增。对于预约号的唯一凭证号（不含分录），如2021 3B 28920
"flowStatus": { //预约系统物流状态码。
//可能的状态有：
//1 预约成功，2 预约单已接收，等待分配，3 预约单已分配，等待制单，4 制单完成，等待复核，
//5 复核完成，7 临时挂起，8 报销失败，9 报销完成，21 取消预约单接收，31 取消预约单分配
"code":{int}, //状态码。如1
"description":{string} //状态文字描述。如"预约成功"
},
"details":[{ //入账明细(转出项目纬度)
"sourceAccount":{string}, //转出项目号
"code":{string}, //费用项代码
"name":{string}, //费用项名称
"voucherNo":{string}, //凭证号。2024年8月起，此项信息同时在上级结构中提供，不建议继续使用此处的值。
"amount":{number}, //转出金额
"originalVoucherNo":{string} //对应此项转出的凭证号，含分录，如2021 3B 28920,1
}],
"payDetails":[{ //入账支付明细。2024年8月新增。暂仅对即刻提交的校内经费转账业务提供。
"targetAccount":{string}, //转入项目号。
"amount":{number} //转入金额。
}],
"histories":[{ //财务审核记录。2024年8月新增。仅在查询单个业务并明确指定history查询参数时返回。
"stepName":{string}, //审核环节名称。
"operator":{ //操作人
"code":{string}, //操作人工号
"name":{string} //操作人姓名
},
"operateDate":{long}, //操作时间。unix时间戳，单位秒
"remark":{string} //审核意见。
}]
}
}
* 对于非即刻提交的业务，这些属性一旦指定值，操作人将不能在财务预约系统中修改。
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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# 获取已完成或已撤销/退回的业务
- GET https://api.sjtu.edu.cn/v1/finance/appointments/{businessType} 客户端 connect_finance SDK
# 功能介绍
获取指定业务分类下所有未标记已完成，但财务已完成(财务预约状态为30且入账时间早于当天零点)或财务已撤销(财务预约状态为-1)已退回(财务预约状态为-3、15)的业务。
注：
- 通过DELETE接口撤销的业务视为已删除，不在查询范围内。
- 预约状态30表示财务已入账已复核，但入账当日仍允许撤销，因此需等到入账次日才能确保业务完成。
- 预约状态-1表示已撤销，预约状态-3表示审核退回，预约状态15表示制单退回，均为对应预约号的终态。即使财务系统允许重新编辑后提交，新提交的预约是新的预约号，和本业务的关联将中断。
# 路径请求参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| businessType | string | 自拟定业务分类 |
- businessType
# URL请求参数
| 参数名 | 类型 | 描述 | 备注 |
|---|---|---|---|
| submitInstantly | boolean | 是否查询即刻提交的业务 | 默认为false，指查询非即刻提交业务 |
| withdraw | boolean | 查询已撤回/退回业务还是查询已完成业务 | 默认为false，指查询已完成的业务，指定为true时表示查询已撤回/退回的业务 |
# 响应参数
所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。
同获取单个业务详情接口，参见以上的Appointment 财务预约响应参数
# 提交新的业务
- PUT https://api.sjtu.edu.cn/v1/finance/appointments/{businessType}/{businessNo} 客户端 connect_finance SDK
# 功能介绍
提交新的业务
# 路径请求参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| businessType | string | 自拟定业务分类 |
| businessNo | string | 业务号 |
# 请求体
财务预约数据，结构参见Appointment 财务预约
# 响应参数
所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。
同获取单个业务接口，参见Appointment 财务预约响应参数
# 撤销业务
- DELETE https://api.sjtu.edu.cn/v1/finance/appointments/{businessType}/{businessNo} 客户端 connect_finance SDK
# 功能介绍
撤销业务，撤销成功后视同已删除。查询接口将不再返回该笔业务的相关数据，如果需要再次申请需要再次提交。
对应业务若已在财务系统中预约，将尝试在财务系统中撤销，如财务系统撤销失败，本接口也将失败。
# 路径请求参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| businessType | string | 自拟定业务分类 |
| businessNo | string | 业务号 |
# 标记业务处理完成
- POST https://api.sjtu.edu.cn/v1/finance/appointments/{businessType}/{businessNo} 客户端 connect_finance SDK
# 功能介绍
标记业务处理完成。
业务系统应该在获取到财务已入账状态，并完成自身处理后，使用此接口标记业务已完成。标记已完成的业务不会再出现在获取已完成或已撤销的业务接口返回数据中，可以有效增加接口的性能。 如果业务系统不使用此接口进行标记，则也不应该使用获取已完成或已撤销的业务接口进行批量查询。
# 路径请求参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| businessType | string | 自拟定业务分类 |
| businessNo | string | 业务号 |
# 请求体
财务预约数据，结构参见Appointment 财务预约，但仅需提供finished属性，且当前必须为true。
# 响应参数
所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。
同获取单个业务接口，参见以上的Appointment 财务预约响应参数