Skip to main content

话单API对接

话单API对接

统一推单接口

推送话单​

接口说明​

请求URL：请在后台API信息中查看

请求方式：POST

body 指该参数需在请求JSON传参

请求参数​

参数名类型必填描述
body appKeystringyes后台API信息中的appKey
body poolKeystringyes话单池编码，详见话单池文档
body callbackUrlstringyes回调URL
body timestamplongyes毫秒级时间戳，有效期为一分钟
body signstringyes利用MD5签名，不可重复使用
body ordersarrayyes推送的订单数组，参见订单数据结构

订单数据结构​

参数名类型必填描述
body amountstringyes订单金额
body numberInfostringyes手机号码
body orderIdstringyes订单ID
body expireTimestringyes过期时间，格式为yyyy-MM-ddTHH:mm:ss，日期时间分隔符为T，非空格，最小要大于当前时间一分钟
body extsjsonno支付信息，在某些订单池会用到，格式为jsonObject
签名方法

MD5(timestamp+appSecret)，appSecret为后台API信息中的appSecret

参数示例​

{
    "appKey": "ThisIsYourAppKey",
    "poolKey": "DIANXIN_KC",
    "callbackUrl": "http://www.callback-url.com/callback",
    "timestamp": 1647344736869,
    "sign": "9f80010babbc8230dfcb06b78a173e95",
    "orders": [
        {
            "amount": "0.01",
            "numberInfo": "13800138000",
            "orderId": "123456789",
            "expireTime": "2018-01-01T00:00:00",
            "exts": {"ext1": "ext1"}
        },
        // ... 多个订单
    ]
}
注意

上述参数示例中，AppKey为 ThisIsYourAppKey ，AppSecret为 ThisIsYourAppSecret ，签名文本为 1647344736869ThisIsYourAppSecret

返回示例​

{
    "msg": "操作成功",
    "code": 0, // 状态码为0则为成功，其他皆为异常
    "data": [
      "订单[OR20282852]上传失败：订单金额不能为空",
      "订单[OR22795292]上传失败：订单金额错误",
    ], // 会返回上传失败的订单号 ，并附上错误信息，全部成功时为空数组
    "timestamp": 1647344736869 // 失败时会返回该字段，该字段为服务器当前时间戳
}

回调​

回调URL：下单时所传callbackUrl

回调方式：POST

退单回调时的RequestBody
{
    "type": "RETURN", // 订单类型：RETURN为退单，PAID为支付
    "orderId": "下单时传的orderId",
    "timestamp": "回调时的毫秒时间戳",
    "exts": "下单时传的exts",
    "sign": "MD5('RETURN' + orderId + timestamp + appSecret)"
}
充值完成回调时的RequestBody
{
    "type": "PAID", // 订单类型：RETURN为退单，PAID为支付
    "orderId": "下单时传的orderId",
    "timestamp": "回调时的毫秒时间戳",
    "platformOrderId": "2022041623212382923", // 充值平台的官方订单号
    "exts": "下单时传的exts",
    "sign": "MD5('PAID' + orderId + timestamp + appSecret)"
}
// 签名时PAID不需要带单引号，仅代表其是文本！

返回200-299HTTP状态码代表已经成功处理回调，否则服务器会再稍后的时间继续进行回调

最佳实践​

被回调时应当校验签名，且保证timestamp和当前时间相差不超过一分钟，如果无法完成校验请返回HttpStatusCode>=300的响应，系统会重新回调

池属性​

  • 重复：可以在同一天内推送重复手机号码的，但是前一单必须已经完成（已退单或者已充值）才可以继续推送。
  • 不重复：当天每个号码只接受一单，如果当天已经有一单，则不接受新单。

常见问题​

  • Q: 下单提示 签名不可重复使用

  • A: 请保证每次下单都进行了签名，且时间戳不能与之前相同

  • Q: 下单提示 签名过期

  • A: 请检查timestamp和返回的timestamp的时间差，不能超过一分钟