接口文档模板

某项目某接口

简要描述

• 某项目某接口说明

接口版本

接口列表

连接地址

• 通过http/https协议发送json格式报文
• 内网测试地址 http://172.16.129.207:12345
• 公网测试地址 http://test.cardsv.com:12345
• 公网生产地址 https://hpay.cardsv.com.cn:12346

请求方式

• 通过http/https协议通过post提交json格式报文，Content-Type: application/json

数据格式

• 指令格式
  JSON格式字符串
• 字符编码
  统一采用UTF-8字符编码

安全规范

数字签名

• 为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。数字签名有两个步骤，先按一定规则拼接要签名的原始串，再选择具体的算法和密钥计算出签名结果。一般失败的结果不签名。

签名原始串
无论是请求还是应答，签名原始串按以下方式组装成字符串：

1. 除sign字段外，所有参数按照字段名的ascii码从小到大排序后使用QueryString的格式（即key1=value1&key2=value2…）拼接而成，空值不传递，不参与签名组串。
2. 签名原始串中，字段名和字段值都采用原始值，不进行URL Encode。
3. 平台返回的应答或通知消息可能会由于升级增加参数，请验证应答签名时注意允许这种情况。

签名算法
目前暂只支持MD5签名

• MD5签名
  MD5 是一种摘要生成算法，通过在签名原始串后加上商户通信密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。为了方便比较，签名结果统一转换为大写字符。
  注意：签名时将字符串转化成字节流时指定的编码字符集应与参数charset一致。
  MD5签名计算公式：
  sign=Md5(原字符串&key=密钥).toUpperCase

php实例

/**
 * 加签实例 function
 * @param array $data 待加签报文
 * @param string $key 密钥
 * @return string $sign 签名
 */
function getsign($data, $key)
{
    ksort($data);
    $tmpstr = '';
    foreach ($data as $k => $v) {
        if (' ' != $v && 'sign' != $k) {
            $tmpstr = $tmpstr . $k . '=' . $v . '&';
        }
    }
    $tmpstr = $tmpstr . 'key=' . $key;
    $sign = strtoupper(md5($tmpstr));
    return $sign;
}

报文主体

报文内容

自检

请求报文:

返回报文:

备注：可验证签名密钥或签名算法是否正确。

请求示例

{
    "apptype": "0200",
    "process": "000000",
    "instcode": "00000001",
    "instorder": "210825061616471018225",
    "timestamp": "20210819141810",
    "noncestr": "620deaf3bb5e5c60",
    "signtype": "md5",
    "sign": "3711214FA8428C30EB7FA53B27CD59BF",
}

返回示例

正确时返回:

{
    "apptype": "0210",
    "process": "000000",
    "instcode": "00000001",
    "instorder": "210825061616471018225",
    "timestamp": "20210819141812",
    "noncestr": "7f86256dc53e7c33",
    "retcode": "00",
    "retmsg": "success",
    "signtype": "md5",
    "sign": "B54AD41EE9BC6975AF03454ED9E12A86",
}

错误时返回:

{
    "apptype": "0210",
    "process": "000000",
    "instcode": "00000001",
    "instorder": "210825061616471018225",
    "timestamp": "20210819141811",
    "noncestr": "00ce0937df2478b1",
    "retcode": "xx",
    "retmsg": "fail"
}

备注：更多返回错误代码请看错误代码描述。

备注

• 无

业务流程