接入指南

一、引言

以下内容包含通过易鲸平台实现收款接口说明。

1.1 编写目的

本文档主要目的是帮助合作伙伴技术开发人员熟练掌握易鲸收款接口使用，并接入到现有的系统中。

1.2 使用对象

本文档的使用对象为合作伙伴的产品经理、系统设计人员、技术开发人员及测试人员。

1.3 版权说明

此文档版权归厦门易鲸信息科技有限公司（以下简称"whalet"）所有。作为本系统的最终用户（以下简称"合作方/合作伙伴"），可以拥有该文档的使用权，但未征得whalet的书面批准，不得向第三方借阅、出让、出版该文档。

1.4 技术支持

有关本接口对接、调试任何问题，可以在工作时间按以下方式联络相关技术支持人员。
product@whalet.com

二、公共报文

2.1 接入方式

使用HTTPS通信协议，使用POST方式提交。

环境	地址
测试环境	https://test-open.whalet.com/api
生产环境	https://open.whalet.com/api

2.2 数据格式

使用JSON作为请求和响应报文的通用格式，统一采用UTF-8编码格式。
报文必填标识：M(必填选项) O(可选选项) C(条件必选，特定条件必填);

请求报文

请求报文由两部分组成：请求报文头和请求报文体。其中请求报文头信息在报文头(head) 节点内，请求报文体信息在报文体(body)节点内。

请求报文头格式适用于所有接口。请求报文头信息的填写标准请参看公共请求报文头章节。

请求报文体根据每个接口定义而各不相同。请求报文体的定义请参看具体接口请求定义。需按照具体接口定义组装和解析请求报文体。

响应报文

响应报文由两部分组成：响应报文头和响应报文体。其中响应报文头信息在报文头(head)节点内，响应报文体信息在报文体(body)节点内。

响应报文头格式适用于所有接口。响应报文头信息的填写标准请参看公共响应报文头章节。

响应报文体根据每个接口定义而各不相同。应答报文体的定义请参看具体接口响应定义。需按照每个接口定义组装和解析应答报文体。

响应成功时，报文头的code为"SUCCESS"，detail为"成功", 此时报文体(body)节点根据实际业务需要为空也可以不为空。

响应失败时，错误码和错误信息填写在报文头的code(返回码)和detail(返回描述)域中，报文体(body)节点为空。

2.3 加密及签名方式

为保证数据的安全性，交易报文传输都需要进行加密、签名和校验。

报文加密算法：AES/ECB/PKCS5Padding

会话密钥生成：KeyGenerator生成

会话密钥加密算法：RSA/ECB/PKCS1Padding

签名算法：SHA1withRSA

RSA密钥对获得

对于合作方来说，需要生成自己的RSA密钥对（包含公钥和私钥），其中，私钥合作方自己保留，同时将公钥2048位（Base64 编码）提供给whalet。
对于whalet来说，需要为每个合作方生成对应的密钥对 2048位（Base64 编码）。其中，私钥whalet平台保留，公钥2048位（Base64 编码）需要提供给合作方。

报文加密及签名

使用KeyGenerator生成器，生成AES加密会话密钥SK。

使用SK对json明文进行加密(AES/ECB/PKCS5Padding)，并将加密结果转换为HEX字符串，得到encrypt域。

对SK进行Base64编码，并将结果转换为HEX字符串，使用接收方公钥对其加密（RSA/ECB/PKCS1Padding)，并将结果转换为HEX字符串，得到keyEnc域。对请求待签字符串(UTF-8编码)使用发送方的私钥进行签名(SHA1withRSA)，并将签名结果转换为HEX字符串，得到sign域。

报文解密及验签

将keyEnc域转换为二进制byte数组，使用接收方的私钥对其进行解密，然后进行Base64解码并转换为二进制byte数组，得到明文SK；

将encrypt也转换为二进制byte数组，使用上一步得到的会话密钥SK解密，得到明文json；

使用获取到的待签字符串、发送方公钥和sign域数据验证签名的有效性。

请求待签字符串

所有字段按如下顺序依次使用|符号连接。

partnerId，apiCode，version，requestNo来自请求头中对应字段。
encrypt来自实际请求体中encrypt字段。

响应待签字符串

所有字段按如下顺序依次使用|符号连接。

partnerId，apiCode，version，requestNo，code和detail来自响应头中对应字段。
encrypt来自实际响应体中encrypt字段，报文体(body)节点为空时，encrypt为空，不参加待签字符串连接。

2.4 公共请求报文头

字段名	类型	长度	必填	描述
partnerId	String	30	M	合作方id,whalet提供
apiCode	String	30	M	接口名称
requestNo	String	30	M	请求流水号, 唯一
version	String	3	M	接口版本，固定为：1.0
sign	String		M	请求报文签名
keyEnc	String		M	会话密钥密文

2.5 公共响应报文头

字段名	类型	长度	必填	描述
partnerId	String	30	M	请求头原样返回合作方id,whalet提供
apiCode	String	30	M	请求头原样返回接口名称
requestNo	String	30	M	请求头原样返回请求流水号, 唯一
version	String	3	M	请求头原样返回版本，固定为：1.0
code	String	32	M	返回码SUCCESS 表示请求成功
detail	String	256	M	描述
sign	String		O	响应报文签名
keyEnc	String		O	会话密钥密文

2.6 错误响应码

代码	描述	备注
SUCCESS	请求成功
PROCESSING	处理中	等待通知，以通知为准
FAILURE	失败	具体失败内容见detail属性
TOO_MANY_REQUESTS	请求频率过高
PARTNER_NOT_EXIST	合作方不存在
INTERNAL_ERROR	内部错误
PARAM_FORMAT_ERROR	参数格式错误
PARAMETER_ERROR	参数错误
IDEMPOTENT_ERROR	幂等错误
REQUEST_NO_NOT_UNIQUE	请求号重复
UNAUTHORIZED	未授权
UNAUTHENTICATED_ERROR	认证(签名)错误
INTERFACE_UNAUTHORIZED	接口未授权

2.7 异步通知

针对部分无法同步返回结果（同步结果状态为PROCESSING）的接口，whalet会在业务处理完成后通过异步通知的方式，根据不同业务场景，将不同通知类型（通过ApiCode区分）的消息post到合作伙伴提供的通知URL上，合作伙伴收到通知后在完成相应的消息解密验签后，可自行处理自己的业务。
合作方需要在指定时间内返回结果（需满足公共响应格式以及要求），如果出现请求超时，whalet会按照如下规则重试：

最多重试5次

间隔时间依次为1s、2s、4s、8s、16s

如果5次仍然无法成功，whalet将线下通知合作伙伴

建议合作方收到请求后异步处理内部业务逻辑，及时返回响应结果。同时保证自身服务的稳定性。

2.8 报文示例

以连通性Demo为例。

请求定义

ConnectivityGuideRequestBody

notifyFlag

enum<string>

是否通知

required

Allowed values:

notifyMessage

string

通知内容

optional

responseFlag

enum<string>

是否响应

required

Allowed values:

responseMessage

string

响应内容

optional

请求示例

响应定义

ConnectivityGuideResponseBody

messge

string

消息内容

optional

响应示例

三、文件上传

3.1 接入方式

使用HTTPS通信协议，使用POST方式提交。

环境	地址
测试环境	https://test-open.whalet.com/file/upload
生产环境	https://open.whalet.com/file/upload

3.2 数据格式

请求格式使用multipart/form-data，响应格式使用JSON。

3.3 token生成

待签字符串

将字段按如下顺序使用|符号连接。

partnerId为合作方ID，timestamp为当前时间戳（毫秒，13位数字）。

签名

对待签字符串(UTF-8编码)使用发送方的私钥进行签名(SHA1withRSA)，并将签名结果转换为HEX字符串即为token。

有效期

whalet会对token进行验签，并根据timestamp校验token的有效期，token的有效期为30分钟，在有效期内可以重复使用。

3.4 请求示例

shell命令请求

postman请求

3.5 响应示例

正确响应

{
    "code": "SUCCESS",
    "detail": "成功",
    "info": {
        "fileId": "202405011245158834940001",
        "fileName": "demo.jpg",
        "fileUrl": "https://test-file.whalet.com/2024-05-01/75ab32a9-cc98-46cb-9e8f-5c055fd9e4b5.jpg"
    }
}

异常响应

{
    "code": "UNAUTHENTICATED_ERROR",
    "detail": "invalid token",
    "info": null
}

注意事项

支持的文件类型包括：jpeg, jpg, png, gif, bmp, pdf, doc, docx, xls, xlsx, csv, txt, zip, rar

单个文件大小限制为：10M

一、引言#

1.1 编写目的#

1.2 使用对象#

1.3 版权说明#

1.4 技术支持#

二、公共报文#

2.1 接入方式#

2.2 数据格式#

请求报文#

响应报文#

2.3 加密及签名方式#

RSA密钥对获得#

报文加密及签名#

报文解密及验签#

请求待签字符串#

响应待签字符串#

2.4 公共请求报文头#

2.5 公共响应报文头#

2.6 错误响应码#

2.7 异步通知#

2.8 报文示例#

请求定义#

请求示例#

响应定义#

响应示例#

三、文件上传#

3.1 接入方式#

3.2 数据格式#

3.3 token生成#

待签字符串#

签名#

有效期#

3.4 请求示例#

shell命令请求#

postman请求#

3.5 响应示例#

正确响应#

异常响应#

注意事项#

一、引言

1.1 编写目的

1.2 使用对象

1.3 版权说明

1.4 技术支持

二、公共报文

2.1 接入方式

2.2 数据格式

请求报文

响应报文

2.3 加密及签名方式

RSA密钥对获得

报文加密及签名

报文解密及验签

请求待签字符串

响应待签字符串

2.4 公共请求报文头

2.5 公共响应报文头

2.6 错误响应码

2.7 异步通知

2.8 报文示例

请求定义

请求示例

响应定义

响应示例

三、文件上传

3.1 接入方式

3.2 数据格式

3.3 token生成

待签字符串

签名

有效期

3.4 请求示例

shell命令请求

postman请求

3.5 响应示例

正确响应

异常响应

注意事项