瀚沄社区第三方接入文档 V0.0.2

API

V0.0.2 Changes

• access_token 过期时间单位调整为秒,有效性策略微调整
• 商家信息列表中增加运费信息
• 商家信息增加 标题, 主页, logo 字段
• 商品详情增加宣传语字段
• 下单接口增加下单备注
• 增加错误码和返回码详情
• 增加默认编码方式约定
• 商品详情增加type类型(service|goods)
• 商品详情更改增加传入商品ID
• 增加接入要求
• 删除配下单请求中多余的配送价格字段
• getcallbackip 增加APPID字段
• 商户详情返回数据增加说明
• 下单链接增加返回说明
• 修改订单更新状态请求方式，增加相关说明

简介

瀚沄社区的电商服务主要依靠接入第三方电商来完成,为了方便大家的接入,特书写以下文档.以下文档涉及到的HTTP请求及返回都默认为UTF-8

接入要求

商家需要提供如下信息用于基础接入:

• 商家名称
• 商家地址
• 商家客服邮箱
• 商家客服电话
• 商家logo url(96*96)
• 商家主页url
• 商家信息url
• 商家标题 (页面标题显示使用,8字以内)

提供这些后瀚沄社区会以邮件提供如下信息即可以做接入:

• APPID
• APPSECRET

接入授权

第三方平台在接入的时候需提供一个用户获取商户信息的url,并会获取到一个APPID和APPSECRET(目前以邮件告知,请务必妥善保存),瀚沄社区平台以此来验证第三方平台身份.

链接地址
http://community.dreamlabchina.com/api/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

访问方向
第三方后台 -> 瀚沄社区服务

鉴权
无需鉴权

链接请求约定
http请求方式: GET
grant_type:获取凭证的时候此处填写client_credential
APPID和APPSECRET使用申请接入的时候分配的APPID和APPSECRET

链接返回约定

• 正常返回

{
    "status":",
    "access_token":"ACCESS_TOKEN",
    "expires_in":24                   #单位是秒
}

• 异常返回

{
    "status":"ERROR",
    "errcode":40013;
    "errmsg":"invalid op"
}

在获取新的access_token之后原token还会维持有效5分钟,方便业务切换

获取服务器ip地址

用于第三方商户获取瀚沄社区后台IP列表,用于简单鉴权

链接地址
http://community.dreamlabchina.com/api/getcallbackip?access_token=ACCESS_TOKEN&appid=APPID

访问方向
第三方商户 -> 瀚沄社区后台

鉴权
通过access_token鉴权

链接请求约定
请求方式:GET

链接返回约定

• 正常

{
    "status":"OK",
    "ip_list":["127.0.0.1",...]    #ip列表
}

• 异常

{
    "status":"ERROR",
    "errcode":40013;
    "errmsg":"invalid op"
}

获取商户信息

主要用于瀚沄社区后台从商户处获取商品信息

链接地址
此处链接地址由第三方商户在申请接入时提供

访问方向
瀚沄社区 -> 第三方商户

鉴权
第三方商户可以根据瀚沄服务器的IP地址进行鉴权

链接请求约定
http请求方式: GET

链接返回约定

• 正常

{
    "status":"OK",
    "store":{
        "name": 商家名称,
        "addr": 商家地址,
        "email": 客服邮箱,
        "hotline": 客服电话,
        "title": 商家标题(页面标题显示用,8字内),
        "logo_url": 商家logo(96*96),
        "web_url": 商家网站url
    },
    "promotion":[{                           优惠
    "promotion_pic_link":url,                优惠图片链接
    "promotion_link":url                     优惠链接,指向第三方商户页面
    },...],
    "delivery":[{                           运费
        "price": 运费价格,
        "discount_type": 减免类型
        "condition":条件数值            
    }..]
    "order_url":下单地址,
    "comment_url":评价地址,
    "goods":{
        "goods_num":number,  # 商品数量
        "goods_list":[{
            id：  商品ID
            pic： 商品图片， url形式提供
            desc： 商品描述, 
            price： 商品价格，
            detail_url： 商品详情url
        },...]
    }
}

关于运费的说明:

运费的表述结构为 [{price, discount_type, condition}..]

price表示价格,

discount_type表示减免类型,包括no_discount(正常情况), amount_limit(满多少钱减免运费, time_limit(限时免运费), count_limit(限前多少件免运费), 但目前仅支持price_limit

condition表示条件数值

no_discount时此项填空

amount_limit时此项填充需要的订单总额

time_limit时此项填充填充 开始时间-结束时间 字符串,其中时间以unix timestamp(从1970到现在的秒数)形式表示,
返回的时候请按照price从低到高排序,系统计算运费的时候会逐次匹配,找到第一个匹配的时候返回.
示例:

[{"price":0, "discount_type":"amount_limit", "conditon":"100"}, 
{"price":12, "discount_type":"no_discount", "conditon":""}]

以上表示满100元免运费, 正常运费价格12.

异常

{
    "status":"ERROR",
    "errcode":40013,
    "errmsg":"invalid op"
}

商户信息变更

主要用于第三方平台通知瀚沄社区后台商户信息发生变化,瀚沄社区后台在得知变更后会重新拉取相关数据

链接地址
http://community.dreamlabchina.com/notify?eventtype=storeinfo_change&access_token=ACCESS_TOKEN&appid=APPID

访问方向
第三方平台 -> 瀚沄社区后台

鉴权
access_token

请求约定
请求方式: GET
请求参数:
  event_type 事件类型
  access_token 用于鉴权的token
  appid 用于鉴别第三方appid

响应约定

• 正常

{
    "status":"OK"
}

• 异常

{
    "status":"ERROR",
    "errcode":40013;
    "errmsg":"invalid op"
}

商品详情

商品详情页面由瀚沄社区后台在用户访问相关商品的时候访问第三方商户后台获取

链接地址
由商户信息中,detail_url提供
http://detail_url/

访问方向
瀚沄社区 -> 第三方

鉴权
第三方商户可以根据瀚沄服务器IP鉴权

链接请求约定
http请求方式: GET

链接返回约定

• 正常

{
    "id":商品ID,
    "class_name": 分类名称(标题名),
    "type": 商品类型服务或商品(service|goods)
    "pic":图片url,
    "desc":商品简述,
    "size":商品规格
    "price":商品单价,
    "adv":商品宣传语,
    "avail_time":可用时间列表,
    "store": {
        name:商家名称,
        addr:商家地址,
        logo:商家logo url
    }
    "detail":商品详情,
    "payed_num":已购买数量
}

avail_time使用如下约定,以数组形式给出,共两个元素,第一个表示工作日,第二个表示周末,元素定义为起始时间|结束时间|选择时间间隔|最少等待时间 如周末或者周内不提供服务只需要把对应字符串置空即可,如周内和周末服务时间相同,需要填写两次. 对于不需要此时间的商户可以直接把数组置空.
例如:
["8|20|2|2", "10|18|2|2"] 表示工作日每天8-20点提供服务,选择时间间隔为2小时,最早可用时间至少为当前2小时后,周末每天10-18点提供服务,选择时间间隔为2小时,最早可用时间至少为未当前2小时后
["8|20|2|2", ""] 表示只在工作日可用
["", "8|20|2|2"] 表示只在周末可用

• 异常

{
    "status":"ERROR",
    "errcode":40013;
    "errmsg":"invalid op"
}

商品详情变更

用于第三方通知瀚沄社区后台商品详情发生变化,例如价格/服务时间等.

链接地址
http://community.dreamlabchina.com/notify?event_type=goodsdetail_change&goods_id=GOODS_ID&access_token=ACCESS_TOKEN&appid=APPID

访问方向
第三方平台 -> 瀚沄社区后台

鉴权
access_token

请求约定
请求方式: GET
请求参数:
    goods_id 商家对应商品的ID,在商户信息和商品详情都有返回
    event_type 事件类型

响应约定

• 正常

{
    "status":"OK"
}

• 异常

{
    "status":"ERROR",
    "errcode":40013;
    "errmsg":"invalid op"
}

下单

用于瀚沄社区后台向第三方商户下单

访问方向
瀚沄社区 -> 第三方商户

链接
此链接地址在获取商户信息时获得.

鉴权
第三方商户可以根据瀚沄服务器IP鉴权

链接请求约定

"order_info":{
    "order":{
        "id":订单id,
        "price":订单总价,
        "delivery_price":配送价格,
        "time":订单时间,
        "request_time":预期配送/服务配送时间,
        "comment": 用户备注
    },
    "goods":[{
        "id":商品ID,
        "price":商品价格,
        "count":商品数量,
    },...
    ],
    "customer":{
        name: 客户名称,
        phone: 客户电话,
        addr: 客户地址,
    },
}

其中request_time目前只对服务类产品有效,实物类商品的提供上可以忽略该参数

链接返回约定

• 正常

{
    "status":"OK", 
    “order_id”: 商户订单号，字符串，32未以内
}

• 异常

{
    "status":"ERROR",
    "errcode":40013,
    "errmsg":"invalid operation"
}

订单状态更新

用于第三方回调更新订单状态

链接地址
http://community.dreamlabchina.com/api/notify/? \
eventtype=storeinfo_change& \
order_id=ORDERID&state=STATE&time=TIME&request_time=REQUEST_TIME& \
access_token=ACCESS_TOKEN&appid=APPID

访方向
第三方商户 -> 瀚沄社区后台

鉴权
通过access_token进行

链接请求约定
访问方式: GET
请求参数:

"order_id":订单编号(商户订单编号）;
"order_state":订单状态,
"time":订单状态变更时间,  # 时间以unixtimestamp(从1970到现在的秒数)形式表示
"request_time":商家和客户线下协商的时间 #表示形式同上
"access_token": ACCESS_TOKEN
"appid": APPID

order_state包括 delivering(配送中), completed(已完成)
request_time在商家和用户协商后,可以由商家发起修改

链接返回约定

• 正常

{
    "status":"OK"
}

• 异常

{
    "status":"ERROR",
    "errcode":40013;
    "errmsg":"invalid op"
}

评价

用于瀚沄社区平台向第三方商户反馈订单评价情况

链接地址
从商户信息中获取

访问方向
瀚沄社区 -> 第三方商户

鉴权
第三方商户可以根据瀚沄服务器IP鉴权

链接请求约定

• 访问方式: POST
• 请求内容:

comment:{
        order_id:订单号,
        "detail":评价内容,
        "stars":评价星级
}

评价星级为1-5

链接返回约定

• 正常

{
    "status":"OK"
}

• 异常

{
    "status":"ERROR",
    "errcode":40013;
    "errmsg":"invalid op"
}    

返回以及错误码详情