版权所有©,上海海鼎信息工程股份有限公司,2016-2022,保留所有权利。
接入指南
接口开发规范
-
协议规则
传输方式:采用HTTPS传输 提交方式: 参数以HTTP REQUEST PAYLOAD形式进行提交。 设置Content-Type为“application/json” 设置Accept为“application/json” 数据格式:传入以及返回数据以JSON格式表达 字符编码:采用UTF-8字符编码 -
安全规范
认证:采用HTTP Basic Authentication 进行身份认证
通知回调
-
用途
通知回调方式是由鼎立云主动通知的方式来回调接入系统,相比传统的由接入系统轮询鼎立云的方式,回调方式更及时高效,特别是在一些对时间要求比较高的场景中,回调性能更好,且能减少系统压力。
-
回调说明
接入系统需要提供一个可被公网访问的URL地址,出于传输安全的需要,建议使用https方式但不进行证书校验)。 接入系统可以订阅不同的通知主题,不同的主题可以使用不同的回调地址,回调方式也可以和轮询方式同时使用。
-
格式内容说明
消息字段 |
字段名称 |
说明 |
|
id |
消息ID |
消息的唯一标识 |
|
group |
消息分组 |
用于消息业务类型的分组 |
|
content |
消息内容,json字符串 |
用于传递消息关键业务信息,如订单号 |
|
time |
消息时间 |
消息产生时间 |
-
消息示例
{
"id": "1",
"group": "order",
"topic": "order.shipped",
"content": "{ \"order_id\": \"44546546512132\" }",
"time": "2019-04-30 10:00:00"
"tag": "store:001"
}
接入系统收到回调后请返回成功:
{
"success": true
}
如果接收失败,可以返回错误,鼎力云将会延时重试推送10次,超过10次后此通知将被抛弃:
{
"success": false,
"message": "错误信息"
}
为了获得更好的性能,接入系统响应回调通知要求在200ms之内完成,对于处理时间比较长的任务,建议先收下通知再异步处理。
接入平台授权
-
授权信息说明
平台(platform_id) 开通新平台,需要约定平台ID,用于管理订单履约规则。 平台商家(shop_id) 开通新平台,需要指定一个平台商家,用于管理订单履约规则。 租户申请(tenant_id) 不同商户调用不同URL。 如SAAS生产:提交订单:http://api.u.hd123.com/{tenant_id}/soms/orderservice/order 接口用户名(user) 调用鼎力云接口的用户名 接口密码(password) 调用鼎力云接口的密码 -
沙箱授权申请
开发联调过程中,由项目工程负责人内部发起流程申请。
-
商户授权申请
上线申请过程中,由项目工程负责人内部发起流程申请。
业务场景
平台订单对接
接入方作为【平台】的角色,接入中台,由中台完成订单履约
-
门店配送订单流程

说明: 提交订单后: 订单状态->已确认;配送状态->未配送 门店作业:门店接单->接单(accepted);门店备货->接单(shipping); 更新配送状态(shipped): 订单状态->配送中(delivering);配送状态->已发货(shipped) 更新配送状态(signed): 订单状态->配送完成(delivered);配送状态->已妥投(signed)
相关接口: link:http://apidoc.hd123.com/public/soms/dly-doc/mcyp/#_soms_orderservice_newsubmit[提交订单]
相关消息: link:http://apidoc.hd123.com/public/soms/dly-doc/mcyp/#%E5%8F%AF%E8%AE%A2%E9%98%85%E7%9A%84%E9%80%9A%E7%9F%A5%E5%88%97%E8%A1%A8[order.state.changed]
-
订单发货前整单取消

说明: 提交订单: 订单状态->已确认;配送状态->未配送 取消订单: 订单状态->已取消;配送状态->未配送
-
订单发货后整单退

说明: 提交订单后: 订单状态->已确认;配送状态->未配送 更新配送状态(shipped): 订单状态->配送中;配送状态->已发货 取消订单: 订单挂起,生成退货单 确认收到退货: 订单状态->配送完成;配送状态->已拒收
-
仅退款流程

说明: 提交退款单(type=refund): 退单状态->已生成;退款状态->未退款 退款同意: 退单状态->已完成;退款状态->已退款 退款拒绝: 退款状态->已取消;退款状态->未退款
-
退款退货流程

说明: 提交退单(type=refundAndRtn): 退单状态->已生成;退货状态->未退货 确认退状态: 退单状态->已完成;退货状态->已退货
-
订单预占货
image:images/stock.png
-
订单预占货取消

平台资料对接
资料层级结构

说明:
平台商家:一个平台可以开通多个店铺(品牌、商家),一个店铺对应一个平台商家。
如:友客客户有两个品牌入驻了美团:友客、益欣,对于美团来说这两个品牌是两个商家,那在中台,友客和益欣就是同一个平台下的两个平台商家。
平台门店:一个平台商家可以关联多个门店,每个平台门店映射一个线下门店
平台商品:一个平台可以售卖的商品范围
平台门店商品:平台下的某个门店可以售卖的商品范围
未启用资料中台的场景
提交平台门店

说明:
平台门店:表示【本平台】要上线的门店范围,不在范围内的门店,不会同步该平台的库存、价格
提交平台商品

说明:
平台商品:表示【本平台】要上线的商品范围,设置平台商品,可以缩小同步给该平台的库存、价格范围,提升同步效率
启用资料中台的场景

资料中台开放平台文档: http://apidoc.hd123.com/public/mas/1.0.0/
平台门店
消息通知:platform_shop.changed.notify
查询API:/v2/{tenant}/service/platformcategory/query
平台分类
消息通知:platform_category.changed.notify
查询API:/v2/{tenant}/service/platformcategory/query
平台商品
消息通知:platform_front_spu.changed.notify
查询API:/v2/{tenant}/service/platformfrontspu/{platformId}/{frontSpuId}
平台门店商品
消息通知:platform_shop_sku.changed.notify
查询API:/v2/{tenant}/service/platformShopSku/query
效果示例:

平台价格更新对接
价格变化通知

通知示例:
{
"id": "1",
"group": "sku",
"topic": "store.pricechanged",
"scope": "store:0001",
"content": {
"skus": [
{
"store_id": "1001",
"sku_id": "10001",
"price": 100
},
{
"store_id": "1001",
"sku_id": "10002",
"price": 150
}
]
},
"time": "2019-04-30 10:00:00"
}
接入系统收到回调后请返回成功:
{
"success": true
}
如果接收失败,可以返回错误,鼎力云将会延时重试推送3次,超过3次后此通知将不再重试:
{
"success": false,
"message": "错误信息"
}
平台库存更新对接
库存变化通知

通知示例:
{
"id": "1",
"group": "sku",
"topic": "store.skuchanged",
"scope": "store:0001",
"content": {
"skus": [
{
"store_id": "1001",
"sku_id": "10001",
"qty": 100
},
{
"store_id": "1001",
"sku_id": "10002",
"qty": 150
}
]
},
"time": "2019-04-30 10:00:00"
}
接入系统收到回调后请返回成功:
{
"success": true
}
如果接收失败,可以返回错误,鼎力云将会延时重试推送3次,超过3次后此通知将不再重试:
{
"success": false,
"message": "错误信息"
}
门店履约端接入
接入方作为【门店履约方】的角色,接入中台,完成线上单据的履约操作
-
订单流程

说明: 新订单通知 获取打印数据,打印小票 查询订单详情 拣货操作 送货操作 送达确认 自提确认
-
仅退款流程

说明: 新退款通知 查询退款详情 同意退款 拒绝退款
-
退款退货流程

说明: 新退货通知 查询退货详情 同意退款 拒绝退款 确认收货成功 确认收货失败
ERP接入
接入方作为【ERP】的角色,接入中台,完成资料同步、销售单据结算等流程
-
资料流程

说明: 通过门店同步接口,同步门店信息给鼎力云 通过品牌同步接口,同步品牌信息给鼎力云 通过类目同步解耦,同步商品类目信息给鼎力云 通过主档同步接口,同步商品主档信息给鼎力云 通过商品同步接口,同步商品信息给鼎力云 通过门店商品同步接口,同步门店商品信息给鼎力云 通过门店商品库存更新接口,同步库存信息给鼎力云 通过门店商品价格更新接口,同步价格信息给鼎力云
-
批发单流程

说明: 订单发货通知 查询订单详情
-
仅退款批发退流程

说明: 退款确认通知 查询退单详情
-
退款退货批发退流程

说明: 退货收货通知 查询退单详情
-
平台对账数据流程
说明: 新订单对账消息通知 查询账单详情
促销场景
促销是线下商家典型采用的促销场景,包含多种促销模版。
概念:
促销活动:是指定时间段发生的一次促销行为。
促销模型:目前支持四种类型的促销模型:打折、满减、特价、赠送。
促销模版:在特定促销模型下变化出来的具体促销内容,比如特价分为单品特价、组合特价等。
-
单品特价
模版名:single_price 说明:A从原先的价格X元直接降为Y元 示例:购买商品69010020045,原价20元,特价10元
{ "sku_id": "69010020045", "std_price": 20.00, "price": 10.00 } -
组合特价
模版名:group_price 说明:商品A,B,C任选m件n元 示例:购买商品69010020045、69303401295任选2件10元
{ "sku_ids": ["69010020045", "69303401295"], "buy_qty": 2, "price": 10.00 } -
捆绑特价
模版名:package_price 说明:购买A商品X件,并且购买B商品m个或者C商品n个特价Y元 示例:购买2件商品69120434096,再任选1件691111111或692222222,特价10.00
{ "fixed_sku_id": "69120434096", "fixed_qty": 2, "optional_skus": [ { "sku_id": "691111111", "qty": 1 }, { "sku_id": "692222222", "qty": 1 } ], "price": 10.00 } -
单品折扣
模版名:single_discount 说明:购买A商品直接X折 示例:购买商品69010020045享受6折
{ "sku_id": "69010020045", "discount": 0.6 } -
单品满数量折扣
模版名:qty_discount 说明:购买A商品满X个打Y折 示例:购买商品69010020045满5件享受6折
{ "sku_id": "69010020045", "min_qty": 5, "discount": 0.6 } -
单品满金额折扣
模版名:amount_discount 说明:购买A商品满X元打Y折 示例:购买商品69010020045满100元享受6折
{ "sku_id": "69010020045", "min_amount": 100.00, "discount": 0.6 } -
单品满数量减
模版名:qty_reduce 说明:购买A商品满X个减Y元 示例:购买商品69010020045满2件减5元
{ "sku_id": "69010020045", "min_qty": 2, "reduce_amount": 5.00 } -
单品满金额减
模版名:amount_reduce 说明:购买A商品满X元减Y元 示例:购买商品69010020045满100元立减5元
{ "sku_id": "69010020045", "min_amount": 100.00, "reduce_amount": 5.00 } -
单品满赠
模版名:single_gift 说明:买n个商品A送m个商品B(或A本身),赠品无售价,多买多送 示例:购买商品69111111每2件送1件赠品69222222
{ "buy_sku_id": "69111111", "buy_qty": 2, "gift_sku_id": "69222222", "gift_qty": 1 } -
单品满数量赠
模版名:qty_gift 说明:购买A商品满X个送B赠品Y个,只送一次 示例:购买商品69111111满2件送1件赠品69222222
{ "buy_sku_id": "69111111", "min_qty": 2, "gift_sku_id": "69222222", "gift_qty": 1 } -
单品满金额赠
模版名:amount_gift 说明:购买A商品满X元送B赠品Y个,只送一次 示例:购买商品69111111满100元送1件赠品69222222
{ "buy_sku_id": "69111111", "min_amount": 100.00, "gift_sku_id": "69222222", "gift_qty": 1 }
可订阅的通知列表
-
订单类消息
order.shipped(订单发货),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.shipped", "content": "{ \"order_id\": \"44546546512132\",\"front_order_id\": \"44546546512132\"}", "time": "2019-04-30 10:00:00" }消息内容说明
字段 字段名称 说明 order_id
海鼎订单号
唯一标识
front_order_id
平台订单号
平台维度唯一标识
order.canceled(订单取消),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.canceled", "content": "{ \"order_id\": \"44546546512132\", \"front_order_id\": \"44546546512132\" }", "time": "2019-04-30 10:00:00" }order.signed(订单签收),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.signed", "content": "{ \"order_id\": \"44546546512132\" ,\"front_order_id\": \"44546546512132\"}", "time": "2019-04-30 10:00:00" }order.refused(订单拒收),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.refused", "content": "{ \"order_id\": \"44546546512132\" ,\"front_order_id\": \"44546546512132\"}", "time": "2019-04-30 10:00:00" }return.received(退货单收货),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "return.received", "content": "{ \"order_id\": \"44546546512132\", \"front_order_id\": \"44546546512132\", \"rtn_id\": \"4565121321212125\" }", "time": "2019-04-30 10:00:00" }store.order.created(门店新订单),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "store.order.created", "tag": "store:001", "content": "{ \"order_id\": \"44546546512132\" }", "time": "2019-04-30 10:00:00" }store.return.created(门店新退货),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "store.return.created", "tag": "store:001", "content": "{ \"order_id\": \"44546546512132\", \"rtn_id\": \"84544465646545645\"}", "time": "2019-04-30 10:00:00" }store.order.shipped(门店订单发货),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.shipped", "tag": "store:001", "content": "{ \"order_id\": \"44546546512132\" }", "time": "2019-04-30 10:00:00" }store.return.received(门店退货单收货),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "return.received", "tag": "store:001", "content": "{ \"order_id\": \"44546546512132\", \"front_order_id\": \"44546546512132\", \"rtn_id\": \"4565121321212125\" }", "time": "2019-04-30 10:00:00" }store.order.operation(门店配送作业),其中operation取值:shipping=门店集货,cancalShipping=门店取消集货,示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "store.order.operation", "tag": "store:001", "content": "{ \"order_id\": \"44546546512132\", \"operation\": \"shipping\" }", "time": "2019-04-30 10:00:00" }refund.refunded(退款完成)示例:
{ "id": "4028fe8153b876e50153b8779b2a0002", "group": "order", "topic": "refund.refunded", "tag": "store:001", "content": "{ \"order_id\": \"44546546512132\", \"rtn_id\": \"1232142353\",\"front_order_id\": \"6578681232142353\" }", "time": "2019-04-30 10:00:00" }ordersettle.created(对账单生成消息),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "ordersettle.created", "content": "{ \"order_id\": \"44546546512132\"}", "time": "2019-04-30 10:00:00" }order.state.changed(订单状态变化消息),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.state.changed", "content": "{ \"order_id\": \"44546546512132\",\"front_order_id\": \"44546546512132\",\"state\": \"delivering\"}", "time": "2018-12-13 00:00:00" }order.deliverystate.changed(订单配送状态变化消息),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.deliverystate.changed", "content": "{ \"order_id\": \"44546546512132\",\"front_order_id\": \"44546546512132\",\"delivery_state\": \"shipped\"}", "time": "2018-12-13 00:00:00" }order.exception.changed(订单异常变化消息),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.exception.changed", "content": "{ \"order_id\": \"44546546512132\",\"front_order_id\": \"44546546512132\",\"has_exception\": \"true\",\"exception_reason\": \"异常原因\"}", "time": "2018-12-13 00:00:00" }order.carrierstate.changed(订单承运状态变化消息),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.carrierstate.changed", "content": "{ \"order_id\": \"44546546512132\",\"front_order_id\": \"44546546512132\",\"carrier_state\": \"pickup\"}", "time": "2018-12-13 00:00:00" }return.state.changed(退单状态变化消息),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "return.state.changed", "content": "{\"rtn_id\": \"44546546512132\", \"order_id\": \"44546546512132\",\"front_order_id\": \"44546546512132\",\"state\": \"finished\"}", "time": "2018-12-13 00:00:00" }order.selftake.check(自提检查接口),其中front_order_id和order_id非必传,示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.selftake.check", "content": "{\"store_id\": \"0001\",\"selftake_code\": \"自提码\",\"platform_id\": \"youzan\",\"front_order_id\": \"平台订单号",\"order_id\": \"订单号"}", "time": "2018-12-13 00:00:00" }order.operation.changed(订单门店作业状态变化消息),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.operation.changed", "content": "{ \"order_id\": \"44546546512132\",\"front_order_id\": \"44546546512132\",\"operation_state\": \"shipping\"}", "time": "2018-12-13 00:00:00" }order.item.changed(订单换货消息),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "order.item.changed", "content": "{\"platform_id\": \"youzan\",\"front_order_id\": \"平台订单号",\"order_id\": \"订单号"}", "time": "2018-12-13 00:00:00" }store.order.canceled(门店订单取消),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "store.order.canceled", "tag": "store:001", "content": "{ \"order_id\": \"44546546512132\", \"front_order_id\": \"44546546512132\" }", "time": "2019-04-30 10:00:00" } -
承运类消息
store.order.carrierexception(承运异常),示例: pickupFailed:揽件失败
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "order", "topic": "store.order.carrierexception", "tag": "store:001", "content": "{ \"order_id\": \"44546546512132\", \"carrier_state\": \"pickupFailed\" }", "time": "2019-04-30 10:00:00" } -
支付类消息
pay.order.success(订单支付成功),示例:
{ "id": "2c92819657c1a6860157c1a9f9220007", "group": "pay", "topic": "pay.order.success", "content": "{\"payAmount\":0.01,\"storeNo\":\"0088\",\"billType\":\"pay\",\"orderUuid\":\"111110016acc4916834fad23354b5fb9\",\"payNo\":\"2016101421001004080274676406\",\"orderAmount\":0.01,\"orderNumber\":\"0088161014132716708\",\"uuid\":\"cf8705ee0e194f41b11b475b1d50816b\",\"payAccountId\":\"2088002495582085\",\"payChannelName\":\"支付宝\",\"payTime\":\"2016-10-14 13:27:16\",\"payChannel\":\"aliPay\",\"tenantId\":\"testbn01\",\"sourceOrderUuid\":\"testbn01\",\"remark\":\"支付成功\",\"payState\":\"paySuccess\"}", "time": "2019-04-30 10:00:00" } -
营销类消息
activity.audited(活动发布),示例:
{ "id": "2c92819657c1a6860157c1a9f9220007", "group": "mp", "topic": "activity.audited", "content": "{ \"activity_id\": \"201708050001\" }", "tag": "store:1001", "time": "2019-04-30 10:00:00" }activity.stopped(活动下架),示例:
{ "id": "2c92819657c1a6860157c1a9f9220007", "group": "mp", "topic": "activity.stopped", "content": "{ \"activity_id\": \"201708050001\" }", "tag": "store:1001", "time": "2019-04-30 10:00:00" }coupon.consumed(券核销),示例:
{ "id": "2c92819657c1a6860157c1a9f9220007", "group": "equity", "topic": "coupon.consumed", "content": "{ \"coupon_code\": \"201708050001\" }", "time": "2019-04-30 10:00:00" }tran.created(新交易),示例:
{ "id": "4028fe8153b876e50153b8779b2a0001", "group": "member", "topic": "tran.created", "content": "{\"tran_time\":\"2017-07-26 17:17:00\",\"person_id\":\"00111\",\"pos_no\":\"0001\",\"face_id\":\"111100\",\"store_id\":\"0001\",\"tran_id\":\"qyh0000201707270007\",\"member_code\":\"8888170508000005\"}", "time": "2019-04-30 10:00:00" }
常见问题
授权相关
-
订单中心授权
沙箱授权(由项目经理发起内部流程申请以下沙箱资源) 租户ID(tenant_id):租户ID,商户的唯一表示 服务地址(url): https://sandbox.api.u.hd123.com/{tenant_id} 接口用户名(user):*** 接口密码(password):*** 平台(platform_id):用于区分不同平台 平台商家(shop_id):用于区分平台商家的不同用户 测试门店(station_id):用于联调时使用的测试门店正式环境授权(由项目经理发起内部流程申请正式环境资源) 租户ID(tenant_id):租户ID,商户的唯一表示 服务地址(url): https://api.u.hd123.com/{tenant_id} 接口用户名(user):*** 接口密码(password):*** 平台(platform_id):用于区分不同平台 平台商家(shop_id):用于区分平台商家的不同用户 -
营销中心授权
联系对接的项目经理处理
-
支付中心授权
联系对接的项目经理处理
API相关
-
订单中心
平台结算价settle_total 平台结算价:平台和商家联合促销的情况,优惠金额由商家和平台共同承担的场景。平台结算价=客户实付商品金额+平台优惠分摊金额订单金额 客户购买A、B、C上个商品,原价为A(120元),B(200元)、C(300元)。A商品促销价为100元。整单优惠60(其中平台优惠18,商家优惠42)。那么A商品优惠占比= (A的实付金额100)/(A+B+C)=1/6;B商品优惠占比=(B的实付金额200)/(A+B+C)=2/6;C商品优惠占比=(C的实付金额300)/(A+B+C)=3/6。 A的金额如下: 整单分摊金额apt_dis_amount=60*1/6=10元。 实付金额pay_amount=100-10=90元。 单品促销金额discount_amount=120-100=20元。 平台结算金额settle_total=90+(18*1/6)=93元。 B的金额如下: 整单分摊金额apt_dis_amount=60*2/6=20元。 实付金额pay_amount=200-20=180元。 单品促销金额discount_amount=0元。 平台结算金额settle_total=180+(18*2/6)=186元 C的金额如下: 整单分摊金额apt_dis_amount=60-A的整单分摊-B的整单分摊=30(为了防止除不尽的情况,最后一个商品行的整单分摊金额用减法)。 实付金额pay_amount=300-30=270元。 单品促销金额discount_amount=0元。 平台结算金额settle_total=270+(18*3/6)=279元 订单的金额如下: 订单的实付金额real_total=90+180+270=540元。 订单的平台结算金额settle_amount=93+186+279=558元。预占货订单 商家是多平台共享库存,希望在下单的时候(未付款)就扣减其他平台的库存。回调地址 鼎力云订单状态变化、库存变化、价格变化等都是通过推送消息给第三方的方式实现的。第三方平台对接需要提供接收消息的回调地址。 消息内容参考:https://u.hd123.com/view/module/doc.html#nf-api-1=
接口
Unresolved directive in index.adoc - include::/home/jenkins_new/workspace/soms-dly-doc/target/asciidoc/mcyp/public/paths.adoc[]
商户接口
Unresolved directive in index.adoc - include::/home/jenkins_new/workspace/soms-dly-doc/target/asciidoc/merchant/paths.adoc[]
对象定义
Unresolved directive in index.adoc - include::/home/jenkins_new/workspace/soms-dly-doc/target/asciidoc/mcyp/public/definitions.adoc[] Unresolved directive in index.adoc - include::/home/jenkins_new/workspace/soms-dly-doc/target/asciidoc/merchant/definitions.adoc[]
