概述
接口适用范围
此文档定义了LinkDaDa开放平台（以下简称LinkDaDa）和交易所的接口交互规范，包括LinkDaDa发起的请求接口和交易所发起的通知接口。
接口对接流程
接口规范
接口为RESTful风格，除文件上传下载等特殊情况外，请求（POST时）和响应内容均为json格式。为避免交易所侧可能的改造成本，本规范避免使用http status code、path参数和GET/POST外的其他方法。
接口字段无特殊说明的， 默认为UTF-8编码。为增加接口兼容性，接口请求及响应字段均采用小写驼峰形式，如"signUrl", "createAt"。
GET 请求的 query 参数, 如果是数组(类型后面加[]表示数组)或者对象类型, 则实际传输的参数是经过 json 编码的字符串
-
接口响应规范：
{ "status":200, //状态码，表示成功或者失败。其中2xx表示成功，4xx为请求异常，5xx为服务器内部异常 "error": "", //错误类型 "message":"OK", //状态码描述 "maxPageSize":100, //允许每页最大的条数, 该字段只在有分页功能的接口响应中存在 "total": 1, //查询结果总条数，该字段只在有分页功能的接口响应中存在 "data":"{\"id\":1}", //具体业务数据， json形式的字符串 "signUrl":"GET /trades-for-his/orders/123", //本次请对应的url, **不含QueryString** "signTime": 1490529625, //签名时刻的时间戳(Unix timestamp) "sign":"xxxxxxxxxx" //签名 }signUrl，signTime，sign为每个接口响应必须带的参数，后续接口响应示例省略不再重复说明
接口地址规范：
交易所提供的API地址为
https://api.xxx.com/bilian/users/orders/ 或
https://xxx.com/api/bilian/users/orders/
接口地址
LinkDaDa侧提供的接口地址, 用于交易订单创建、充提币通知等。
接口签名
双方接口都应使用签名作为安全通信机制。相关接口, 双方应使用RSA签名。
注意: 发起请求时, 应对QueryString和Content的所有内容进行签名; 接收响应时, 应对Content的所有内容进行签名。而不是仅对接口中定义的内容签名。
签名前, 先将待签名数据(请求或者响应的参数列表)进行预处理:
参数列表中加入signUrl和signTime参数, 如
{
"signTime":1490529625,//签名时刻的时间戳(Unix timestamp)
"signUrl":"GET /trades-for-his/orders/123", //本次请对应的方法和url, 不含QueryString
}将请求参数以参数名按字典序升序排列，并拼接在一起，如“k1=v1&k2=v2&k3=v3”
-
以上处理输出"待签名文本", 以下为php代码片段:
/** * 生成待签名文本 * @param array $data */ function genSignReq(array $data) { //1. 先将参数按参数名的字典序升序进行排序 $signReq = []; //待签名字符串 ksort($data); //2. 将数组拼成字符串。注意, 对于json中的null、bool类型, 需要转换成约定好的文本 foreach ($data as $k => $v) { if($v === null) { // null 转换成空字符串 $v = ''; }elseif ($v === true) { // true 转换文本'1' $v = '1'; }elseif ($v === false) { // true 转换成文本'0' $v = '0'; } //为key/value对生成一个key=value格式的字符串，并拼接到待签名字符串后面 $signReq[] = "$k=$v"; } return implode('&', $signReq); } 注意：计算签名时，应将sign（签名）参数排除。
注意：计算签名的时候不需要对参数进行URLencode处理（“application/x-www-form-URLencoded”编码）。
RSA签名
-
OpenSSL工具安装
- Linux用户（以Ubuntu为例）
sudo apt-get install openssl- Windows用户开发者可以在OpenSSL官方网站(https://www.openssl.org/related/binaries.html)下载Windows的OpenSSL安装包进行安装
-
RSA私钥及公钥生成
openssl #执行openssl, 进入openssl控制台 OpenSSL> genrsa -out rsa_private_key.pem 1024 #生成私钥 OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt #Java开发者需要将私钥转换成PKCS8格式 OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem #生成公钥- 注意：对于使用Java的开发者，将pkcs8在console中输出的私钥去除头尾、换行和空格，作为开发者私钥，对于.NET和PHP的开发者来说，无需进行pkcs8命令行操作。
-
私钥及公钥文件示例
经过以上步骤，开发者可以在当前目录下看到rsa_private_key.pem和rsa_public_key.pem两个文件，前者为私钥，后者为公钥。交易所侧保留私钥，将公钥提交给LinkDaDa，用于信息加密及解密。以下为使用OpenSSL生成的私钥文件和公钥文件示例。
-
标准的私钥文件示例（PHP、.NET使用）
-----BEGIN RSA PRIVATE KEY----- MIICXAIBAAKBgQChKpLOsRHQ5L046EEseZn+lTbgD5H9N9Z/SsxrJMkQv5GL/NWl jgPlaGSY4Eawi6k3b26RQUGHA9QZ7lSlNXPJByTjpghBti1wccv8xYQgbmVlKj5g /bfqjVIDPDCj8oNa4dGCnfyJ6oW0bfZXfbtK6xeFFvJTRNNn+8Sz0IK4cQIDAQAB AoGAasJ972dCawMrCYhoq+J9jTQg3rnRtlCHyViuIweCHZMZAgdhK0Lw98V4ZgCj Mw3A8VTihFwa4So7FVZYQfwvjtz3SfpYvB6YSB9gnFNB3RvOUwFLqbnCtEw7tWyP 7vhE1HfyTzmngFpbjFTaGjioXvQA6zN7wj3ptycbwfZxWLECQQDQZflrgkdi7y59 Ab0fd2LQmgBawQjwUeqLMTrqVi6dy7q+r4PVK86t0AYruCXTK8Tl7kxE/ez5W88k mw9fevx9AkEAxfq4nVmyFLXrD+3NcG86TSWIv4df1u695KfSiZISQzv7XmW/wlSX QWFtpocz1nQL5mpkivx/YcZ0il5WELcSBQJBAJoymfb+kquVpqRAYRujTq5jBNgh 9Oc89XrAloNF+YAweqEVZUqZ+3eIcMhwnSw/OpWXWT/DU1C+qerAAQP5EFECQF8H 5EoTXfm3AOgae7x2h4O0epmE/6oJ2zjAnbzPUtjXF+fN62f6dsg5XgrLZ0SPW470 juJwJSznt9UbRzCqz4kCQG+nbP/ZmrJXocC9yWupDQysFBE+p3+Fpstb2pNymGyR SblvImtWhRq+kPY48Uxbpy5u7G2KxwqGoxwkmXbmb6U= -----END RSA PRIVATE KEY----- PKCS8处理后的私钥文件示例（Java使用）
-
```
-----BEGIN PRIVATE KEY-----
MIICdgIBADANBgkqhkiG9w0BAQEFAASCAmAwggJcAgEAAoGBAKEqks6xEdDkvTjo
QSx5mf6VNuAPkf031n9KzGskyRC/kYv81aWOA+VoZJjgRrCLqTdvbpFBQYcD1Bnu
VKU1c8kHJOOmCEG2LXBxy/zFhCBuZWUqPmD9t+qNUgM8MKPyg1rh0YKd/InqhbRt
9ld9u0rrF4UW8lNE02f7xLPQgrhxAgMBAAECgYBqwn3vZ0JrAysJiGir4n2NNCDe
udG2UIfJWK4jB4IdkxkCB2ErQvD3xXhmAKMzDcDxVOKEXBrhKjsVVlhB/C+O3PdJ
+li8HphIH2CcU0HdG85TAUupucK0TDu1bI/u+ETUd/JPOaeAWluMVNoaOKhe9ADr
M3vCPem3JxvB9nFYsQJBANBl+WuCR2LvLn0BvR93YtCaAFrBCPBR6osxOupWLp3L
ur6vg9Urzq3QBiu4JdMrxOXuTET97PlbzySbD196/H0CQQDF+ridWbIUtesP7c1w
bzpNJYi/h1/W7r3kp9KJkhJDO/teZb/CVJdBYW2mhzPWdAvmamSK/H9hxnSKXlYQ
txIFAkEAmjKZ9v6Sq5WmpEBhG6NOrmME2CH05zz1esCWg0X5gDB6oRVlSpn7d4hw
yHCdLD86lZdZP8NTUL6p6sABA/kQUQJAXwfkShNd+bcA6Bp7vHaHg7R6mYT/qgnb
OMCdvM9S2NcX583rZ/p2yDleCstnRI9bjvSO4nAlLOe31RtHMKrPiQJAb6ds/9ma
slehwL3Ja6kNDKwUET6nf4Wmy1vak3KYbJFJuW8ia1aFGr6Q9jjxTFunLm7sbYrH
CoajHCSZduZvpQ==
-----END PRIVATE KEY-----
```
* 公钥文件示例
```
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQChKpLOsRHQ5L046EEseZn+lTbg
D5H9N9Z/SsxrJMkQv5GL/NWljgPlaGSY4Eawi6k3b26RQUGHA9QZ7lSlNXPJByTj
pghBti1wccv8xYQgbmVlKj5g/bfqjVIDPDCj8oNa4dGCnfyJ6oW0bfZXfbtK6xeF
FvJTRNNn+8Sz0IK4cQIDAQAB
-----END PUBLIC KEY-----
```
-
签名和校验
LinkDaDa和交易所发起的请求、返回的响应均需要签名，签名方式为：计算待签名文本的RSA签名。
-
将签名 base64编码,即为 sign的值（请求和响应中sign对应的值） 以下为php代码片段:
/** * 签名 * * @param array $data 需要签名的内容 * @param string $rsaPrivateKey rsa私钥 * @return string 生成的签名 */ function genSign(array $data, $rsaPrivateKey) { //1. 生成待签名文本 $signReq = genSignReq($data); //2. 对摘要进行签名 $signRes = null; $key = openssl_get_privatekey($rsaPrivateKey) or Verify::fail('openssl_get_privatekey failed', [openssl_error_string()]); openssl_sign($signReq, $signRes, $key) or Verify::fail('openssl_sign failed', [openssl_error_string()]); openssl_free_key($key); //3. base64编码 $sign = base64_encode($signRes); return $sign; } /** * @param array $data 待验签的文本 * @param $rsaPublicKey 公钥 * @return bool */ function verifySign(array $data, $rsaPublicKey) { if(!isset($data['sign'])){ return false; } $sign = base64_decode($data['sign']); unset($data['sign']); // 验签前需要把sign排除 //1. 生成待签名文本 $signReq = genSignReq($data); //2. 验签 $key = openssl_get_publickey($rsaPublicKey); $result = openssl_verify($signReq, $sign, $key); openssl_free_key($key); if($result == -1){ Verify::fail('openssl_verify failed', [openssl_error_string()]); } return $result==1; }
注意：LinkDaDa请求交易所的接口，如首次注册用户，LinkDaDa使用自己的私钥进行签名，交易所使用LinkDaDa的公钥进行验签，并将响应结果使用交易所私钥进行加签，LinkDaDa使用交易所公钥进行验签。同理，交易所通知LinkDaDa的接口，如订单成功接口，交易所使用自己的私钥进行加签，LinkDaDa收到通知后，使用交易所的公钥进行验签。
