tysk/tyskFacecade.go

268 lines
24 KiB
Go
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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 //结算中心
Common //公共中心
Bill //票据中心
}
// 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)
//PayArrangeQuery 排款查证
//企业ERP等系统调用该接口查询排款任务的执行情况。
// 注意事项:
//1.直联用户需在司库系统配置付方单位的查询权限。
//2.使用排款申请接口返回的原外部排款批次号来进行查证,将返回该笔排款任务拆分出的各笔付款任务状态。
//2.1 排款-单笔付款情况下进行查证查证接口rows标签下不根据未支付金额返回付款金额与之相同的未排期明细数据。
//2.2 排款-批量付款情况下进行查证查证接口rows标签下不会返回未排期的付款数据。
//3.当结算方式为银承开票、商承开票、银承转让或商承转让时,返回相关的票据汇总信息。
//4.当结算方式为现金支票、转账支票、银行保函、信用证、其他时,子任务状态为“支付成功”时,返回线下付款日期。
PayArrangeQuery(PayArrangeQueryReq tysk_entity.PayArrangeQueryReq) (res tysk_entity.PayArrangeQueryResp, err error)
//PayArrangeBillQuery 排款票据信息查询
//用于查询排款结算方式为银承开票、商承开票、银承转让或商承转让时,司库系统接收该请求。
// 注意事项:
//1.直联用户需在司库系统配置付方单位的查询权限,[公共中心]-[用户权限管理]-[机构权限设置]进行维护。
//2.接口支持一次最大20条
//3.使用排款申请接口返回的原外部排款批次号、子任务编号来进行查证,将按子任务号或外部排款批次号得查询结果返回票据信息。
//4.当调用排款查证接口返回子任务的结算方式为银承开票、商承开票、银承转让或商承转让时使用。
PayArrangeBillQuery(PayArrangeBillQueryReq tysk_entity.PayArrangeBillQueryReq) (res tysk_entity.PayArrangeBillQueryResp, err error)
//BatchesPayArrangeBillQuery 3.2.8多批次排款票据查询
//用于查询排款结算方式为银承开票、商承开票、银承转让或商承转让时,司库系统接收该请求。
// 注意事项:
//1.直联用户需在司库系统配置付方单位的查询权限,[公共中心]-[用户权限管理]-[机构权限设置]进行维护。
//2.接口支持一次最大100条
//3.使用排款申请接口返回的原外部排款批次号、子任务编号来进行查证,将按子任务号或外部排款批次号得查询结果返回票据信息。
//4.当调用排款查证接口返回子任务的结算方式为银承开票、商承开票、银承转让或商承转让时使用。
BatchesPayArrangeBillQuery(BatchesPayArrangeBillQueryReq tysk_entity.BatchesPayArrangeBillQueryReq) (res tysk_entity.BatchesPayArrangeBillQueryResp, err error)
//TGBPay 3.2.9团金宝付款
//用于发起团金宝交易,支持落地经办、提交审批、直接付款三种模式,用户可以根据设置信息选择业务处理模式。
// 注意事项:
//1.外部请求批次号不能重复,包括批量付款、团金宝交易
//2.操作人必须有ERP团金宝业务权限、付款账户操作权限
//3.收款信息最大支持1000笔
//4.仅支持人民币交易
//5.在司库中按照如下业务模式参数进行处理:
//1审批处理ERP传输的单据直接到流程中心-待审批任务;
//2) 直接出账,只走司库接口,单据可在团金宝/薪酬代发查询功能查询;
//3经办处理时团金宝经办页面进行后续操作
//6.若选择联动支付,增加权限校验,校验付方账号必须是资金池成员账号且开通联动下拨功能,若该账户支持联动支付,资金会先从核心账户转入该支付账户中进行支付,资金下拨结果可在【多笔付款查证】接口中进行查看;
TGBPay(TGBPayReq tysk_entity.TGBPayReq) (res tysk_entity.TGBPayResp, err error)
//RefundTransQuery 3.2.9团金宝付款
//用于查询状态已标识为“已退汇”的支付单据包括本地制单、ERP来源、排款来源以及各渠道来源的单笔付款、批量付款、薪酬支付、费用报销、付款计划、用款申请交易。
// 注意事项:
//1.接口支持一次最大20条日期最大范围为当日T-1前90天内的交易
//2.请求使用的银企直联用户必须有ERP退汇业务权限、付款账户查询权限
//3.退汇交易查询支持自动退汇和手工退汇交易查询,其中自动退汇交易查询银行范围包括:中信银行、招商银行、平安银行退汇情况的交易查询。
//4.付款类型是“团金宝”业务,仅支持单笔记账方式的退汇明细查询。
RefundTransQuery(RefundTransQueryReq tysk_entity.RefundTransQueryReq) (res tysk_entity.RefundTransQueryResp, err error)
//BatchSalarySend 3.2.11批量代发(薪酬代发)
//该接口用于发起薪酬代发申请,调用该接口推送请求,司库系统接收该请求后生成薪酬代发的申请任务,并返回受理状态。受理成功后,客户需依据司库系统配置的审批流程参数及工作流,完成司库系统的审批流转。待审批通过后,系统自动执行付款交易指令,用户可通过批量付款/团金宝查证交易进行交易状态的查询。
// 注意事项:
//1.本交易为一借多贷模式1个付方账号多个收方账号
//2.付方账号需提前在司库系统内维护为直联账户并为直联用户赋予薪酬代发支付权限及付方单位的机构权限;
//3.接口调用后立即返回司库受理状态,此状态只表示交易请求是否受理,若校验通过该笔付款将进入【司库系统】-【结算中心】-【薪酬代发】功能,支付是否成功需稍后使用多笔查证交易进行查询。
//4.在司库中按照如下业务模式参数进行处理:
//1审批处理ERP传输的单据直接到流程中心-待审批任务;
//2)直接出账,只走司库接口,单据可在薪酬代发查询功能查询;
//3经办处理时需要在司库公共中心进行流程配置薪酬代发经办页面进行后续操作。
//5.若该账户支持联动支付,资金会先从核心账户转入该支付账户中进行支付,资金下拨结果可在【批量付款查证】接口中进行查看;
BatchSalarySend(BatchSalarySendReq tysk_entity.BatchSalarySendReq) (res tysk_entity.BatchSalarySendResp, err error)
}
type Common interface {
//BankInfoQuery 3.3.1境内银行网点信息查询
//用于查询境内银行网点信息查询企业调用该接口查询网点请求司库系统接收该请求后返回境内银行网点信息支持分页查询参数为银行编号和区域编码ID详见附件银行编码和区域编码不能同时都为空。
// 注意事项:
//1.当前支持境内银行网点信息查询,含外资行境内网点;
//2.银行编码和区域码详见【附录5.9-银行编码信息和区域信息V1.0】,查询时这两个参数不能同时为空;
//3.支持分页查询;
BankInfoQuery(BankInfoQuery tysk_entity.BankInfoQueryReq) (res tysk_entity.BankInfoQueryResp, err error)
}
type Bill interface {
//BillList 3.4.1票据列表查询
//企业ERP等系统调用该接口发起票据信息查询支持持有票据、票据行为申请、票据行为签收三类场景司库系统接收该请求后返回对应的票据信息查询结果按照【账号】+【票据包号】+【子票区间】进行去重。
//持有票据:选择该条件进行查询可以列表展示指客户当前持有的票据
//票据行为申请:选择该条件(支持全选或复选)可以查询客户发起过对应申请行为的票据
//票据行为签收:选择该条件(支持全选或复选)可以查询客户发起过对应签收行为的票据
// 注意事项:
//1.请求使用的银企直联用户需有相关账号的查询权限
//2.该交易使用分页查询起始记录号从1开始每页最多显示200条记录。
BillList(BillListReq tysk_entity.BillListReq) (res tysk_entity.BillListResp, err error)
//BillDetail 3.4.2票据详情查询
// 注意事项:
//1.当输入账号进行查询时,系统需校验用户对票据所属的账号具有查询权限;
BillDetail(BillDetailReq tysk_entity.BillDetailReq) (res tysk_entity.BillDetailResp, err error)
}