引言

  马蜂窝旅行商城主要包括：自由行（机票＋酒店）、当地游、签证、邮轮、跟团游、门票、定制等七大业务线。

  本文档主要对门票业务提供支持，包括当前门票业务下的“景区/场馆”、“节庆/嘉年华”、“游乐园”、“温泉票”、“滑雪票”、“通票/年票”、“游船票”、“观光巴士票”八个二级品类；

  文档描述了马蜂窝开放平台对于门票业务订单提供的对接解决方案，帮助马蜂窝平台商家快速完成对接，包括用户下单和退款以及日录库存同步。

 （注：此文档适用于马蜂窝平台商家业务，不支持马蜂窝自营业务）

          1、 以平台商家身份入驻马蜂窝旅行商城；

  2、 完成马蜂窝开放平台接入申请，获取parter_id、client_secret、ase_key等接入参数；

  3、 参照本文档完成接口开发；

  4、 与马蜂窝在线上环境进行接口联调、测试和接口校验工作；

  5、 将完成接入系统的信息，添加至马蜂窝开放平台业务；

  6、 以商家身份选择已接入系统，正式启用接口对接；

         商家：泛指已经入驻马蜂窝旅行商城的平台商家；

         接入系统：平台商家使用的ERP系统，可能是商家自行研发系统或者是市面常见三方系统；如若是三方系统想直接接入，可以找寻平台商家提供支持或者联系马蜂窝门票业务申请测试商家账号；

 马蜂窝开放平台（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

否

此参数在涉及到文件上传的接口时为必填参数 ，其他接口不用传该参数

 马蜂窝的所有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 加密。加密后的结果为本次请求的签名。

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

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

         随机串的生成规则为：

             1、 长度为16为字符串

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

         具体 PHP 的示例如下：