# Finance APIs
此组api用来实现业务系统和财务预约系统的整合。
- 使用本组API前请先阅读概述，使用前的准备工作请参考此处，令牌的获取参考此处，构造请求请参考此处，返回数据请参考此处，除非特殊注明，所有开放式API有着通用的返回结构。
- 每个API的授权方式、授权范围和是否API SDK支持请查看以下每个API详细的表述。
此组api实现以下目的：
- 引导用户启动一个财务预约申请，限制用户修改预约中的部分信息项
- 撤销一个之前启动的预约申请
- 获取预约处理的状态
由此组api启动的每笔财物预约在业务系统中均需对应一业务系统业务，以businessType+businessNo唯一确定
- businessType: 业务系统内部的业务分类，最长6位字符串，由业务系统自行确定
- businessNo: 业务号，最长20位字符串。对于流程平台的应用，推荐使用流程流水号。
# 一般交互设计
- 业务系统根据自身业务规则产生报销需求后，通过PUT接口提交该财务报销的相关数据
- 业务系统向用户提供进入财务预约系统编辑该项预约的操作入口，入口地址在PUT或GET操作的响应数据中提供
- 用户进入财务预约系统，编辑或者补充必要信息，提交预约单并按常规报销流程办理
- 业务系统通过GET接口轮询业务的办理状态
- 如业务系统发现业务状态为已入账（已入账的建议判断逻辑为：response.status.code in (20, 30) 并且更新时间response.updateTime早于当天零点），在完成自身业务处理后，通过POST接口标记业务为已完成
- 如业务规则允许用户修改信息后重新预约，业务系统应在用户修改前，调用DELETE接口先行撤销该笔业务，如果撤销失败，业务系统应阻止用户修改。
# 获取所有预约处理的状态
- GET https://api.sjtu.edu.cn/v1/finance/appointments/{businessType}?fetchAll={true|false} 客户端 connect_finance
# 功能介绍
获取指定业务分类下所有预约处理的状态
# 请求参数
- 路径参数 businessType 自拟定业务分类
- 请求参数 fetchAll true: 查询所有预约（目前暂不支持）, false: 仅查询财务已处理完成但业务系统未完成的预约
# 响应参数
所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。
- Appointment 财务预约 Structure
{
"businessType":{string}, //业务分类，长度最大6，由业务系统自定义。
"businessNo":{string}, //业务号，长度最大20，推荐使用流程流水号。businessType + businessNo应在业务系统中唯一标识一笔报销业务。
"attachmentCount":{int}, //附件张数。0表示不指定，如果指定，将不可修改。
"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}, //*实际报销人姓名
"finished":{boolean}, //业务系统是否确认该业务为已完成。一项业务只有业务系统调用"标记业务处理完成"接口明确标记为已完成后，该属性才为true。
//同时，调用"标记业务处理完成"接口时，该属性需要设置为true，且仅需设置该属性
"details":[{ //报销明细项。对于校内转账，不支持多条明细
"sourceAccount":{string}, //*经费来源的财务账号。不提供时可在财务系统预约界面再指定，但sourceAccount和code应至少指定一项。
"code":{string}, //*报销项代码。取值业务对接时咨询财计处。不提供时可在财务系统预约界面再指定，但sourceAccount和code应至少指定一项。
"amount":{number} //*报销金额。不提供表示不限制金额，可在财务系统预约界面再指定；0表示不允许的报销项目，一般和特定的报销项代码组合使用。
}],
"targets":[{ //支付对象明细。每个支付对象应在person、external、internal中提供且仅提供一项，并应和支付方式（targetType）吻合
"person": { //转卡
"name":{string}, //姓名
"code":{string} //学工号
},
"external": { //汇款
"name":{string}, //对方单位名称/姓名
"identityNo":{string}, //对方身份证号。业务类型(type)为酬金时必须提供
"bankAccount": {string},//银行账号
"bankCode":{string} //银行联行号
},
"internal": { //校内转账
"targetAccount":{string}//转入的财务经费账号
},
"amount":{number}, //*支付金额。
"remark":{string} //*支付附言。
}],
"mallItems":[{ //商城物品清单。报销商城订单商品时提供，总金额不能超时根据报销明细或者支付明细确定的金额。
"mallId": {string}, //商城id
"orderNo": {string}, //商城订单号
"skuNo": {string}, //商品编号
"amount": {number} //商品金额
}],
"attachments": [{ //报销附件。暂时和attachmentCount不构成对照检查
"name":{string}, //附件名称
"invoice": {boolean}, //附件是否发票。2024-04-15新增，默认false。
"url":{string}, //附件下载地址
"digest":{string} //附件内容md5
}],
/***** 以下属性只读 *****/
"amount":{number}, //总金额，由报销明细项金额或者支付明细项金额累加所得，如均未指定，此项为0。
"url":{string}, //在财务系统中打开该预约的连接。该属性仅在获取单个业务或者提交新业务时返回
"urlNew":{string}, //在财务系统（智能报销预约，推荐使用）中打开该预约的连接。该属性仅在获取单个业务或者提交新业务时返回
"createTime":{long}, //业务创建时间。Unix时间戳
/***** 以下属性由财务系统反馈，用户在财务系统中提交预约单后提供，如预约单被撤销（包括通过DELETE接口或者用户在财务系统中操作），反馈信息同时删除 *****/
"response": { //财务系统反馈
"appointmentNo":{string}, //预约号。
"actualAmount":{number} //实际入账总金额。
"updateTime":{long}, //反馈更新时间。Unix时间戳
"status": { //业务状态。可能的状态有：10 预约成功, 15 财务拒绝, 16 异常, 20 已做账未审核, 30 已做账已审核
"code":{int}, //状态码。如10
"description":{string} //状态文字描述。如"预约成功"
},
"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}, //凭证号。财务系统原始返回值去除分录后的值，如2021 3B 28920
"amount":{number}, //入账金额
"originalVoucherNo":{string} //原始凭证号。财务系统的原始返回值，如2021 3B 28920,1
}]
}
}
* 这些属性一旦指定值，操作人将不能在财务预约系统中修改
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
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
# 获取单个预约处理的状态
- GET https://api.sjtu.edu.cn/v1/finance/appointments/{businessType}/{businessNo} 客户端 connect_finance
# 功能介绍
获取单个预约处理的状态
# 请求参数
- 路径参数 businessType 自拟定业务分类
- 路径参数 businessNo 业务号
# 响应参数
所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。
同获取指定业务分类下所有预约处理的状态接口，参见以上的Appointment 财务预约响应参数
# 提交新的业务
- PUT https://api.sjtu.edu.cn/v1/finance/appointments/{businessType}/{businessNo} 客户端 connect_finance
# 功能介绍
提交新的业务
# 请求参数
- 路径参数 businessType 自拟定业务分类
- 路径参数 businessNo 业务号
- 请求体参数 财务预约数据，结构参见Appointment 财务预约
# 响应参数
所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。
同获取指定业务分类下所有预约处理的状态接口，参见以上的Appointment 财务预约响应参数
# 撤销业务
- DELETE https://api.sjtu.edu.cn/v1/finance/appointments/{businessType}/{businessNo} 客户端 connect_finance
# 功能介绍
对应业务若已在财务系统中预约，将尝试在财务系统中撤销，如财务系统撤销失败，本接口也将失败。业务撤销成功后，查询接口将不再返回该笔业务的相关数据，视作已删除。
# 请求参数
- 路径参数 businessType 自拟定业务分类
- 路径参数 businessNo 业务号
# 标记业务处理完成
- POST https://api.sjtu.edu.cn/v1/finance/appointments/{businessType}/{businessNo} 客户端 connect_finance
# 功能介绍
标记业务处理完成
# 请求参数
- 路径参数 businessType 自拟定业务分类
- 路径参数 businessNo 业务号
# 响应参数
所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。
同获取指定业务分类下所有预约处理的状态接口，参见以上的Appointment 财务预约响应参数