使用说明

本文档将帮助您快速了解和使用产品功能。目前版本为1.x版本，后续会根据需要对API版本进行持续更新迭代。

一、概述:

• TOOLSTIP会持续集成各种api接口，目前支持支撑海运查询的各类必要接口，以及webhook功能。
• 未来除了持续完善API版本迭代外，还会陆续支持国内和国际时效查询接口，以及其它主流API接口。

二、快速入手

• 使用常用邮箱注册，然后登陆账户。
• 生成自己的私有api key。

三、请求

• 请求允许以HTTP或HTTPS协议进行发送。
•  
• 1. 基础链接
• HTTPS： https://api.toolstip.cn
• HTTP： http://api.toolstip.cn
•  
• 2. 请求头
• 所有请求的头部都必须包含名为 Toolstip-Api-Key 的键，其对应值是你的 API Key。
• 表头中 Content-Type 对应值必须为 application/json，Content-Type 默认提供 UTF-8 格式的字符集参数，其他编码格式都不支持。
•  

• 	
  Content-Type: application/json 
  Toolstip-Api-Key: YOUR_API_KEY
  
  

•  
• 3. 公共请求参数
•  

• 字段	描述
  请求类型POST	必须，完整接口： 基础链接 + 版本号 + 路径，例如：https://api.toolstip.cn/v1/proxy
  route	必须，请求路由
  limit	可选，限制返回符合条件数量，默认20

TOOLSTIP 使用 API Key 对请求进行授权。

一、如何获取 API KEY？

• 登录您的 TOOLSTIP 账户，按如下顺序找到获取 API Key 的界面，设置 → 获取 API Key。
• 获取 API Key 之后，请妥善保管你的 API Key，不要将其分享到网站上，这可能导致 API Key 被他人使用而造成损失。

二、示例代码

curl -X POST -k "https://api.toolstip.cn/v1/proxy" \
	-H "Content-Type:application/json" \
	-H "Toolstip-Api-Key:YOUR_API_KEY" \
	-d "[\"route\":\"basis\",\"limit\":\"1\"}"

所有响应和请求都采用 JSON 字符串。

一、响应字段结构

• 字段	描述
  meta	必须，除了5开头的响应，内容结构都会包含此字段
  code	必须，int类型，meta的下一层结构字段，即API请求的响应状态码
  type	必须，string类型，响应状态码类型
  message	必须，string类型，meta的下一层结构字段，即API响应的描述内容
  data	必须，Array类型，存放API请求响应结构数据

二、示例代码

{
	"meta": {
		"code": 4001,
		"type": "Unauthorized",
		"message": "Invalid API key"
	},
	"data": []
}

TOOLSTIP 使用传统的HTTP状态码来表明 API 请求的状态。通常，2xx形式的状态码表示请求成功，4XX形式的状态码表请求发生错误（比如：必要参数缺失），5xx格式的状态码表示服务器可能发生了问题。

一、状态码列表

• 状态码	类型	描述
  200	Success	请求成功
  202	Success	暂无可用数据
  204	No Content	请求成功，但未获取到数据,可能是目标数据不存在
  400	Bad Request	请求类型错误，请查询API文档，确定该接口的调用方法
  4001	Bad Request	无效API key，请核对后再尝试
  4002	Bad Request	API key 已经被删除，或当前不可用
  401	Unauthorized	授权失败或没有权限，请检查并确保您的API Key正确无误
  4011	Unauthorized	请指定请求路由，或者当前请求路由缺失
  4012	Unauthorized	您暂无当前接口的路由权限
  403	Bad Request	该接口不存在，请检查并确保您的请求接口正确无误
  4031	Bad Request	当前请求数据为空
  404	Not Found	该接口不存在，请检查并确保您的请求接口正确无误
  408	Time Out	请求超时，官网没有返回数据，请稍后再试
  411	Bad Request	请求参数长度超过限制，请检查并确保请求参数长度符合要求
  412	Bad Request	请求参数格式不合要求，请检查并确保请求参数格式符合要求
  413	Out limited	请求参数数量超过限制，请查看API文档以获取该接口请求数量限制
  417	Bad Request	缺少请求参数或者请求参数无法解析，请检查并确保请求参数完整、格式正确
  421	Bad Request	必填参数不能省略，请查看API文档补充必选参数后再尝试
  423	Bad Request	已存在，无需再次创建
  429	Bad Request	API请求频率次限制，请稍后再试，请查看API文档以获取该接口请求频率限制
  5xx	Server Error	系统异常，请联系我们: service@toolstip.cn