tysk/tyskFacecade.go

package tysk

import (
	"gitea.cdlsxd.cn/self-tools/tysk/tysk_constant"
	"gitea.cdlsxd.cn/self-tools/tysk/tysk_entity"
)

// TyskFacade 定义了司库系统的外观接口
type TyskFacade interface {
	Account //账户中心
	Settle  //结算中心

}

// Account 定义了账户相关的操作接口
type Account interface {
	// GetAccountBalance 账户余额查询
	// 查询司库中活期账户的实时余额信息。
	// 注意事项：
	// 1. 请求使用的银企直联用户需有相关账号的查询权限；
	// 2. 每次支持不多于20个账户的查询，返回当前司库同步到的账户余额信息；
	//    如果账户余额尚未查询到，司库统一返回金额字段为空。
	GetAccountBalance(accountList tysk_entity.GetAccountBalanceReq) (res map[tysk_constant.AccountNo]tysk_entity.GetAccountBalanceList, err error)

	// GetTodayTransHis 当日交易明细查询
	// 用于查询账户的当日交易明细信息。
	// 注意事项：
	// 1. 请求使用的银企直联用户需有相关账号的查询权限；
	// 2. 使用分页查询，起始记录号从1开始，每页最多显示100条记录；
	//    报文中的交易流水号sumTranNo由司库系统产生，用于标识客户交易明细数据唯一性。
	GetTodayTransHis(todayTransHisReq tysk_entity.TodayTransHisReq) (res tysk_entity.TodayTransHisResp, err error)

	// GetAccountInfo 账户信息查询
	// 用于查询客户在司库系统中维护的账号信息。
	// 注意事项：
	// 1. 请求使用的银企直联用户需有相关账号的查询权限；
	// 2. 使用分页查询，起始记录号从1开始，每页最多显示20条记录。
	GetAccountInfo(accountInfoReq tysk_entity.AccountInfoReq) (res tysk_entity.AccountInfoResp, err error)

	// ReceiptApply 电子回单申请
	// 实现司库电子回单查询申请，申请成功后需使用SKEDDQRY接口查询回单文件状态。
	// 注意事项：
	// 1. 账号需提前在司库系统内维护并为直联用户赋予查询权限；
	// 2. 电子回单下载需三步操作：
	//    - SKEDDRSQ 提交查询申请
	//    - SKEDDQRY 查询回单准备状态
	//    - SKEDCDTD 下载回单文件
	// 3. 接口限流：每台服务同时处理2笔交易，等待时间1秒
	// 4. 访问限制：同客户每天1000次
	// 5. 时间间隔最大为30天
	// 6. 支持当日回单的银行：中信、招商、平安、浦发、民生、中国银行、工商银行；
	//    不支持的银行返回错误码SE01100，并默认返回T-1日回单。
	ReceiptApply(receiptApplyReq tysk_entity.ReceiptApplyReq) (success bool, err error)

	// ReceiptQuery 电子回单查询
	// 客户可使用该接口，查询SKEDDRSQ（司库电子回单查询申请）接口发出的交易请求的处理结果。若查询返回成功，可根据查询出的回单编号在SKEDCDTD（司库电子回单文件下载）接口下载对应的回单文件。交易将返回明确成功、处理中、失败等状态
	// 注意事项：
	//1.账号需提前在司库系统内维护并为直联用户赋予查询权限；
	//2.司库电子回单下载获取需通过三部操作完成：1. SKEDDRSQ（司库电子回单查询申请）提交所需账号的电子回单查询申请；2. SKEDDQRY（司库电子回单文件查询）查询第一步中查询的电子回单信息是否准备完成，如完成则根据查询提供的分页信息返回相应的回单编号，如未完成则继续轮训该接口（若涉及的电子回单信息较多时建议适当延长轮训间隔）；3. SKEDCDTD（司库电子回单文件下载）根据回单编号对需要的回单文件进行下载。
	//3.接口限流机制：每台服务同时处理2笔交易，等待时间1秒
	//4.接口访问限制：同客户每分钟30次
	ReceiptQuery(receiptQueryReq tysk_entity.ReceiptQueryReq) (res tysk_entity.ReceiptQueryResp, err error)

	// ReceiptDownload 电子回单下载
	//客户可使用该接口，查询SKEDDRSQ（电子回单查询）接口发出的交易请求的处理结果。若查询返回成功，可根据查询出的回单编号在SKEDCDTD（司库电子回单文件下载）接口下载对应的回单文件。交易将返回明确成功、处理中、失败等状态
	// 注意事项：
	//1.账号需提前在司库系统内维护并为直联用户赋予查询权限；
	//2.司库电子回单下载获取需通过三部操作完成：1. SKEDDRSQ（司库电子回单查询申请）提交所需账号的电子回单查询申请；2. SKEDDQRY（司库电子回单文件查询）查询第一步中查询的电子回单信息是否准备完成，如完成则根据查询提供的分页信息返回相应的回单编号，如未完成则继续轮训该接口（若涉及的电子回单信息较多时建议适当延长轮训间隔）；3. SKEDCDTD（司库电子回单文件下载）根据回单编号对需要的回单文件进行下载。
	//3.接口限流机制：每台服务同时处理2笔交易，等待时间3秒
	//4.接口访问限制：同客户每分钟30次
	//5.每次数量为：20条
	//6.文件压缩后最大大小为：2M
	//7.在输入中新增“文件格式”字段，非必输，字典项为“OFD优先”、“PDF优先”。
	ReceiptDownload(receiptDownloadReq tysk_entity.ReceiptDownloadReq) (res tysk_entity.ReceiptDownloadResp, err error)

	// TransHisQueryApply 历史明细查询申请
	//使用该接口提交账户历史交易明细查询请求
	// 注意事项：
	//请求使用的银企直联用户需有相关账号的查询权限。
	TransHisQueryApply(transHisReq tysk_entity.TransHisQueryApplyReq) (res tysk_entity.TransHisQueryApplyResp, err error)

	// TransHisQuery 历史明细查询查询
	//使该接口用于查询账户的历史交易明细信息。
	// 注意事项：
	//1.请求使用的银企直联用户需有相关账号的查询权限	；
	//2.该交易使用分页查询，起始记录号从1开始，每页最多显示100条记录。报文中的交易流水号sumTranNo由司库系统产生，用于标识客户交易明细数据唯一性；
	//3.历史明细：申请（SKTRNHCL），查询（SKTRNHCT）可查司库已有境外银行数据（渣打、汇丰）
	TransHisQuery(transHisReq tysk_entity.TransHisQueryReq) (res tysk_entity.TransHisQueryResp, err error)

	// BalanceHisQueryApply 历史余额查询申请
	//客户可使用该接口提交账户历史余额查询申请
	// 注意事项：
	//1.请求使用的银企直联用户需有相关账号的查询权限；
	//2.账户历史余额查询申请每次支持不多于20个账户的查询。
	//3.可向前申请1年以内的历史余额数据，并且起始日期、终止日期之间的日期间隔不得大于90天。
	BalanceHisQueryApply(BalanceHisQueryApplyReq tysk_entity.BalanceHisQueryApplyReq) (res tysk_entity.BalanceHisQueryApplyResp, err error)

	// BalanceHisQuery 历史余额结果查询
	//客户可使用历史余额查询申请中提交的记录申请编号，来查询账户的历史余额数据。
	// 注意事项：
	//1.请求使用的银企直联用户需有相关账号的查询权限；
	//2.余额数据支持三种来源：01银行接口返回，即通过调用各银行的历史余额接口来获取数据；02银行明细返回，当对方行没有历史余额接口，而通过其当日最后一条银行流水明细中的余额字段来获取数据；03 明细数据计算，当对方行不支持历史余额接口、其明细也没有余额字段时，通过某日的余额基准数据，结合其间交易明细轧差计算，得出的历史余额数据；
	//3.数据状态01获取中，为余额数据获取的中间状态，如对方银行接口已调用，但尚未返回；02 已返回、03获取失败为余额数据获取的终态，其中返回03时，余额金额字段为空；
	//4.当数据来源01和02的时候，数据状态包括02或03；数据来源是03时，数据状态根据接口调用状态分别展示01、02或03.
	//5.历史余额：申请（SKBALHSQ），查询（SKBALHCX）可查司库已有境外银行数据（渣打、汇丰）
	BalanceHisQuery(BalanceHisQueryReq tysk_entity.BalanceHisQueryReq) (res tysk_entity.BalanceHisQueryResp, err error)

	// AccountsTransHisQuery 多账户历史明细查询
	//该接口用于查询多账户的历史交易明细信息。
	// 注意事项：
	//1.请求使用的银企直联用户需有相关账号的查询权限；
	//2.该交易使用分页查询，起始记录号从1开始，每页最多显示100条记录。报文中的交易流水号sumTranNo由司库系统产生，用于标识客户交易明细数据唯一性。
	AccountsTransHisQuery(AccountsTransHisQueryReq tysk_entity.AccountsTransHisQueryReq) (res tysk_entity.AccountsTransHisQueryResp, err error)
}

type Settle interface {
	//SinglePay 单笔支付
	//用于发起单笔付款申请，企业调用该接口推送单笔付款请求，司库系统接收该请求后生成单笔付款的申请任务，并返回受理状态。受理成功后，客户需依据司库系统配置的审批流程参数及工作流，完成司库系统的审批流转。待审批通过后，系统自动执行单笔付款交易指令，用户可通过单笔查证交易进行交易状态的查询。
	// 注意事项：
	//1.付方账号需提前在司库系统内维护为直联账户并为直联用户赋予单笔付款支付权限及付方单位的机构权限；
	//2.接口调用后立即返回司库受理状态，此状态只表示交易请求是否受理，若校验通过该笔付款将进入【司库系统】-【结算中心】-【单笔付款】功能，支付是否成功需稍后使用单笔查证交易进行查询。
	//3.在司库中优先级按照如下处理模式：
	//按照【金额】或【附言】进行审批流配置；若公共中心内，结算中心业务参数中开启按金额审批，则需同时配置按金额审批阈值。当ERP推送的单笔付款的付款金额超过设定的审批阈值时，则需落地审批，否则依据附言审批开关匹配是否需要审批。【金额】或【附言】开关均关闭时按照【业务模式参数】进行处理。
	//按照业务模式参数可支持三种模式：
	//1）审批处理，ERP传输的单据，直接到流程中心-待审批任务；
	//2)直接出账，只走司库接口，单据可在单笔付款查询功能查询；
	//3）经办处理时，需要在司库公共中心进行流程配置，单笔付款经办页面进行后续操作。
	//4.若该账户支持联动支付，资金会先从核心账户转入该支付账户中进行支付，资金下拨结果可在【单笔付款查证】接口中进行查看；
	//5.是否跨行，非必输字段，若用户上送，则以用户上送为准，若用户不上送，司库仍按照收付方银行判断是否跨行；
	SinglePay(singlePayReq tysk_entity.SinglePayReq) (res tysk_entity.SinglePayResp, err error)

	//SinglePayQuery 单笔付款查证
	//企业ERP等系统调用该接口查询单笔付款执行情况
	// 注意事项：
	//11.直联用户需在司库系统配置付方单位的查询权限；
	//2.返回的支付任务状态若为处理中，不代表该笔交易失败，请勿重复提交，防止重复动账。
	SinglePayQuery(singlePayReq tysk_entity.SinglePayQueryReq) (res tysk_entity.SinglePayQueryResp, err error)

	//BatchPay 批量付款
	//该接口用于发起多笔付款申请，调用该接口推送多笔付款请求，司库系统接收该请求后生成多笔付款的申请任务，并返回受理状态。受理成功后，客户需依据司库系统配置的审批流程参数及工作流，完成司库系统的审批流转。待审批通过后，系统自动执行付款交易指令，用户可通过批量查证交易进行交易状态的查询。
	// 注意事项：
	//1.本交易为一借多贷模式，1个付方账号，多个收方账号；
	//2.付方账号需提前在司库系统内维护为直联账户并为直联用户赋予批量付款支付权限及付方单位的机构权限；
	//3.接口调用后立即返回司库受理状态，此状态只表示交易请求是否受理，若校验通过该笔付款将进入【司库系统】-【结算中心】-【批量付款】功能，支付是否成功需稍后使用多笔查证交易进行查询。
	//4.在司库中按照如下业务模式参数进行处理：
	//1）审批处理，ERP传输的单据，直接到流程中心-待审批任务；
	//2)直接出账，只走司库接口，单据可在批量付款查询功能查询；
	//3）经办处理时，需要在司库公共中心进行流程配置，批量付款经办页面进行后续操作。
	//5.若该账户支持联动支付，资金会先从核心账户转入该支付账户中进行支付，资金下拨结果可在【批量付款查证】接口中进行查看；
	//6.接口请求参数中提供明细校验模式，“明细校验处理模式”。处理模式包含两种，整批验证模式、明细验证模式，为空时默认为单条明细异常整批失败。
	//整批验证模式 01：即现有处理模式，当批次内存在一条明细验证不通过时，整批状态失败，不入库，接口返回批次失败及错误信息。
	//明细验证模式02：新模式，当批次内存在一条明细验证不通过时，跳过该异常明细继续执行后续明细验证，验证通过的明细进行入库，根据外部请求批次号、外部请求流水号进行保存，同时接口返回部分成功及部分失败明细的条目信息，当采用明细验证模式下，单条明细校验不通过时交易状态返回“BBBBBBB”交易状态信息返回“交易部分成功！”。
	//7.是否跨行，非必输字段，若用户上送，则以用户上送为准，若用户不上送，司库仍按照收付方银行判断是否跨行；
	BatchPay(batchPayReq tysk_entity.BatchPayReq) (res tysk_entity.BatchPayResp, err error)

	//BatchPayQuery 多笔付款查证
	//调用该接口查询批量付款执行情况。
	// 注意事项：
	//1.1.直联用户需在司库系统配置付方单位的查询权限；
	//2.返回的批次支付任务状态若为处理中，不代表整批次交易失败，请勿重复提交，防止重复动账；
	//3.返回的批次支付任务状态若为部分成功，代表该批次中存在交易失败的支付明细。
	BatchPayQuery(batchPayQueryReq tysk_entity.BatchPayQueryReq) (res tysk_entity.BatchPayQueryResp, err error)

	//PayArrange 排款
	//企业ERP等系统调用该接口推送排款请求，司库系统接收该请求后在【司库系统】-【结算中心】-【排款管理】功能生成排款任务，并返回受理状态。
	// 注意事项：
	//1.接口调用后返回司库受理状态，此状态只表示排款请求是否受理；后续的排款及支付情况需使用排款查证交易进行查询；
	//2.付方账号需提前在司库系统内维护为直联账户并按需为直联用户赋予单笔付款或批量付款的支付权限及付方单位的机构权限；
	//3.收方明细信息数量最大支持1000笔；
	//4.若推送的明细单据数量为单条时，系统默认生成单笔付款类型的排款任务；当推送的明细单据数量为多条时，系统默认生成批量付款类型的排款任务。
	//5.若联动支付为是时，系统对应生成单笔或批量类型的联动支付排款任务。若未通过校验，则接口报错并提示“该账户无法支持联动支付”。
	//6.预算占用校验规则：若该排款请求根据配置需占用预算，则对预算占用事项进行校验，若未通过校验则返回错误及提示“无预算占用记录”，进行校验时，预算占用事项流水号（预算占用接口中“交易流水号”）需与本接口“外部排款流水号”保持一致。
	PayArrange(payArrangeReq tysk_entity.PayArrangeReq) (success bool, err error)
}