接入指南

API调用协议

API调用方法详解

API是基于HTTP协议来调用的，开发者（ISV）可以直接使用TOP提供的官方SDK（支持多种语言，包含了请求的封装，签名加密，响应解释，性能优化等）来调用，也可以根据协议来封装HTTP请求进行调用， 以下主要是针对自行封装HTTP请求进行API调用的原理进行详细解说。

调用入口

调用API的服务URL地址，开放平台目前提供了2个正式环境给ISV使用。

调用环境	服务地址	适用范围
域名1	https://reepu.cn/api	仅短网址
域名2	https://reepu.com/api	全部
域名3	https://api.reepu.com	全部

开发者需要对API的请求内容加密与签名，同时API的回包内容需要开发者验签与解密。

接口地址：https://reepu.cn/api + 接口路径 或 https://api.reepu.com + 接口路径

例如: https://reepu.cn/api/short/v1 或 https://api.reepu.com/short/v1

公共参数

调用任何一个API都必须传入的参数，目前支持的公共参数有：

Header

参数名称	参数类型	是否必填	描述	示例值	备注
APIKey	String	是	应用Key	10000000000000000000000000000000

Params

参数名称	参数类型	是否必填	描述	示例值	备注
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8	2016-01-01 12:00:00
sign	String	否	签名	9b2e4b061018eb2c0f9b9d3fb5b957a4
format	String	否	响应数据格式，目前只支持json	json

业务参数

API调用除了必须包含公共参数外，如果API本身有业务级的参数也必须传入，每个API的业务级参数请考API文档说明。

请求响应

参数名称	参数类型	是否必填	描述	示例值	备注
code	Integer	是	状态码	200	200成功，500内部错误
message	String	是	消息	success	success成功，fail失败
timestamp	String	是	时间戳	1712648816
data	Object	是	响应数据

签名算法

为了防止API调用过程中被黑客恶意篡改，调用任何一个API都需要携带签名，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。目前支持的签名算法有以下几种：

常见错误码

错误码	错误描述	错误原因
401	Unauthorized	签名验证失败
404	Not Found	无效的请求路由
405	Method Not Allowed	请求方法不允许
417	Expectation Failed	签名验证失败
500	Internal Server Error	服务器内部错误
503	Service Unavailable	服务不可用