# 二、API调用详解


## 1、调用流程

根据 FDOP 的协议：填充参数 > 生成签名 > 拼装HTTP请求 > 发起HTTP请求> 得到HTTP响应 > 解释json/xml结果。

####



## 2、调用入口

调用 API 的服务 URL 地址， FDOP 目前提供了 2 个环境给 ISV 使用：测试环境和正式环境。
测试环境： ISV软件上线之前的正式模拟环境，输出的为 mock 数据，应用创建成功后即可使用。
正式环境： ISV软件上线之后使用的环境，完成之前的测试没问题后就可以申请使用，具体咨询对接人员。 正式环境为了缩短网络延迟，分别提供海外和国内域名，ISV可以根据自身服务器所在区域选择使用。

##
## | 调用环境 | 服务地址（HTTPS） |
| 测试环境  https://openapi-test.fordeal.com/route/rest |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| 正式环境 | https://cn-openapi.fordeal.com/route/rest  https://openapi.fordeal.com/route/rest |

##
##
####



## 3、公共参数

调用任何一个API都必须传入的参数，目前支持的公共参数有：
| 参数名  说明 | 必选  类型 |
|---------------|------------|------------|------------|
| appKey | 开发者在 Fordeal 开放平台创建的应用唯一标识。 | 是 | string |
| format  只支持JSON。 | 是  string |
|------------------------|------------------------------|---------|------------------------|
| method | API接口名称。如：base.getFulfillmentCenterList | 是 | string |
| sign  API输入参数签名结果，签名算法参照下面的介绍。 | 是  string |
|------------------|------------------------------------------------------------------------------|---------|------------------------|
| signMethod | 签名的摘要算法，可选值为：hmac，md5。 | 是 | string |
| timestamp  请求发起时刻的时间，格式为 ISO 8601。示例：2020-01-21T02:10:39+00:00，API服务端允许客户端请求最大时间误差为10分钟 | 是  string |
|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|------------------------|
| version | 接口版本号，固定1.0 | 是 | string |
| accessToken  用户登录授权成功后，FDOP颁发给应用的授权信息 | 是  string |
|---------------------------------------|------------------------------------------------------------------------------|---------|------------------------|

备注：
1. 公共参数通过 http url query 进行传参；
2. 业务参数通过 http request body 进行传参，参数格式跟公共参数 format 指定的格式保持一致；

####



## 4、业务参数

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



## 5、签名算法

为了防止 API 调用过程中被恶意篡改，调用任何一个 API 都需要携带签名， FDOP 服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。 FDOP 目前支持的签名算法有两种： MD5(sign_method=md5) ， HMAC_MD5(sign_method=hmac) ，签名大体过程如下：
- 对所有API请求参数（包括公共参数和业务参数，但除去sign参数、byte[]类型的参数和body参数），根据参数名称的ASCII码表的顺序排序。如：foo:1, bar:2, foo_bar:3, foobar:4排序后的顺序是bar:2, foo:1, foo_bar:3, foobar:4。
- 将排序好的参数名和参数值拼装在一起，根据上面的示例得到的结果为：bar2foo1foo_bar3foobar4。

- 如果存在 body 参数，将 body 拼在后面。
- 把拼装好的字符串采用utf-8编码，使用签名算法对编码后的字节流进行摘要。如果使用MD5算法，则需要在拼装的字符串前后加上app的secret后，再进行摘要，如：md5(secret+bar2foo1foo_bar3foobar4+body+secret)；如果使用HMAC_MD5算法，则需要用app的secret初始化摘要算法后，再进行摘要，如：hmac_md5(bar2foo1foo_bar3foobar4+body)。

- 将摘要得到的字节流结果使用十六进制表示，如：hex(“helloworld”.getBytes(“utf-8”)) = “68656C6C6F776F726C64”

说明 ： MD5 和 HMAC_MD5 都是 128 位长度的摘要算法，用 16 进制表示，一个十六进制的字符能表示 4 个位，所以签名后的字符串长度固定为 32 个十六进制字符。

####



## 6、签名算法示例




注意事 项
- 所有的请求和响应数据编码皆为utf-8格式，URL里的所有参数名和参数值请做URL编码。
- 参数名与参数值拼装起来的URL长度小于1024个字符时，可以用GET发起请求；参数类型含byte[]类型或拼装好的请求URL过长时，必须用POST发起请求。所有API都可以用POST发起请求。

##
##



## 7、API返回数据说明








## 8. 公共代码

公共代码包含具体的错误信息和详细描述
| 代码(code)  描述(message) | 解决方案 
|------------------------------|---------------------------------------|------------------|
| A0001 | missing public parameters | 缺少公共参数，检查请求参数是否正确。 |
| A0002  invalid appKey | 无效的应用key。 
|---------------------|------------------------------------------------|---------------------------------|
| A0003 | signature is invalidate | 签名验证失败，查看文档检查加签方式是否正确。 |
| A0004  repeat request | 请求重复。 
|---------------------|------------------------------------------------|---------------------|
| A0005 | invalid redirectUri | 重定向地址验证失败，重定向地址要求与应用配置的回调地址在相同的域名下。 |
| A0006  invalid method | 无效的方法名。 
|---------------------|------------------------------------------------|---------------------------|
| A0007 | invalid timestamp | timstamp不在有效时间范围内，FDOP允许客户端请求最大时间误差为10分钟。 |
| A0008  sign failed | 加签失败，请联系FDOP技术。 
|---------------------|---------------------------------------|---------------------------------------------------|
| A0009 | network error | 网络错误，排查网络延迟或者切换FDOP海外/国内域名。 |
| A0010  api not found | api不存在，检查接口拼写是否正确。 
|---------------------|---------------------------------------------|------------------------------------------------------------|
| A0401 | token is invalidate | token验证失败。 |
| A0402  permission denied | 应用没有接口访问权限，请联系FDOP运营。 
|---------------------|---------------------------------------------------------|---------------------------------------------------------------------|
| A0403 | app call limited | 接口调用超过限制，降低频率或者联系FDOP技术。 |
| B0001  system busy | 系统错误。 
|---------------------|---------------------------------------|---------------------|
| B0002 | timeout | 请求超时。 |



## 9.错误码

错误码是错误的归类代码，代表一个大类的错误
| 错误码(errorCode)  错误描述(errorMessage) | 解决方案 
|------------------------------------------------|------------------------------------------------------------|------------------|
| 10001 | 地址异常 | 查看具体错误原因，检查参数。 |
| 10002  风控异常 | 查看具体错误原因，联系平台运营。 
|---------------------|------------------|------------------------------------------------------|
| 10003 | 库存异常 | 查看具体错误原因，联系平台运营。 |
| 10004  商品异常 | 查看具体错误原因，联系平台运营。 
|---------------------|------------------|------------------------------------------------------|
| 99991 | 参数异常 | 查看具体错误原因，检查参数。 |
| 99992  权限异常 | 查看具体错误原因，检查参数。 
|---------------------|------------------|------------------------------------------------|
| 99998 | 系统异常 | 查看具体错误原因，稍后重试或者联系平台运营。 |
| 99999  其他异常 | 查看具体错误原因，稍后重试或者联系平台运营。 
|---------------------|------------------|------------------------------------------------------------------------|