欢迎使用KUMQUAT API, KUMQUAT覆盖了全球220多个国家和550个运营商的全球运营商。
KUMQUAT API 是一个RESTful API,根据JSON API规范格式化请求和响应，并且提供以下服务:

• 基础信息服务
• 交易服务
• 查询服务
• 账户服务
• 通知服务

api的端口以相应的端口号为前缀， api/code/1.0, api/code/2.0。 实现是为了后续的版本不会影响前面的版本。

• 正式环境调用前请在平台上配置公网的ip地址。
• 所有接口格式基于 HTTP 协议方式进行调用，以 Web 服务的方式进行相互之间的通信， 要求 HTTP 的版本为 1.1 以上，所有接口支持GET / POST 方法
• 所有接口都需要有签名摘要参数sign，进行参数校验。详细请见认证。
• 所有接口使用的字符集为：UTF-8。
• 有关时间参数以北京时间（UTC+8）为准。
• 网络异常订单，请登录自助平台确认订单状态，请勿直接以失败处理。
• 充值逻辑中会有少量订单会先成功后失败，请注意对回调进行合理校验和判断。
• ISO 3166-1 标准

该API的主要功能是提供给客户进行充值(例如:话费、流量等)， 在充值过程中， 交易将进行各种各样的状态更改和转换。如下所示:

当事务发生变化的时候， 我们将会通过提供的回调URL将实时发送更新。

我们提供查询接口， 并且可以通过下列两种方式进行查找订单状态: request_no(请求编号) 和 serial_no(系统客户订单唯一标识)。 request_no充当唯一参考， 如果在请求过程中未收到返回信息，可以通过request_no查询是否在系统中存在此订单。

回调地址在后台可以进行配置，并且在下单接口也可以传输回调地址，优先级为接口地址最高，如果下单接口没有传输该参数，那么会以后台配置的回调地址为准，如果都不存在，那么不会进行回调处理。

订单完成时会提供回调通知， 如果当前网络不通畅， 则最多通知5次， 每次阶乘式延迟，如果5次均未成功， 后续不会进行通知。在极少数情况下会发生手动再次回调情况发生， 先成功，后失败的回调情况。并且回调的状态码为 200。

回调url必须是可以访问的公共地址。在测试过程中， 可以使用 ngrok等内网穿透工具进行测试接收回调。

HTTP状态码

KUMQUAT使用标准的HTTP响应代码来指示API请求是否成功。

API错误代码

订单状态

签名算法

签名生成的通用步骤如下： 第一步，设所有发送或者接收到的数据为集合M，将集合M内所有非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

第二步，在stringA最后拼接上sign_key得到stringSignTemp字符串，并对stringSignTemp进行MD5(32位小写)运算，得到secretkey值signValue。

特别注意以下重要规则：

• 参数名ASCII码从小到大排序（字典序）
• 如果参数的值为空不参与签名
• 参数名区分大小写
• 传送的sign参数不参与签名

秘钥(sign_key)由金橘科技提供。

    传输的参数:
      "partner_no": "test",
      "request_no": "123412434",
      "product_id": 19402,
      "account": "8615180624622",
      "amount": 20,
      "datetime": 20201230134400,
      "spbill_create_ip": "111.111.111.111",
      "callback_url": "https://www.kumquat.com/callback"

    第一步进行拼接字符串:
    A = account=8615180624622&amount=20&callback_url=http://www.kumquat.com/callback&datetime=20201230134400&partner_no=test&product_id=19402&request_no=123412434&spbill_create_ip=111.111.111.111
    sign = MD5(A + sign_key)

    假设密钥为: asfsdfdsfgsrgrssdfseesaef
    sign: a875dead05388c6acdc9a807abd78561

在支持翻页的接口中添加翻页的信息， 会根据信息进行返回数据, 返回的数据在header中进行返回。

输入参数

输出信息

请求mock数据的时候, 所填写的数据格式必须要要遵循api规范，callback_url的数据可以填写真实能够访问的接口地址。 会正常的对结果进行回调, 回调的校验签名sign_key=123456789