快速指南

配置

申请流程

  • 申请client_id 和client_secret
  • 在uat环境上开发测试
  • 部署到正式环境


指南

生成密钥

  • 合作商通过client_id和client_secret获取token

时间戳

  • 调用接口的时间，五分钟以内认为正确
  • 时间格式 YYYY-mm-dd hh:mm:ss, 例如 2018-01-01 01:01:01

签名

  • 提供client_secret
  • 将请求的内容结构（需要剔除时间戳）转化为标准的json字符串（依照key的字母表排序）
  • sign 为 json_str + client_secret 的32位md5值
  • Python3 示例
>>> import json
>>> import hashlib
>>> client_secret='test'
>>> data={'oid':'test001'}
>>> raw_str=json.dumps(data, separators=(',', ':'),sort_keys=True) + client_secret
>>> m2=hashlib.md5()
>>> m2.update(raw_str.encode())
>>> sign=m2.hexdigest()
>>> print(raw_str,sign)
{"oid":"test001"}test a2d5db80ec2a5d3a1a6783273e040e77

认证

  • 每次请求需要将token放入到header（需要加Bearer前缀，和token用空格分开）
  • : {‘Authorization’: ‘Bearer 14d3de567caaee6f7538f0c297d41cf466a2aa9f’}

权限

  • 每个token都绑定了某些scope，这些scope决定了这个token的权限
  • Scope在每次申请token时传入

流量限制

  • 每个合作商每分钟访问不得超过70次
  • 个别API可能会有特殊设置
  • 超出限制，会返回如下结果
{
    "detail": "Request was throttled. Expected available in 14 seconds.",
    "success": false,
    "result_code": "throttled",
    "result_message": "Request was throttled. Expected available in 14 seconds."
}

回调接口

  • 部分信息（例如现金支付结果、退款接口）通过异步回调通知合作商
  • 默认回调地址是预配置的notify_url参数
  • 回调接口需要支持POST请求，并且无任何权限认证
  • 合作商需要校验签名参数是否正确
  • 请求参数必有method这个参数，说明通知类型
  • 请求数据格式为application/json
  • 成功返回
{
   "success": true
}
  • 如果没有收到合作商的成功返回，那么会以以下策略重新发送请求: 1min, 5min, 30min, 1h,12h

版本控制

  • 考虑到API版本未来可能会升级，目前加入版本控制特性
  • 请求中需要加入header
    • Accept: application/vnd.aon.youxuan+json; version=1.0
  • 返回结果header
    • Content-Type: application/vnd.aon.youxuan+json
  • 默认版本为1.0

缓存

  • 某些请求是可以缓存结果
  • 缓存的有效期为5分钟
  • 在请求参数中加上use_cache=false 可以避免缓存

返回值的通用格式

success:布尔类型，请求是否成功的标志
result_code:字符类型，返回结果状态号
result_message:字符类型，返回结果描述
result:json，返回结果数据

其他

  • 请求参数中的数值类型需要保留小数点后两位
  • Encoding: utf-8