马蜂窝开放平台（MFWOpenDeals）API是基于HTTPs协议来调用的接口。开发者可以通过封装相应的请求以调用对应的API。具体加密的方法和解密的方法可以通过马蜂窝提供的SDK进行加工。以下是对封装请求的详细描述。

调用说明

调用流程

根据马蜂窝定义的协议：

      1. 加密请求数据(data)

      2. 拼接请求基本字段内容

      3. 生成签名

      4. 发送HTTP请求

      5. 得到HTTP相应

      6. 解密数据

      7. 解析JSON结果

调用入口

环境名称	请求地址(HTTPs)	请求方法
正式环境	https://openapi.mafengwo.cn/deals/rest	“POST (是用 multipart/form-data 编码方式，请求参数包含在请求体(Body)中)”

公共参数 

基础参数

      调用任何马蜂窝开放平台API的时候均需要携带基础参数，目前支持的公共参数为：

参数名	参数类型	必填	参数描述
partnerId	int	是	合作商家ID
action	string	是	API接口的动作名称
timestamp	string	是	请求发起的时间戳
nonce	string	是	随机串。具体如何产生随机串，请看“产生随机串”小节
data	string	是	业务接口请求数据(需要加密)，具体如何加密请求数据，请看“加密请求数据”小节
sign	string	是	根据基础参数生成的数据签名。具体如何产生签名，请看“生成签名”小节
access_token	string	是	OAuth token。具体如何获取   Access Token 请看“获取Access Token”小节
file_data	file	否	此参数在涉及到文件上传的接口时为必填参数 ，其他接口不用传该参数

合作商加获取授权令牌(Access Token)

      马蜂窝的所有API请求最开始都需要经过OAuth的认证方式检验请求是否合法。所以所有的合作商家在请求接口之前需要持有在有效期内的 Access Token。

• 授权URL ：https://openapi.mafengwo.cn/oauth2/token

• HTTP请求方法： GET

• 请求参数：

参数名	参数类型	必填	参数值	参数描述
grant_type	string	是	client_credentials	固定值
client_id	string	是		分配给合作商户的ID
client_secret	string	是		分配给合作商户的Secret

• 正常返回数据：

• 返回格式：

参数名	类型	示例	描述
access_token	string	3a6312c6713bf06284f561240813b8a3	AccessToken
token_type	string	GET	请求的HTTP方法类型
expires_in	string	7200	Token 的有效期，单位为秒

• {"access_token":"3a6312c6713bf06284f561240813b8a3","tokent_ype":"GET","expire_in":7200}

• 异常返回数据：

• 返回格式

参数名	类型	示例	描述
error	string	invalid_request	请求认证的异常原因

    

    异常列表

异常码	描述
invalid_request	grant_type 参数异常
invalid_client	client_id 参数异常
unauthorized_client	授权失败

• 注：默认 Token 有效期为120分钟(7200秒)

加密请求数据

      请求数据加密的原因是因为在合作供应商调用马蜂窝开放平台接口的时候，传递的数据均为敏感数据，如果是以不加密的方式传输的话，很容易被查看到。所以为了数据保密性，我们要求传输的数据也必须为密文传输。
具体的加密规则如下：

   1. AES256/CBC/PKCS7Padding 加密

   2. 对AES加密数据进行一次base64编码

生成签名

      在数据已经加密完成之后，我们需要对 partnerId、action、timestamp、key、nonce 和 data 字段进行合并，并对汇总后的字符串进行 MD5 加密。加密后的结果为本次请求的签名。

sign = MD5(partnerId ＋ action ＋ timestamp ＋ key + nonce + data)

• 注: key值为马蜂窝为合作商户分配的私钥，不做明文传输，请合作商户保管好此私钥。若开发人员不知道此私钥，请联系与马蜂窝开放平台的对接人员。此key可以参看马蜂窝后台“开放平台API”-“开发者配置”-“开发者参数” 中的 ase_key 一项。

经过 md5 加密后的英文字符均应为小写字符，否则验证会不通过。示例："PHP"字符加密后的结果为 2fec392304a5c23ac138da22847f9b7c

产生随机串

      随机串的生成规则为：

      1. 长度为16为字符串

      2. 字符串仅能包括 大小写英文字符、数字

       具体 PHP 的示例如下：

    /**
     * 随机生成字符串
     * @param int $iMaxLength
     * @return string 生成的字符串
     */
    public function sGetRandomStr($iMaxLength = 16)
    {
        $sRandom = '';
        $sPol = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyz';
        for ($i = 0; $i < $iMaxLength; $i++) {
            $sRandom .= $sPol[mt_rand(0, 61)];
        }
        return $sRandom;
    }

数据返回

       在请求马蜂窝开放平台的接口时，接口请求成功则会返回1000,并返回相应的数据。示例结构如下：

{
  "data":[],
  "errno" : 1000,
  "message" : "成功"
}

！ 返回的数据也会经过加密，加密的方式与请求数据的 data 字段的加密方式相同，具体请看“加密请求数据”小节

异常列表

        但出现异常时，接口会返回异常码。若异常码为5位则为系统错误，其他情况为业务错误，系统错误列表如下：

错误码	描述
10001	签名验证失败
10002	时间戳异常或缺少时间戳参数
10003	缺少partnerId
10004	partnerId内容异常
10005	缺少签名参数
10006	异常签名参数
10007	缺少方法名参数
10008	异常方法名参数
10009	缺少Access Token参数
10010	异常Access Token参数
10013	缺少随机串
10014	随机串参数异常
10015	缺少数据字段
10016	无效数据格式
10020	未知商户

>>点此下载加密与解密demo<<