API调用方法详解

API是基于HTTP协议来调用的,你可以根据API定义的参数来封装HTTP请求,进行调用。

调用流程

填充参数-生成签名-拼装HTTP请求-发起HTTP请求-得到HTTP响应-解释响应结果

调用入口

平台提供了两个环境

调用环境 调用url 说明
开发环境 http://developer.asbamboo.com/api 通过开发环境请求,不会产生费用,但第三方渠道参数时自由设置的。你的应用请求开发环境时,第三方渠道参数也应该设置为开发环境的参数。
正式环境 http://api.asbamboo.com 正式环境的有效请求都会产生费用,但第三方渠道参数时自由设置的。你的应用请求正式环境时,第三方渠道参数也应该设置为正式环境的参数。

如何拼装参数?

一般情况下,一个API的参数由公共参数和业务参数两个部分组成。参数名和参数值必须使用utf-8编码。

公共参数
字段 类型 取值范围 必须 默认值 说明
api_name string api列表中支持的名称 必须 trade.cancel api名称
version string api列表中支持的版本 api版本。如果没传,表示使用最新的版本
format string json json 表示需要接口返回什么格式的数据,仅支持json
app_key string 每个应用唯一 必须 app key 一个请求api接口的应用程序的唯一标识符号
sign string 请查看签名规则 必须 签名字符串
timestamp string 10分钟内有效时间戳 必须 时间戳 格式为:yyyy-mm-dd HH:mm:ss,如(2018-09-27 20:01:53)
业务参数

一般情况下,每个API都会有相应的业务参数,请参考API说明

 

如何生成签名?

为了防止API调用过程中被黑客恶意篡改,调用任何一个API都需要携带签名,平台服务端会根据请求参数,对签名进行验证,签名不合法的请求将会被拒绝。签名过程如下:

  1. 对所有API请求参数(包括公共参数和业务参数,但除去sign参数、byte[]类型的参数),根据参数名称的ASCII码表的升序排列。如:foo:1, bar:2, foo_bar:3, foobar:4排序后的顺序是bar:2, foo:1, foo_bar:3, foobar:4。
  2. 将排序好的参数名和参数值拼装在一起,根据上面的示例得到的结果为:bar2foo1foo_bar3foobar4。
  3. 把拼装好的字符串前加上应用的app secret后,使用签名MD5算法生成签名字符串,如:md5(app_secret+bar2foo1foo_bar3foobar4)。
JAVA签名示例代码

public static String makeSign(Map params, String secret, String signMethod) throws IOException {
	// 第一步:检查参数是否已经排序
	String[] keys = params.keySet().toArray(new String[0]);
	Arrays.sort(keys);

	// 第二步:把所有参数名和参数值串在一起
	StringBuilder query = new StringBuilder();
	query.append(secret);
	for (String key : keys) {
		String value = params.get(key);
		query.append(key).append(value);
	}

	// 第三步:使用MD5加密
	byte[] bytes;
	bytes = encryptMD5(query.toString().getBytes(Constants.CHARSET_UTF8));

	// 第四步:把二进制转化为大写的十六进制(正确签名应该为32大写字符串,此方法需要时使用)
	//return byte2hex(bytes);
}

public static String byte2hex(byte[] bytes) {
	StringBuilder sign = new StringBuilder();
	for (int i = 0; i < bytes.length; i++) {
		String hex = Integer.toHexString(bytes[i] & 0xFF);
		if (hex.length() == 1) {
			sign.append("0");
		}
		sign.append(hex.toUpperCase());
	}
	return sign.toString();
}

拼装HTTP请求

将所有参数名和参数值采用utf-8进行URL编码(参数顺序可随意,但必须要包括签名参数),然后通过POST(含byte[]类型参数)发起请求,如:


 curl http://api.asbamboo.com/ \
 -d api_name=trade.pay \
 -d version=v1.0 \
 -d format=json \
 -d app_key=xxxxxxxx \
 -d sign=6E11F1080AFEE832FC9AD7A37FB52308 \
 -d timestamp=2019-01-03%2008:36:54 \
 -d channel=ALIPAY_PC \
 -d title=%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95 \
 -d out_trade_no=20190103083654943 \
 -d total_fee=100 \
 -d client_ip=123.123.123.123 \
 -d notify_url=http://xxxxxxxxxxxxxxxxx/notify/trade/pay \
 -d return_url=http://xxxxxxxxxxxxxxxxx/return/trade/pay \
 -d third_part=%7B%22limit_pay%22:%22no_credit%22%7D

解析响应结果

平台服务端接收并处理一个API请求后,以json作为响应值。具体响应的结果请参考各API说明。 如(为了便于阅读,我将响应值的json做了折行处理):

	
{
    "code":"SUCCESS",
    "message":"success",
    "data":{
        "channel":"ALIPAY_PC",
        "in_trade_no":"19003345171273776",
        "title":"支付测试",
        "out_trade_no":"20190104071738665",
        "total_fee":100,
        "client_ip":"123.123.123.123",
        "trade_status":"PAYOK",
        "payok_ymdhis":"2019-01-04 07:21:22",
        "payed_ymdhis":"",
        "cancel_ymdhis":""
    },
    "random": "5c2f132f2c65c",
    "sign":"E10ADC3949BA59ABBE56E057F20F883E"
}

为了确定这个响应值是平台与你之间的正常通信,避免黑客恶意混谣,你需要验证签名有效性签名

响应结果签名验证方法
  1. 首先你需要将响应值解析成数组。并且排除数组的key是sign那个单元。
  2. 将解析得到的数组进行排序,首先data部分根据key的ASCII码表的升序排列,然后整个数组根据key的ASCII码表的升序排列。
  3. 与请求接口相同的方式进行待签名字符串拼装,区别是这里的data也是一个array,data内容也需要按照这种方式拼接。
  4. 待签名字符串拼接示例:
    如Api接口Http响应结果:
    
    {"code":"SUCCESS","message":"success","data":{"channel":"ALIPAY_QRCD","in_trade_no":"19020293659903995","title":"test","out_trade_no":"20190221140217966","total_fee":"100","client_ip":"127.0.0.1","trade_status":"NOPAY","payok_ymdhis":"","payed_ymdhis":"","cancel_ymdhis":"","qr_code":"https://qr.alipay.com/bax04866u4awkyvv2iud001e"},"random":"5c45606a9176b","sign":"D8584CDCCF86E5C6D11D04BC72C6A434"}
    
    

    它的待签名字符串是
    
    codeSUCCESSdatacancel_ymdhischannelALIPAY_QRCDclient_ip127.0.0.1in_trade_no19020293659903995out_trade_no20190221140217966payed_ymdhispayok_ymdhisqr_codehttps://qr.alipay.com/bax04866u4awkyvv2iud001etitletesttotal_fee100trade_statusNOPAYmessagesuccessrandom5c45606a9176b
    
    
  5. 然后在这个字符串之后加上你的app_secret后,使用签名MD5算法生成签名字符串。
    
    md5(code0datacancel_ymdhischannelALIPAY_QRCDclient_ip127.0.0.1in_trade_no19020293659903995out_trade_no20190221140217966payed_ymdhispayok_ymdhisqr_codehttps://qr.alipay.com/bax04866u4awkyvv2iud001etitletesttotal_fee100trade_statusNOPAYmessagesuccessrandom5c45606a9176b + app_secret)
    
    
  6. 判断上一步得到的签名字符串是否与响应值中的sign单元相等

如果你有什么疑问,请asbamboo.com

群二维码