哈哈零售API详细文档

序言

概述

以接口的形式对哈哈便利的无人售货柜进行开门、结算、查询业务数据等。

重要说明

库存管理：哈哈不维护API商家的库存信息。如商家对库存有要求，请上货时自行保存商品的库存数量，并根据识别结果对库存进行增减。

业务流程：用户扫码后商户端自行决定是否可开门（比如判断是否签约免密支付，或者用户余额是否足够）。开门时，设备的开门和关门或者发生错误状态信息，识别完成后，识别的结果，生成订单时，订单信息，都会通过消息通知给商户。商户需要自行免密签约、免密扣款等。所以一般来说，需要商户端开通支付宝和微信的免密支付才能接入本接口。

1. 接入前说明

1.1 阅读对象

定位人群：哈哈便利接口文档是面向具有一定的网站或APP开发能力，了解 ASP、PHP、JAVA、ASP.NET 等开发语言中的一种及 SQL 数据库语言的网站开发、维护和管理人员。

1.2 接入步骤

步骤1：联系哈哈运营人员开通API功能

联系哈哈运营人员开通您的商家账户的API功能。

步骤2：在商家后台配置回调地址

登录商家后台：http://client.hahabianli.com
进入"API配置"页面
配置回调地址（用于接收开关门通知、识别结果通知、订单通知等）
获取 AppId 和 AppSecret

地址要求：

订单回调地址：必须以 http:// 或 https:// 开头，例如：http://www.baidu.com
消息回调地址：必须以 http:// 或 https:// 开头，用于接收开关门消息、设备异常消息等

1.3 系统交互图

（系统交互流程示意图 - 描述商户系统、哈哈平台、设备之间的交互关系）

2. 接口规则

2.1 协议规则

基本规范：

通信协议：HTTP/HTTPS
字符编码：UTF-8
请求格式：application/x-www-form-urlencoded 或 application/json
响应格式：JSON

域名地址：

正式环境：http://api.hahabianli.com
测试环境：（如需测试环境请联系运营人员）

2.2 签名规则

签名说明：为保证接口安全，所有接口调用都需要进行签名验证。

签名算法：

将所有请求参数按照参数名ASCII码从小到大排序（字典序）
将排序后的参数拼接成字符串：key1=value1&key2=value2&...
在字符串末尾拼接 AppSecret
对拼接后的字符串进行MD5加密，得到签名值
将签名值作为 sign 参数传递

示例：

原始参数：
access_token=abc123
page_no=1
page_size=20
AppSecret=secret_key

排序后拼接：
access_token=abc123&page_no=1&page_size=20&appsecret=secret_key

MD5加密后得到 sign 值

2.3 登陆获取 access_token

简要描述：获取访问令牌，用于后续所有API调用的身份验证。

请求URL：http://api.hahabianli.com/login/getToken

请求方式：POST

请求参数：

参数名	必选	类型	说明
appid	是	string	商家应用ID，在商家后台获取
appsecret	是	string	商家应用密钥，在商家后台获取
sign	是	string	签名，签名算法见2.2章节

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "access_token": "169efc8ffe416006910bd606380782148b7587f7",
    "expires_in": 1296000
  }
}

返回参数说明：

参数名	类型	说明
code	int	返回码，1表示成功，其他表示失败
info	string	返回信息
access_token	string	访问令牌，有效期内可重复使用
expires_in	int	过期时间，单位：秒（15天 = 1296000秒）

备注：

access_token 有效期为15天（1296000秒）
token到期前2天内请求接口会自动生成新的access_token，其它时间请求接口将不会更新token
建议获取到token后自行保存，发现过期或在token到期前的2天内就对token进行更新
更多返回错误代码请看2.4全局错误码

2.4 全局错误码

通用错误码：

错误码	说明	处理方案
1	SUCCESS	操作成功
0	FAIL	操作失败
-1	参数错误	检查请求参数是否完整且正确
-2	签名错误	检查签名算法和密钥是否正确
-3	access_token无效	重新获取access_token
-4	access_token过期	重新获取access_token
-5	权限不足	联系运营人员开通相应权限
-6	请求频率超限	降低请求频率
-7	系统繁忙	稍后重试
-100	设备不存在	检查设备ID是否正确
-101	设备离线	等待设备上线后重试
-102	设备故障	联系设备维护人员
-103	设备正在使用中	等待当前购物结束后重试
-200	商品不存在	检查商品ID是否正确
-300	订单不存在	检查订单号是否正确

3. 设备接口

3.1 设备列表

简要描述：获取商家的设备列表。

请求URL：http://api.hahabianli.com/device/getlist

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
page_no	是	int	第几页，如：1，表示第一页
page_size	是	int	每页多少条，如：20 表示每页20条数据

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": [
    {
      "id": "device001",
      "name": "测试设备1",
      "address": "北京市朝阳区XXX大厦1层",
      "status": "1"
    },
    {
      "id": "device002",
      "name": "测试设备2",
      "address": "北京市海淀区XXX商场2层",
      "status": "1"
    }
  ]
}

返回参数说明：

参数名	类型	说明
id	string	设备ID
name	string	设备名称
address	string	设备地址
status	string	设备状态 (1: 正常, 2: 冻结)

备注：

更多返回错误代码请看首页的错误代码描述

3.2 设备是否多门单开

简要描述：查询设备是否为多门单开。如果只有单门柜可忽略此接口。

多门单开定义：

设备有多个门，但一次只能开一个
多门单开的设备，在调API接口开门时，必须指定门的编号（door_index参数）
从左到右，分别为A门、B门

请求URL：http://api.hahabianli.com/device/isMultiDoorUnique

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "multi_door_unique": 2
  }
}

返回参数说明：

参数名	类型	说明
multi_door_unique	int	是否为多门单开：0-非多门单开，2-双门单开，3-三门单开，4-四门单开

备注：

目前还没有三门柜、四门柜，值先预留
更多返回错误代码请看首页的错误代码描述

3.3 设备开门

3.3.1 开门

简要描述：调用此接口实现设备开门功能。

请求URL：http://api.hahabianli.com/device/open

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID
out_trade_no	是	string	商户订单号，由商户生成，全局唯一
door_index	否	int	门编号，多门单开设备必传。0或不传表示A门，1表示B门

返回示例：

{
  "code": 1,
  "info": "开门成功",
  "data": {
    "order_no": "HH202401240001"
  }
}

返回参数说明：

参数名	类型	说明
order_no	string	哈哈平台订单号

备注：

out_trade_no 建议使用时间戳+随机数生成，确保唯一性
开门成功后，设备会自动开始拍摄购物视频
关门后会触发AI识别，识别结果会通过回调接口通知
更多返回错误代码请看首页的错误代码描述

3.3.2 消息回调通知

简要描述：哈哈平台通过此接口推送各类消息通知给商户，所有消息类型通过 notify_type 字段区分。

通知URL：商户在后台配置的消息回调地址（统一入口）

请求方式：POST

通用参数：

参数名	必选	类型	说明
notify_type	是	string	通知类型，用于区分具体的消息类型
sign	是	string	签名，验证请求来源

3.3.2.1 开关门结果通知 (notify_type=DEVICE_STATUS)

触发条件：在设备开门成功、关门成功或开门失败时推送

参数说明：

参数名	必选	类型	说明
notify_type	是	string	固定值：DEVICE_STATUS
activity_id	是	string	活动编号，如：1712271138560743
create_time	是	int	创建时间戳，如：1633745862
device_id	是	string	设备号，如：D00003
open_type	是	string	IN(补货)，OUT(消费)
out_user_id	是	string	外部用户id
user_id	是	string	用户id
status	是	string	开门结果：1=ERROR(开门失败)，2=OPENED(门已开)，3=CLOSED(门已关)，4=ANOTHER(设备繁忙)
sign	是	string	签名

回调示例：

Array (
  [activity_id] => "1712271138560743",
  [create_time] => 1633745862,
  [device_id] => "D00003",
  [notify_type] => "DEVICE_STATUS",
  [status] => "OPENED",
  [open_type] => "OUT",
  [out_user_id] => "20210918001",
  [user_id] => "2109181628353272",
  [sign] => "c9e3b08303408347ae350ab2c8a22a05"
)

返回要求：

success

3.3.2.2 设备在线状态通知 (notify_type=ONLINE_STATUS)

触发条件：设备在线状态发生变化时推送（需联系运营开通权限）

参数说明：

参数名	必选	类型	说明
notify_type	是	string	固定值：ONLINE_STATUS
device_id	是	string	设备编号
is_online	是	int	设备在线状态：0=不在线，1=在线
signal_val	否	array	信号值：上线时近两次上报信号值（is_online=1时有值）
ping_val	否	array	延时值：上线时近两次上报延时值（is_online=1时有值）
sign	是	string	签名

signal_val 和 ping_val 数组结构：

[
  {
    "occur_time": 1573401600,
    "value": "1"
  },
  {
    "occur_time": 1573401600,
    "value": "1"
  }
]

回调示例：

Array (
  [device_id] => "D00085",
  [is_online] => 1,
  [notify_type] => "ONLINE_STATUS",
  [signal_val] => array:2 [
    0 => array:2 [
      "occur_time" => 1573401600
      "value" => "1"
    ]
    1 => array:2 [
      "occur_time" => 1573401600
      "value" => "1"
    ]
  ],
  [ping_val] => array:2 [
    0 => array:2 [
      "occur_time" => 1573401600
      "value" => "1"
    ]
    1 => array:2 [
      "occur_time" => 1573401600
      "value" => "1"
    ]
  ],
  [sign] => "c9e3b08303408347ae350ab2c8a22a05"
)

返回要求：

success

3.3.2.3 设备音量调节结果通知 (notify_type=VOICE_RESULT)

触发条件：设备音量调节成功时推送

参数说明：

参数名	必选	类型	说明
notify_type	是	string	固定值：VOICE_RESULT
device_id	是	string	设备号，如：D00003
voice	是	number	音量值，为 0~15 的数字
sign	是	string	签名

回调示例：

Array (
  [notify_type] => "VOICE_RESULT",
  [device_id] => "B1507",
  [voice] => 6,
  [sign] => "819bb39c0a93c05e485568083a6c8784"
)

返回要求：

success

3.3.2.4 新品审核结果回调 (notify_type=CLIENT_NEW_PRODUCT)

触发条件：新品审核完成时推送

参数说明：

参数名	必选	类型	说明
notify_type	是	string	固定值：CLIENT_NEW_PRODUCT
status	是	integer	审核状态：1=已通过，2=已拒绝，3=已上架
reject_reason	是	string	被拒绝原因
id	是	string	新品申请唯一编码
msg	是	string	审核结果信息
name	是	string	商品名称
bar_code	是	string	条形码
code	是	string	商品code标识符（拒绝时为空，通过时不为空）
product_extends	否	string	扩展字段信息
sign	是	string	签名

回调示例：

Array (
  [bar_code] => "20210913006",
  [id] => "20315850049321972025",
  [msg] => "已拒绝",
  [name] => "哈哈api测试新品申请",
  [notify_type] => "CLIENT_NEW_PRODUCT",
  [reject_reason] => "商品名称不合规范，请参考示例，重新编辑商品名称",
  [status] => 2,
  [code] => "",
  [product_extends] => "1212374",
  [sign] => "fba0b9b78efd190c4858c88afb488c93"
)

返回要求：

success

3.3.2.5 商品合并结果通知 (notify_type=MERGE_PRODUCT)

触发条件：商品合并操作完成时推送

参数说明：

参数名	必选	类型	说明
notify_type	是	string	固定值：MERGE_PRODUCT
list	是	array	商品合并列表
sign	是	string	签名

list 数组元素说明：

main_code (string): 主商品code，正常使用的商品code
product_code (string): 合并的相同商品的code，除主商品code外，同组其他商品code将不再使用

list 示例：

[
  {
    "main_code": "dongpengteyinpingzhuang",
    "product_code": "dpty8988,dpty6525,dpty500ml"
  },
  {
    "main_code": "hongshiliubaiputaoguozhi",
    "product_code": "hongshiliuputao,hongshiliubaiputaoguozhi"
  }
]

回调示例：

{
  "list": [
    {
      "main_code": "dongpengteyinpingzhuang",
      "product_code": "dpty8988,dpty6525,dpty500ml,dongpemg500ml,dongpengteyinpingzhuang"
    },
    {
      "main_code": "hongshiliubaiputaoguozhi",
      "product_code": "hongshiliuputao,hongshiliubaiputaoguozhi"
    }
  ],
  "notify_type": "MERGE_PRODUCT",
  "sign": "fba0b9b78efd190c4858c8xxxxxxxxxx"
}

返回要求：

success

3.3.2.6 识别结果通知 (notify_type=ORC_RESULT)

触发条件：AI识别完成后推送识别结果

参数说明：

参数名	必选	类型	说明
notify_type	是	string	固定值：ORC_RESULT
activity_id	是	string	活动编号，如：1712271138560743
device_id	是	string	设备号，如：D00003
result	是	string(JSON)	识别结果，包含type、data、excepts
sku_list	是	string(JSON)	商品SKU列表
out_user_id	是	string	商家用户编号
source	是	string	请求开门接口时传入的source
nobuy	是	int	是否有消费：1=无消费，0=有消费
resource_info	是	string(JSON)	视频或图片信息
sign	是	string	签名

result 字段说明：

{
  "type": "OUT",  // IN(补货) 或 OUT(消费)
  "data": {        // 商品code:数量，正数为上货，负数为消费
    "longfu": -2,
    "naicha": -4,
    "abnormal": -1,      // 异常商品（excepts=6）
    "unfriendly": -1,    // 非友好购物（excepts=1,2）
    "unknow": -1,        // 商品不在模板（excepts=5）
    "unrecognized": -1  // 无法判断订单（excepts=7）
  },
  "excepts": [1, 2, 5, 6, 7]  // 异常枚举值
}

excepts 枚举值说明：

1: 遮挡摄像头/偷吃等（result.data.unfriendly = -1）
2: 放入异物（result.data.unfriendly = -1）
5: 商品不在模板（result.data.unknow = -1）
6: 视频全黑、短缺、花屏、黑屏、主辅视频无法识别、视频结束门未关、灯光问题、视频模糊、拿取过多导致无法识别（result.data.abnormal = -1）
7: 无法判断订单（遮挡商品/手速过快）（result.data.unrecognized = -1）

sku_list 字段说明：

[
  {
    "sku": "naicha01",    // 商家自定义商品编号
    "number": -1,          // 商品数量，减少为负，增加为正
    "code": "naicha"       // 哈哈商品编码
  },
  {
    "sku": "unknow01",
    "number": -2,
    "code": "unknow"
  }
]

resource_info 字段说明：

{
  "device_type": 1,
  "video_url": "http://img.hahabianli.com/buyvideo/20210906/170309_1130918988346058398_0.mp4"
}

返回要求：

success

回调示例：

Array (
  [activity_id] => "1712271138560743",
  [device_id] => "D00003",
  [notify_type] => "ORC_RESULT",
  [result] => '{"type":"OUT","data":{"longfu":-2,"naicha":-4,"abnormal":-1,"unfriendly":-1},"excepts":[1,2,5,6]}',
  [sku_list] => '[{"sku":"naicha01","number":-1,"code":"naicha"},{"sku":"unknow01","number":-2,"code":"unknow"}]',
  [out_user_id] => '123456',
  [source] => 'XXX',
  [nobuy] => '0',
  [resource_info] => '{"device_type":1,"video_url":"http://img.hahabianli.com/buyvideo/20210906/170309_1130918988346058398_0.mp4"}',
  [sign] => "eb17ae3ae97600f2b357dc598f86b6c1"
)

备注：

针对异常场景（excepts包含值），建议商家根据实际情况做对应逻辑处理
nobuy=1 时表示用户打开柜门但没有消费
result.data 中的 abnormal、unfriendly、unknow、unrecognized 表示识别到的各类异常情况，值固定为 -1
excepts 数组与 result.data 中的异常字段相对应，用于更详细的异常类型分类

3.3.3 刷卡开门验证

简要描述：用于刷卡设备，验证用户刷卡信息是否有效。

请求URL：http://api.hahabianli.com/device/cardVerify

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID
card_no	是	string	卡号
card_type	是	int	卡类型：1-IC卡，2-身份证，3-其他

返回示例：

{
  "code": 1,
  "info": "验证成功",
  "data": {
    "can_open": true,
    "user_info": {
      "name": "张三",
      "phone": "138****1234"
    }
  }
}

返回参数说明：

参数名	类型	说明
can_open	boolean	是否允许开门
user_info	object	用户信息（可选）

3.4 设备在线状态

简要描述：查询设备当前在线状态。

请求URL：http://api.hahabianli.com/device/onlineStatus

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "online_status": 1,
    "last_online_time": "2024-01-24 15:30:00"
  }
}

返回参数说明：

参数名	类型	说明
online_status	int	在线状态：0-离线，1-在线
last_online_time	string	最后在线时间

3.5 设备音量调节

简要描述：调节设备播报音量。

请求URL：http://api.hahabianli.com/device/setVolume

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID
volume	是	int	音量值：0-100，0表示静音，100表示最大音量

返回示例：

{
  "code": 1,
  "info": "设置成功"
}

3.6 设备和锁的状态

简要描述：查询设备和门锁的实时状态。

请求URL：http://api.hahabianli.com/device/status

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "device_status": 1,
    "door_status": 0,
    "lock_status": 1,
    "camera_status": 1,
    "network_status": 1
  }
}

返回参数说明：

参数名	类型	说明
device_status	int	设备状态：0-离线，1-在线，2-故障
door_status	int	门状态：0-关闭，1-打开
lock_status	int	锁状态：0-未锁，1-已锁
camera_status	int	摄像头状态：0-异常，1-正常
network_status	int	网络状态：0-断开，1-连接

4. 商品接口

4.1 设备可售卖商品列表

简要描述：获取指定设备可售卖的商品列表。

请求URL：http://api.hahabianli.com/goods/deviceGoodsList

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": [
    {
      "goods_id": "goods001",
      "goods_name": "可口可乐",
      "barcode": "6901234567890",
      "price": 3.50,
      "image": "http://example.com/coke.jpg",
      "stock": 10
    }
  ]
}

返回参数说明：

参数名	类型	说明
goods_id	string	商品ID
goods_name	string	商品名称
barcode	string	商品条码
price	decimal	商品价格
image	string	商品图片URL
stock	int	库存数量

4.2 商品总库

简要描述：获取哈哈平台的商品总库列表。

请求URL：http://api.hahabianli.com/goods/totalList

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
page_no	是	int	页码
page_size	是	int	每页条数
keyword	否	string	搜索关键词（商品名称或条码）

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "total": 100,
    "list": [
      {
        "goods_id": "goods001",
        "goods_name": "可口可乐",
        "barcode": "6901234567890",
        "image": "http://example.com/coke.jpg"
      }
    ]
  }
}

4.3 添加商品至商家商品库

简要描述：从哈哈平台商品总库中选择商品添加到商家自己的商品库。

请求URL：http://api.hahabianli.com/goods/addToMerchant

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
goods_id	是	string	商品ID（来自商品总库）
price	是	decimal	售价

返回示例：

{
  "code": 1,
  "info": "添加成功"
}

4.4 商家商品库

简要描述：获取商家自己的商品库列表。

请求URL：http://api.hahabianli.com/goods/merchantList

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
page_no	是	int	页码
page_size	是	int	每页条数

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "total": 50,
    "list": [
      {
        "goods_id": "goods001",
        "goods_name": "可口可乐",
        "barcode": "6901234567890",
        "price": 3.50,
        "image": "http://example.com/coke.jpg",
        "status": 1
      }
    ]
  }
}

4.5 商品上下架

简要描述：设置商品在指定设备的上架或下架状态。

请求URL：http://api.hahabianli.com/goods/setStatus

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID
goods_id	是	string	商品ID
status	是	int	状态：0-下架，1-上架

返回示例：

{
  "code": 1,
  "info": "设置成功"
}

4.5.1 获取设备层模板

简要描述：获取设备的货架层级模板配置。

请求URL：http://api.hahabianli.com/goods/getLayerTemplate

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "layers": [
      {
        "layer_no": 1,
        "layer_name": "第一层",
        "goods_list": []
      }
    ]
  }
}

4.5.2 创建更新层模板接口

简要描述：创建或更新设备的货架层级模板。

请求URL：http://api.hahabianli.com/goods/updateLayerTemplate

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
device_id	是	string	设备ID
layers	是	array	层级配置数组

返回示例：

{
  "code": 1,
  "info": "更新成功"
}

4.6 新品申请

简要描述：商家申请添加新商品到哈哈平台商品总库。

请求URL：http://api.hahabianli.com/goods/applyNew

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
goods_name	是	string	商品名称
barcode	是	string	商品条码
image	是	string	商品图片URL
description	否	string	商品描述

返回示例：

{
  "code": 1,
  "info": "申请已提交，等待审核"
}

4.7 商品编号对应关系

简要描述：查询商家商品ID与哈哈平台商品ID的对应关系。

请求URL：http://api.hahabianli.com/goods/idMapping

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
merchant_goods_id	否	string	商家商品ID
haha_goods_id	否	string	哈哈平台商品ID

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "merchant_goods_id": "m_goods_001",
    "haha_goods_id": "h_goods_001"
  }
}

4.8 商品合并

简要描述：将多个相似商品合并为一个商品。

请求URL：http://api.hahabianli.com/goods/merge

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
target_goods_id	是	string	目标商品ID（保留的商品）
source_goods_ids	是	array	源商品ID数组（将被合并的商品）

返回示例：

{
  "code": 1,
  "info": "合并成功"
}

5. 订单接口

5.1 回调通知说明

回调地址配置：

在商家后台配置一个消息回调地址，用于接收所有类型的通知：

开关门状态通知 (DEVICE_STATUS)
设备在线状态通知 (ONLINE_STATUS)
设备音量调节结果通知 (VOICE_RESULT)
新品审核结果回调 (CLIENT_NEW_PRODUCT)
商品合并结果通知 (MERGE_PRODUCT)
AI识别结果通知 (ORC_RESULT) - 最重要

回调通知特点：

所有通知都通过同一个消息回调地址接收
必须包含 notify_type 字段用于区分具体的业务类型
所有通知都包含 sign 字段用于验证
商户必须返回 success 字符串表示接收成功
未正确响应会触发重试机制（最多3次，间隔5秒、30秒、60秒）

notify_type 枚举值：

notify_type 值	说明	章节
DEVICE_STATUS	开关门状态通知	3.3.2.1
ONLINE_STATUS	设备在线状态通知	3.3.2.2
VOICE_RESULT	音量调节结果通知	3.3.2.3
CLIENT_NEW_PRODUCT	新品审核结果回调	3.3.2.4
MERGE_PRODUCT	商品合并结果通知	3.3.2.5
ORC_RESULT	AI识别结果通知	3.3.2.6

签名验证：

将所有参数（除sign外）按字典序排序
拼接成 key1=value1&key2=value2 格式
末尾拼接 AppSecret
进行MD5加密得到签名值

幂等性要求：

商户需要实现幂等性处理，避免重复通知导致重复业务处理
建议通过 activity_id 或 device_id + create_time 进行幂等性校验

重要提示：

ORC_RESULT(识别结果通知)是最重要的回调，包含用户购买的商品信息
商户应根据识别结果进行扣款操作
当 nobuy=1 时表示用户没有消费，不需要扣款
当识别结果中 excepts 包含值时，建议人工审核

5.2 识别或订单回调结果查询

简要描述：查询哈哈平台是否成功推送识别结果或订单通知给商户。

请求URL：http://api.hahabianli.com/order/callbackStatus

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
order_no	是	string	哈哈平台订单号

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "callback_status": 1,
    "callback_time": "2024-01-24 15:30:00",
    "retry_count": 0
  }
}

返回参数说明：

参数名	类型	说明
callback_status	int	回调状态：0-未推送，1-推送成功，2-推送失败
callback_time	string	回调时间
retry_count	int	重试次数

5.4 识别结果查询

简要描述：主动查询订单的AI识别结果。

请求URL：http://api.hahabianli.com/order/recognizeResult

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
order_no	否	string	哈哈平台订单号
out_trade_no	否	string	商户订单号

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "order_no": "HH202401240001",
    "out_trade_no": "M202401240001",
    "goods_list": [
      {
        "goods_id": "goods001",
        "goods_name": "可口可乐",
        "price": 3.50,
        "quantity": 2,
        "amount": 7.00
      }
    ],
    "total_amount": 7.00,
    "confidence": 0.95,
    "video_url": "http://example.com/video/123.mp4",
    "status": "completed"
  }
}

5.5 订单查询

简要描述：查询订单详细信息。

请求URL：http://api.hahabianli.com/order/query

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
order_no	否	string	哈哈平台订单号
out_trade_no	否	string	商户订单号

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "order_no": "HH202401240001",
    "out_trade_no": "M202401240001",
    "device_id": "device001",
    "goods_list": [],
    "total_amount": 7.00,
    "order_status": "paid",
    "create_time": "2024-01-24 15:00:00",
    "pay_time": "2024-01-24 15:05:00"
  }
}

5.6 设置订单支付状态

简要描述：商户完成扣款后，通知哈哈平台订单支付状态。

请求URL：http://api.hahabianli.com/order/setPayStatus

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
order_no	是	string	哈哈平台订单号
pay_status	是	int	支付状态：1-支付成功，2-支付失败
pay_time	否	string	支付时间
transaction_id	否	string	第三方支付流水号

返回示例：

{
  "code": 1,
  "info": "设置成功"
}

5.7 开门前后图片或视频查询

简要描述：获取订单关联的开门前后对比图片或购物视频。

请求URL：http://api.hahabianli.com/order/media

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
order_no	是	string	哈哈平台订单号

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "before_image": "http://example.com/before.jpg",
    "after_image": "http://example.com/after.jpg",
    "video_url": "http://example.com/video.mp4"
  }
}

返回参数说明：

参数名	类型	说明
before_image	string	开门前图片URL
after_image	string	关门后图片URL
video_url	string	购物过程视频URL

5.8 静态柜分层图片与识别结果

简要描述：获取静态货柜的分层图片和每层的识别结果（适用于静态识别柜）。

请求URL：http://api.hahabianli.com/order/layerRecognize

请求方式：POST

请求参数：

参数名	必选	类型	说明
access_token	是	string	访问token
order_no	是	string	哈哈平台订单号

返回示例：

{
  "code": 1,
  "info": "SUCCESS",
  "data": {
    "layers": [
      {
        "layer_no": 1,
        "before_image": "http://example.com/layer1_before.jpg",
        "after_image": "http://example.com/layer1_after.jpg",
        "goods_list": [
          {
            "goods_id": "goods001",
            "goods_name": "可口可乐",
            "change_quantity": -2
          }
        ]
      }
    ]
  }
}

返回参数说明：

参数名	类型	说明
layer_no	int	层级编号
before_image	string	开门前该层图片
after_image	string	关门后该层图片
change_quantity	int	商品数量变化（负数表示减少）

附录

A. 完整接口清单

1. 接口规则（4个）

2.1 协议规则
2.2 签名规则
2.3 登陆获取 access_token
2.4 全局错误码

2. 设备接口（9个）

3.1 设备列表
3.2 设备是否多门单开
3.3.1 开门
3.3.2 开关门结果通知
3.3.3 刷卡开门验证
3.4 设备在线状态
3.5 设备音量调节
3.6 设备和锁的状态

3. 商品接口（10个）

4.1 设备可售卖商品列表
4.2 商品总库
4.3 添加商品至商家商品库
4.4 商家商品库
4.5 商品上下架
4.5.1 获取设备层模板
4.5.2 创建更新层模板接口
4.6 新品申请
4.7 商品编号对应关系
4.8 商品合并

4. 订单接口（8个）

5.1 识别结果通知
5.2 订单信息通知
5.3 识别或订单回调结果查询
5.4 识别结果查询
5.5 订单查询
5.6 设置订单支付状态
5.7 开门前后图片或视频查询
5.8 静态柜分层图片与识别结果

B. 常见问题

Q1: access_token多久过期？ A: access_token有效期为15天（1296000秒）。token到期前2天内请求接口会自动生成新的access_token，其它时间请求接口将不会更新token。建议获取到token后自行保存，发现过期或在token到期前的2天内就对token进行更新。

Q2: 如何处理识别结果通知？ A: 商户应在收到识别结果通知后，根据商品列表和金额进行用户扣款，并调用"设置订单支付状态"接口告知哈哈平台支付结果。

Q3: 识别置信度低于0.8怎么办？ A: 建议进行人工审核，可通过"开门前后图片或视频查询"接口获取购物视频进行核实。

Q4: 回调接口没有收到通知？ A: 可通过"识别或订单回调结果查询"接口查询推送状态。如果推送失败，可主动调用"识别结果查询"接口获取数据。

Q5: 多门柜如何开门？ A: 先调用"设备是否多门单开"接口判断设备类型，如果是多门单开设备，在调用开门接口时需传递door_index参数指定门编号。

版本历史

版本	日期	变更内容
1.0.0	2024-01-24	初始版本，包含完整API文档

文档来源：https://showdoc.hahabianli.com/web/#/685869388/275897889 最后更新：2024-01-24

哈哈零售API详细文档.md 36 KB Historique Raw

哈哈零售API详细文档

序言

概述

重要说明

1. 接入前说明

1.1 阅读对象

1.2 接入步骤

步骤1：联系哈哈运营人员开通API功能

步骤2：在商家后台配置回调地址

1.3 系统交互图

2. 接口规则

2.1 协议规则

2.2 签名规则

2.3 登陆获取 access_token

2.4 全局错误码

3. 设备接口

3.1 设备列表

3.2 设备是否多门单开

3.3 设备开门

3.3.1 开门

3.3.2 消息回调通知

3.3.2.1 开关门结果通知 (notify_type=DEVICE_STATUS)

3.3.2.2 设备在线状态通知 (notify_type=ONLINE_STATUS)

3.3.2.3 设备音量调节结果通知 (notify_type=VOICE_RESULT)

3.3.2.4 新品审核结果回调 (notify_type=CLIENT_NEW_PRODUCT)

3.3.2.5 商品合并结果通知 (notify_type=MERGE_PRODUCT)

3.3.2.6 识别结果通知 (notify_type=ORC_RESULT)

3.3.3 刷卡开门验证

3.4 设备在线状态

3.5 设备音量调节

3.6 设备和锁的状态

4. 商品接口

4.1 设备可售卖商品列表

4.2 商品总库

4.3 添加商品至商家商品库

4.4 商家商品库

4.5 商品上下架

4.5.1 获取设备层模板

4.5.2 创建更新层模板接口

4.6 新品申请

4.7 商品编号对应关系

4.8 商品合并

5. 订单接口

5.1 回调通知说明

5.2 识别或订单回调结果查询

5.4 识别结果查询

5.5 订单查询

5.6 设置订单支付状态

5.7 开门前后图片或视频查询

5.8 静态柜分层图片与识别结果

附录

A. 完整接口清单

1. 接口规则（4个）

2. 设备接口（9个）

3. 商品接口（10个）

4. 订单接口（8个）

B. 常见问题

版本历史

哈哈零售API详细文档.md 36 KB

Historique Raw