2024年7月8日发(作者：濯浩岚)
美团券验证平台接入文档
1 接入步骤
2 验证流程
3 接口设计
3.0 说明
3.0.1 sign计算方法：
3.0.2 测试用的app_key,sign_key和美团券密码：
3.1 M1接口：查询美团券信息
接口地址：
请求方式：
输入参数：
返回结果：
错误码：
调用示例：
3.2 M2接口：消费美团券
接口地址：
请求方式：
输入参数：
返回结果：
错误码：
调用示例：
3.3 M3接口：冲正美团券状态
接口地址：
请求方式：
输入参数：
返回结果：
调用示例：
4 Q&A
1 接入步骤
第一步：申请接入，美团创建接入第三方实体，同时给第三方分配接入凭证(app_key,sign_key)
第二步：第三方进行系统开发测试，实现美团的验证接口
第三步：合作项目上线前，第三方提交一份门店id和名字的列表，由美团配置一份两边poiid的对应表
列表格式：
第三方门店id
12345
美团维护的poiid对应表格式：
系统接入方
XXX
后续维护：
系统使用期间，如第三方有门店更改、添加，需提交申请给指定美团联系人。
美团门店id
12345
第三方门店id
12345
第三方门店名
海底捞（朝阳门店）
门店所属城市
北京
门店所属区域
东城区
第三方门店名
海底捞（朝阳门店）
门店所属城市
北京
门店所属区域
东城区
2 验证流程
3 接口设计
3.0 说明
3.0.1 sign计算方法：
首先将通知过来的所有参数，除去sign本身，以及值是空的参数，按参数名字母升序排序，然后按参数1值1参数2值2…参数n值n的方式进行连接，
得到一个字符串
然后在连接后得到的字符串前面加上通知验证密钥(sign_key, 不同于app_key)，然后计算sha1值，转成小写
比如请求的参数为：
sign=9987e6395c239a48ac7f0d185c525ee965e591a7&verifycode=4&app_key=ca2bf41f1910a9c359370ebf87caeafd&p
oiid=12345×tamp=1384333143&poiname= 海底捞(朝阳店)&v=1
去掉sign参数，其余的按参数名升序排列：app_keyca2bf41f1910a9c359370ebf87caeafdpoiid12345poiname海底捞(朝阳店)timestamp1384
333143v1verifycode4
假设sign_key为21be83530509abc81aa945a02bec37601cf3cc21，我们把sign_key放在上面的字符串的前面：21be83530509abc81aa945a02
bec37601cf3cc21app_keyca2bf41f1910a9c359370ebf87caeafdpoiid12345poiname海底捞(朝阳店)timestamp1384333143v1verifycode12
3412341234
计算sha1()结果为：9987e6395c239a48ac7f0d185c525ee965e591a7
注意：本文中所有对应的参数名和值都请使用utf-8编码格式
3.0.2 测试用的app_key,sign_key和美团券密码：
app_key:
ca2bf41f1910a9c359370ebf87caeafd
sign_key:
21be83530509abc81aa945a02bec37601cf3cc21
poiid:
12345
美团券密码：
verifycode
4
2
2
2
222244441111
其他
状态
可使用
已消费
已退款
已过期
已冻结
密码错误
3.1 M1接口：查询美团券信息
接口地址：
/api/ecouponinfo
请求方式：
HTTP GET
输入参数：
字段
verifycode
app_key
poiid
poiname
posid
timestamp
sign
v
必填
是
是
是
否
否
是
是
是
字段类型
string
string
string
string
string
int
string
string
示例值
ca2bf41f1910a9c35937
0ebf87caeafd
1234
北京-海底捞（朝阳门店）
k
1384333143
1b759da18a739e1e
1.0
字段说明
美团券密码，12位数字
美团分配的接入token
码商内部的门店id
门店名称
验证美团券的pos机id
时间戳
api输入参数签名结果
版本号
返回结果：
字段
err_code
err_str
verifycode
coupon_status
必填
是
是
是
是
字段类型
int
string
string
int
示例值
0
查询成功
1
默认值
-1
字段说明
0 : 查询成功，1xxx:
查询失败
错误描述
输入的美团券密码
美团券状态:
0：该美团券可使用
1：该美团券已消费
过，不能使用
2：该美团券已退款
，不能使用
3：该美团券已过期
，不能使用
4：该美团券已冻结
，不能使用
status_str
dealid
goodsname
price
value
endtime
是
是
是
是
是
是
string
int
string
string
string
string
该美团券已消费过，
不能使用
12345
西贝西北菜代金券1
张
70
100
2013-12-12
59:59:59
-1
美团券状态描述
美团券所属项目id
商品描述
购买价格
实际价格
美团券使用有效期截
止时间
usetime
poiname
是
是
string
string
2013-08-12
59:59:59
北京-海底捞（朝阳
门店）
美团券消费日期，st
atus为1时有值
美团券消费门店，st
atus为1时有值
错误码：
err_code
0
1001
1002
1003
1004
1005
1105
err_str
查询成功
参数错误
签名错误
appkey错误
门店未注册
没有找到该美团券
同1005，没有找到改美团券
调用示例：
请求：
curl
'/api/ecouponinfo?sign=9987e6395c239a48ac7f0d185c525ee965e591a7&verifycode=1
23412341234&app_key=ca2bf41f1910a9c359370ebf87caeafd&poiid=12345×tamp=1384333143&poi
name=%E6%B5%B7%E5%BA%95%E6%8D%9E(%E6%9C%9D%E9%98%B3%E5%BA%97)&v=1'
返回：
{
"err_code": 0,
"err_str": "查询成功",
"verifycode": "4",
"coupon_status": 0,
"status_str": "该美团券可使用",
"dealid": 1234,
"goodsname": "测试商品信息",
"price": "119.9",
"value": "120.0",
"endtime": "2014-12-12 59:59:59",
"usetime": "",
"poiname": ""
}
3.2 M2接口：消费美团券
接口地址：
/api/ecouponverify
请求方式：
HTTP GET
输入参数：
字段
verifycode
app_key
poiid
poiname
posid
timestamp
sqnum
sign
v
必填
是
是
是
否
否
是
是
是
是
字段类型
string
string
string
string
string
int
string
string
string
示例值
ca2bf41f1910a9c35937
0ebf87caeafd
1234
北京-海底捞（朝阳门店）
k
1384333143
23131313133
1b759da18a739e1e
1.0
字段说明
美团券密码，12位数字
美团分配的接入token
码商内部的门店id
门店名称
验证美团券的pos机id
时间戳
请求序列号，如有冲正流
程，可以此作为冲正凭证
api输入参数签名结果
版本号
返回结果：
字段
err_code
err_str
verifycode
dealid
goodsname
price
value
endtime
必填
是
是
是
是
是
是
是
是
字段类型
int
string
string
int
string
string
string
string
示例值
0
消费成功
12345
西贝西北菜代金券1
张
70
100
2013-12-12
59:59:59
默认值
字段说明
0 : 消费成功，1xxx :
消费失败
错误描述
输入的美团券密码
美团券所属项目id
商品描述
购买价格
实际价格
美团券使用有效期截
止时
usetime
poiname
print_tpl
是
是
是
string
string
sting
2013-08-12
59:59:59
海底捞（朝阳门店）
消费时间
消费门店
小票打印内容
错误码：
err_code
0
1001
1002
1003
1004
1005
1006
1007
1008
1009
err_str
消费成功
参数错误
签名错误
appkey错误
门店未注册
没有找到该美团券
该美团券已消费过，不能使用
该美团券已退款，不能使用
该美团券已过期，不能使用
该美团券已被冻结，不能使用
调用示例：
请求：
curl
'/api/ecouponverify?sqnum=1234&posid=&verifycode=4&app_key=ca2
bf41f1910a9c359370ebf87caeafd&v=1&sign=c64bd8a21d35ab8cbd05c6d9008ff2e88ad344ab&poiid=1234
5&poiname=%E6%B5%B7%E5%BA%95%E6%8D%9E%28%E6%9C%9D%E9%98%B3%E5%BA%97%29×
tamp=1419397555'
返回：
{
"err_code": 0,
"err_str": "消费成功",
"verifycode": "4",
"dealid": 1234,
"goodsname": "测试商品信息",
"price": "119.9",
"value": "120.0",
"endtime": "2015-01-30 59:59:59",
"usetime": "",
"poiname": ""
}
3.3 M3接口：冲正美团券状态
接口地址：
/api/ecouponverifycancel
请求方式：
HTTP GET
输入参数：
字段
verifycode
app_key
poiid
timestamp
consume_sqnum
sign
v
必填
是
是
是
是
是
是
是
字段类型
string
string
string
int
string
string
string
示例值
ca2bf41f1910a9c35937
0ebf87caeafd
1234
1384333143
23131313133
1b759da18a739e1e
1.0
字段说明
美团券密码，12位数字
美团分配的接入token
码商内部的门店id
时间戳
与对应的核销请求保持一
致，否则校验不通过
api输入参数签名结果
版本号
返回结果：
字段
err_code
err_str
verifycode
必填
是
是
是
字段类型
int
string
string
示例值
0
冲正成功
默认值
字段说明
0 : 冲正成功，1xxx :
冲正失败
错误描述
输入的美团券密码
调用示例：
请求：
curl
'/api/ecouponverifycancel?posid=&verifycode=4&consume_sqnum=123
4&app_key=ca2bf41f1910a9c359370ebf87caeafd&v=1&sign=3daa0e20073da2e59f27b26f2fc8b875048de2
da&poiid=12345×tamp=1419397555'
返回：
{
"err_code": "0",
"err_str": "冲正成功",
"verifycode": "4"
}
4 Q&A
Q: 为什么验证了美团券4，但是下次还是可以验证？
A:
使用测试的appkey和signkey进行验证时，实际上是不会写数据库的，只是按固定的格式返回数据，方便您的测试。测试通过后可以联系美团的技
术人员申请正式的appkey,需要提供如下的信息：公司名称，对接的技术负责人及联系方式，对接的商务联系人及联系方式。
Q: 美团是否能够提供sdk，方便商家的开发？
A：美团提供三种语言的sdk(python, php, java)，商家可以通过调取相应的函数来完成验证等流程。
Q: 如果是C语言写的POS机代码，有什么需要注意的么？
A：商家如果是自己写的http client,请务必支持HTTP/1.1， 注意Content-length可能没有具体的数值，可能是chunked。
Q: 如果提示“门店未注册”，该如何处理？
A: 请找美团的工作人员添加门店，提供如下的信息：该门店在美团页面上的链接，该门店在贵方系统中的id, 门店名称，门店城市，门店地址。
2024年7月8日发(作者：濯浩岚)
美团券验证平台接入文档
1 接入步骤
2 验证流程
3 接口设计
3.0 说明
3.0.1 sign计算方法：
3.0.2 测试用的app_key,sign_key和美团券密码：
3.1 M1接口：查询美团券信息
接口地址：
请求方式：
输入参数：
返回结果：
错误码：
调用示例：
3.2 M2接口：消费美团券
接口地址：
请求方式：
输入参数：
返回结果：
错误码：
调用示例：
3.3 M3接口：冲正美团券状态
接口地址：
请求方式：
输入参数：
返回结果：
调用示例：
4 Q&A
1 接入步骤
第一步：申请接入，美团创建接入第三方实体，同时给第三方分配接入凭证(app_key,sign_key)
第二步：第三方进行系统开发测试，实现美团的验证接口
第三步：合作项目上线前，第三方提交一份门店id和名字的列表，由美团配置一份两边poiid的对应表
列表格式：
第三方门店id
12345
美团维护的poiid对应表格式：
系统接入方
XXX
后续维护：
系统使用期间，如第三方有门店更改、添加，需提交申请给指定美团联系人。
美团门店id
12345
第三方门店id
12345
第三方门店名
海底捞（朝阳门店）
门店所属城市
北京
门店所属区域
东城区
第三方门店名
海底捞（朝阳门店）
门店所属城市
北京
门店所属区域
东城区
2 验证流程
3 接口设计
3.0 说明
3.0.1 sign计算方法：
首先将通知过来的所有参数，除去sign本身，以及值是空的参数，按参数名字母升序排序，然后按参数1值1参数2值2…参数n值n的方式进行连接，
得到一个字符串
然后在连接后得到的字符串前面加上通知验证密钥(sign_key, 不同于app_key)，然后计算sha1值，转成小写
比如请求的参数为：
sign=9987e6395c239a48ac7f0d185c525ee965e591a7&verifycode=4&app_key=ca2bf41f1910a9c359370ebf87caeafd&p
oiid=12345×tamp=1384333143&poiname= 海底捞(朝阳店)&v=1
去掉sign参数，其余的按参数名升序排列：app_keyca2bf41f1910a9c359370ebf87caeafdpoiid12345poiname海底捞(朝阳店)timestamp1384
333143v1verifycode4
假设sign_key为21be83530509abc81aa945a02bec37601cf3cc21，我们把sign_key放在上面的字符串的前面：21be83530509abc81aa945a02
bec37601cf3cc21app_keyca2bf41f1910a9c359370ebf87caeafdpoiid12345poiname海底捞(朝阳店)timestamp1384333143v1verifycode12
3412341234
计算sha1()结果为：9987e6395c239a48ac7f0d185c525ee965e591a7
注意：本文中所有对应的参数名和值都请使用utf-8编码格式
3.0.2 测试用的app_key,sign_key和美团券密码：
app_key:
ca2bf41f1910a9c359370ebf87caeafd
sign_key:
21be83530509abc81aa945a02bec37601cf3cc21
poiid:
12345
美团券密码：
verifycode
4
2
2
2
222244441111
其他
状态
可使用
已消费
已退款
已过期
已冻结
密码错误
3.1 M1接口：查询美团券信息
接口地址：
/api/ecouponinfo
请求方式：
HTTP GET
输入参数：
字段
verifycode
app_key
poiid
poiname
posid
timestamp
sign
v
必填
是
是
是
否
否
是
是
是
字段类型
string
string
string
string
string
int
string
string
示例值
ca2bf41f1910a9c35937
0ebf87caeafd
1234
北京-海底捞（朝阳门店）
k
1384333143
1b759da18a739e1e
1.0
字段说明
美团券密码，12位数字
美团分配的接入token
码商内部的门店id
门店名称
验证美团券的pos机id
时间戳
api输入参数签名结果
版本号
返回结果：
字段
err_code
err_str
verifycode
coupon_status
必填
是
是
是
是
字段类型
int
string
string
int
示例值
0
查询成功
1
默认值
-1
字段说明
0 : 查询成功，1xxx:
查询失败
错误描述
输入的美团券密码
美团券状态:
0：该美团券可使用
1：该美团券已消费
过，不能使用
2：该美团券已退款
，不能使用
3：该美团券已过期
，不能使用
4：该美团券已冻结
，不能使用
status_str
dealid
goodsname
price
value
endtime
是
是
是
是
是
是
string
int
string
string
string
string
该美团券已消费过，
不能使用
12345
西贝西北菜代金券1
张
70
100
2013-12-12
59:59:59
-1
美团券状态描述
美团券所属项目id
商品描述
购买价格
实际价格
美团券使用有效期截
止时间
usetime
poiname
是
是
string
string
2013-08-12
59:59:59
北京-海底捞（朝阳
门店）
美团券消费日期，st
atus为1时有值
美团券消费门店，st
atus为1时有值
错误码：
err_code
0
1001
1002
1003
1004
1005
1105
err_str
查询成功
参数错误
签名错误
appkey错误
门店未注册
没有找到该美团券
同1005，没有找到改美团券
调用示例：
请求：
curl
'/api/ecouponinfo?sign=9987e6395c239a48ac7f0d185c525ee965e591a7&verifycode=1
23412341234&app_key=ca2bf41f1910a9c359370ebf87caeafd&poiid=12345×tamp=1384333143&poi
name=%E6%B5%B7%E5%BA%95%E6%8D%9E(%E6%9C%9D%E9%98%B3%E5%BA%97)&v=1'
返回：
{
"err_code": 0,
"err_str": "查询成功",
"verifycode": "4",
"coupon_status": 0,
"status_str": "该美团券可使用",
"dealid": 1234,
"goodsname": "测试商品信息",
"price": "119.9",
"value": "120.0",
"endtime": "2014-12-12 59:59:59",
"usetime": "",
"poiname": ""
}
3.2 M2接口：消费美团券
接口地址：
/api/ecouponverify
请求方式：
HTTP GET
输入参数：
字段
verifycode
app_key
poiid
poiname
posid
timestamp
sqnum
sign
v
必填
是
是
是
否
否
是
是
是
是
字段类型
string
string
string
string
string
int
string
string
string
示例值
ca2bf41f1910a9c35937
0ebf87caeafd
1234
北京-海底捞（朝阳门店）
k
1384333143
23131313133
1b759da18a739e1e
1.0
字段说明
美团券密码，12位数字
美团分配的接入token
码商内部的门店id
门店名称
验证美团券的pos机id
时间戳
请求序列号，如有冲正流
程，可以此作为冲正凭证
api输入参数签名结果
版本号
返回结果：
字段
err_code
err_str
verifycode
dealid
goodsname
price
value
endtime
必填
是
是
是
是
是
是
是
是
字段类型
int
string
string
int
string
string
string
string
示例值
0
消费成功
12345
西贝西北菜代金券1
张
70
100
2013-12-12
59:59:59
默认值
字段说明
0 : 消费成功，1xxx :
消费失败
错误描述
输入的美团券密码
美团券所属项目id
商品描述
购买价格
实际价格
美团券使用有效期截
止时
usetime
poiname
print_tpl
是
是
是
string
string
sting
2013-08-12
59:59:59
海底捞（朝阳门店）
消费时间
消费门店
小票打印内容
错误码：
err_code
0
1001
1002
1003
1004
1005
1006
1007
1008
1009
err_str
消费成功
参数错误
签名错误
appkey错误
门店未注册
没有找到该美团券
该美团券已消费过，不能使用
该美团券已退款，不能使用
该美团券已过期，不能使用
该美团券已被冻结，不能使用
调用示例：
请求：
curl
'/api/ecouponverify?sqnum=1234&posid=&verifycode=4&app_key=ca2
bf41f1910a9c359370ebf87caeafd&v=1&sign=c64bd8a21d35ab8cbd05c6d9008ff2e88ad344ab&poiid=1234
5&poiname=%E6%B5%B7%E5%BA%95%E6%8D%9E%28%E6%9C%9D%E9%98%B3%E5%BA%97%29×
tamp=1419397555'
返回：
{
"err_code": 0,
"err_str": "消费成功",
"verifycode": "4",
"dealid": 1234,
"goodsname": "测试商品信息",
"price": "119.9",
"value": "120.0",
"endtime": "2015-01-30 59:59:59",
"usetime": "",
"poiname": ""
}
3.3 M3接口：冲正美团券状态
接口地址：
/api/ecouponverifycancel
请求方式：
HTTP GET
输入参数：
字段
verifycode
app_key
poiid
timestamp
consume_sqnum
sign
v
必填
是
是
是
是
是
是
是
字段类型
string
string
string
int
string
string
string
示例值
ca2bf41f1910a9c35937
0ebf87caeafd
1234
1384333143
23131313133
1b759da18a739e1e
1.0
字段说明
美团券密码，12位数字
美团分配的接入token
码商内部的门店id
时间戳
与对应的核销请求保持一
致，否则校验不通过
api输入参数签名结果
版本号
返回结果：
字段
err_code
err_str
verifycode
必填
是
是
是
字段类型
int
string
string
示例值
0
冲正成功
默认值
字段说明
0 : 冲正成功，1xxx :
冲正失败
错误描述
输入的美团券密码
调用示例：
请求：
curl
'/api/ecouponverifycancel?posid=&verifycode=4&consume_sqnum=123
4&app_key=ca2bf41f1910a9c359370ebf87caeafd&v=1&sign=3daa0e20073da2e59f27b26f2fc8b875048de2
da&poiid=12345×tamp=1419397555'
返回：
{
"err_code": "0",
"err_str": "冲正成功",
"verifycode": "4"
}
4 Q&A
Q: 为什么验证了美团券4，但是下次还是可以验证？
A:
使用测试的appkey和signkey进行验证时，实际上是不会写数据库的，只是按固定的格式返回数据，方便您的测试。测试通过后可以联系美团的技
术人员申请正式的appkey,需要提供如下的信息：公司名称，对接的技术负责人及联系方式，对接的商务联系人及联系方式。
Q: 美团是否能够提供sdk，方便商家的开发？
A：美团提供三种语言的sdk(python, php, java)，商家可以通过调取相应的函数来完成验证等流程。
Q: 如果是C语言写的POS机代码，有什么需要注意的么？
A：商家如果是自己写的http client,请务必支持HTTP/1.1， 注意Content-length可能没有具体的数值，可能是chunked。
Q: 如果提示“门店未注册”，该如何处理？
A: 请找美团的工作人员添加门店，提供如下的信息：该门店在美团页面上的链接，该门店在贵方系统中的id, 门店名称，门店城市，门店地址。