微信门店接口
更新日志:
目录
微信门店接口文档
1. 接口简介
2. 开发者必读
2.1 申请接入
2.2 开发流程
3. 创建门店
3.1 上传图片
3.2 创建门店
3.3 审核事件推送
3.4 查询门店信息
3.5 查询门店列表
3.6 修改门店服务信息
3.7 删除门店
4. 门店类目表
5. 常见错误码
6. 联系我们
# 微信门店接口文档
# 1.接口简介
门店管理接口为商户提供门店批量导入、查询、修改、删除等主要功能,方便商户快速、高效进行门店管理和操作。
商户在使用门店管理接口时需注意以下几个问题:
门店poiid体系已做改造,poiid自创建后立刻分配,不再受审核影响发生变化。
为保证在审核通过后,获取到的poi_id 能与商户自身数据做对应,将会允许商户在创建时提交自己内部或自定义的sid(字符串格式,微信不会对唯一性进行校验,请商户自己保证),用于后续获取poi_id 后对数据进行对应;
门店的可用状态available_state,将标记门店相应审核状态,只有审核通过状态,才能进行更新,更新字段仅限扩展字段(表1 中前11 个字段);
扩展字段属于公共编辑信息,提交更新后将由微信进行审核采纳,但扩展字段更新并不影响门店的可用状态(即available_state 仍为审核通过),但update_status 状态变为1,更新中状态,此时不可再次对门店进行更新,直到微信审核采纳后;
在update_status 为1,更新中状态下的门店,此时调用getpoi 接口,获取到的扩展字段为更新的最新字段,但并不是最终结果,仍需等待微信编辑对扩展字段的建议进行采纳后,最终决定是否生效(有可能更新字段不被采纳);
门店页面示例
# 2.开发者必读
# 2.1申请接入
拥有已认证的服务号可申请开通门店管理功能。
认证的订阅号拥有卡券、WI-FI、摇一摇、广告主等功能后会自动开通门店管理功能。
申请路径如下登录微信公众平台—添加功能插件—选择门店功能。
# 2.2开发流程
获取接口权限后,商户开发者需按照以下步骤开发和调试,请开发者务必仔细阅读以下流程!
1、创建门店前的准备
上传图片:上传商户新建门店时所使用的图片。上传的图片url必须为微信自己域名的url。
2.创建门店
调用创建门店接口,调用成功后返回errcode、errmsg,会返回最终poiid。
3.审核结果事件推送
新创建的门店在审核通过后,会以事件形式推送给商户填写的回调url(登录公众平台进入“开发者中心”设置)获取门店唯一id:poi_id。
4.查询门店信息
在审核通过并获取poi_id 后,商户可以利用poi_id,查询具体某条门店的信息。
5.查询门店列表
商户可以通过该接口,批量查询自己名下的门店list,并获取已审核通过的poi_id以及商户自身用于对应、商户名、分店名、地址字段的sid
6.修改门店服务信息
商户可以通过该接口,修改门店的服务信息,包括:图片列表、营业时间、推荐、特色服务、简介、人均价格、电话7 个字段(名称、坐标、地址等不可修改)修改后需要人工审核。
7.删除门店
商户可以通过该接口,删除已经成功创建的门店。
注意:所有API接口POST的数据只支持UTF-8编码,否则会返回报错。
# 3.创建门店
# 3.1上传图片
接口说明
用POI 接口新建门店时所使用的图片url 必须为微信域名的url,因此需要先用上传图片接口上传图片并获取url,再创建门店。
上传的图片限制文件大小限制1MB,支持JPG 格式。
接口调用请求说明
请求参数说明
返回数据说明
返回成功示例:
{
"url":"http://mmbiz.qpic.cn/XXXXX"
}
插入失败示例(errcode 不为0,errmsg 为相应错误信息):
{
"errcode":40001,
"errmsg":"invalid credential"
}
# 3.2创建门店
接口说明
创建门店接口是为商户提供创建自己门店数据的接口,门店数据字段越完整,商户页面展示越丰富,越能够吸引更多用户,并提高曝光度。
创建门店接口调用成功后会返回errcode 0、errmsg ok,会实时返回唯一的poiid。
接口调用请求说明
请求参数说明
POST数据示例
字段视图:
json 数据示例
{"business":{
"base_info":{
"sid":"33788392",
"business_name":"15个汉字或30个英文字符内",
"branch_name":"不超过10个字,不能含有括号和特殊字符",
"province":"不超过10个字",
"city":"不超过30个字",
"district":"不超过10个字",
"address":"门店所在的详细街道地址(不要填写省市信息):不超过80个字",
"telephone":"不超53个字符(不可以出现文字)",
"categories":["美食,小吃快餐"],
"offset_type":1,
"longitude":115.32375,
"latitude":25.097486,
"photo_list":[{"photo_url":"https:// 不超过20张.com"},{"photo_url":"https://XXX.com"}],
"recommend":"不超过200字。麦辣鸡腿堡套餐,麦乐鸡,全家桶",
"special":"不超过200字。免费wifi,外卖服务",
"introduction":"不超过300字。麦当劳是全球大型跨国连锁餐厅,1940 年创立于美国,在世界上大约拥有3 万间分店。
主要售卖汉堡包,以及薯条、炸鸡、汽水、冰品、沙拉、 水果等快餐食品",
"open_time":"8:00-20:00",
"avg_price":35
}
}
}
门店基础信息字段(重要)
门店服务信息字段
返回数据
返回成功示例:
{
"errcode":0,
"errmsg":"ok"
"poi_id":460123456
}
插入失败示例(errcode 不为0,errmsg 为相应错误信息):
{
"errcode":40001,
"errmsg":"invalid credential"
}
常见出错字段规范
1)门店名称
门店名:不能为空,15个汉字或30个英文字符内,不能含有括号和特殊字符,仅为商户(品牌)名称,如海底捞,苏宁电器,华景国旅,茂业百货;不应包含地区、地址、分店名等信息。错误及正确示例见下。
分店名:不超过20个字,不能含有括号和特殊字符,用于在同一商户(品牌)有多家分店时区分不同门店,如国贸店,春熙路店,万象城店;不应包含地区信息,不应与门店名有重复。错误及正确示例见下。
错误示例1:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 广州东兴堂大药房连锁有限公司永新分店 ",
"branch_name":"",
出错原因:把分店名写在了门店名中;包含了地区信息;包含了“连锁有限公司”字样
正确示例:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 东兴堂大药房 ",
"branch_name":" 永新分店 ",
错误示例2:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 山西国美 ",
"branch_name":" 太原长治路店 ",
出错原因:包含了地区信息
正确示例:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 国美 ",
"branch_name":" 长治路店 ",
错误示例3:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 屈臣氏(北京路店) ",
"branch_name":""
出错原因:包含了括号;分店名写在了门店名中
正确示例:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 屈臣氏 ",
"branch_name":" 北京路店 ",
错误示例4:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 黄记煌 ",
"branch_name":" 黄记煌成都春熙路店 ",
出错原因:门店名和分店名重复
正确示例:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 黄记煌 ",
"branch_name":" 春熙路店 ",
错误示例5:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 丽影广场 ",
"branch_name":" 麦当劳 ",
出错原因:理解有误,将门店名和分店名填反
正确示例:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":" 麦当劳 ",
"branch_name":" 丽影广场店 ",
注意:最终门店名和分店名将以“business_name(branch_name)”的形式拼合显示,请在填写时考虑展示效果(其中括号为统一自动添加,请不要自行添加);不同字段搜索和存储规则不同,请严格按照规范填写门店信息,以保证用户顺利搜索、找到您的门店;随后填写的地址信息中将包含区域信息,一同展示给用户,不必在名称中重复填写地区信息。
2)详细地址
准确填写门店所在地址和门牌号,务必至少包括“XX路XX号”这一基本信息;因为无法检索和定位,请不要只填写“XX楼下”、“XX左侧100米”、“XX商厦首层”、“XX地铁站D出口向北100米”这类的信息,如要保留,请先保证门牌号准确填写。
请不要在“详细地址”字段中重复填写省市区信息,直辖市除外(province、city均要填写)
错误示例:
"province":"浙江省",
"city":"杭州市",
"district":"下城区",
"address":" 杭州市下城区 庆春路86号世纪联华超市5楼", |
出错原因:在详细地址中重复填写了省市区信息,造成拼合后重复显示。错误展示效果:浙江省杭州市下城区杭州市下城区庆春路86号世纪联华超市5楼。
正确示例:
"province":"浙江省",
"city":"杭州市",
"district":"下城区",
"address":"庆春路86号世纪联华超市5楼",
正确展示效果:浙江省杭州市下城区庆春路86号世纪联华超市5楼。
直辖市信息填写示例:
"province":"上海市",
"city":"上海市",
"district":"徐汇区",
"address":"田林路397号中环国际广场A楼",
3)类目信息
商户按照类目列表选择实际门店对应的类目。
错误示例:
{"business":{
"base_info":{
"sid":"33788392",
"business_name":"麦当劳",
"branch_name":"艺苑路店",
"province":"广东省",
"city":"广州市",
"district":"海珠区",
"address":"艺苑路11 号",
"telephone":"020-12345678",
"categories":["美食,茶餐厅"],
出错原因:将麦当劳的类目信息写成“美食,茶餐厅”。
<a href="https://docs.google.com/spreadsheets/d/191n-uUJJFow_n1ySvPsLOpk88FJKXQuzSCKUe7vnjxQ/edit?usp=sharing "类目详情请参照“【附表】微信门店类目表" target="_blank">类目详情请参照“【附表】微信门店类目表”
4)电话
填写的电话信息需要真实有效,审核过程会进行电话抽审,无人接听或电话无效会影响审核结果。
只能含有数字和“-”字符;固定电话须填写区号;区号、分机号均用“-”连接;现阶段请不要填写多个电话。
错误示例1:
"telephone":"(010)87632851",
错误原因:区号未用“-”连接。
错误示例2:
"telephone":"34435764",
错误原因:固定电话未加区号。
错误示例3:
"telephone":"13880934557、0351-34435764",
错误原因:填写了多个电话。
错误示例4:
"telephone":"138-8093-4557",
错误原因:手机号码内部不应用“-”间隔。
错误示例5:
"telephone":"8003800转4010",
错误原因:分机号未用“-”连接。
错误示例6:
"telephone":"8003800#4010",
错误原因:分机号未用“-”连接
正确示例:
"telephone":"021-81445873",
"telephone":"021-81445873-1003",
"telephone":"13867428497",
"telephone":"4008002835",
5)经纬度:
可通过其他第三方平台获取已知地点经纬度坐标,通过选择offset_type字段类型对应上传相应经纬度。
也可利用以下工具找到各门店对应的经纬度坐标,导出相应坐标值。
详见链接:坐标拾取器地址。
http://lbs.qq.com/tool/getpoint/index.html
注意:经纬度坐标需要转换为腾讯地图坐标。
详见链接:
<a href="http://lbs.qq.com/webservice_v1/guide-convert.html "坐标转换地址"" target="_blank">http://lbs.qq.com/webservice_v1/guide-convert.html
# 3.3审核事件推送
新创建的门店在审核通过后,会以事件形式推送给商户填写的回调URL(登录公众平台进入“开发者中心”设置)
微信服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。 关于重试的消息排重,推荐使用FromUserName + CreateTime 排重。
假如服务器无法保证在五秒内处理并回复,可以直接回复空串,微信服务器不会对此作任何处理,并且不会发起重试。
推送XML数据包示例:
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[fromUser]]></FromUserName>
<CreateTime>1408622107</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[poi_check_notify]]></Event>
<UniqId><![CDATA[123adb]]></UniqId>
<PoiId><![CDATA[123123]]></PoiId>
<Result><![CDATA[fail]]></Result>
<msg><![CDATA[xxxxxx]]></msg>
</xml>
参数说明:
# 3.4查询门店信息
接口说明
创建门店后获取poi_id 后,商户可以利用poi_id,查询具体某条门店的信息。 若在查询时,update_status 字段为1,表明在5 个工作日内曾用update 接口修改过门店扩展字段,该扩展字段为最新的修改字段,尚未经过审核采纳,因此不是最终结果。最终结果会在5 个工作日内,最终确认是否采纳,并前端生效(但该扩展字段的采纳过程不影响门店的可用性,即available_state仍为审核通过状态)
注:修改扩展字段将会推送审核,但不会影响该门店的生效可用状态。
接口调用请求说明
请求参数说明
POST数据示例
{
"poi_id":"271262077"
}
返回数据说明
数据示例
{
"errcode":0,
"errmsg":"ok",
"business ":{
"base_info":{
"sid":"001",
"business_name":"麦当劳",
"branch_name":"艺苑路店",
"province":"广东省",
"city":"广州市",
"address":"海珠区艺苑路11 号",
"telephone":"020-12345678",
"categories":["美食,小吃快餐"],
"offset_type":1,
"longitude":115.32375,
"latitude":25.097486,
"photo_list":[{"photo_url":"https:// XXX.com"} , {"photo_url":"https://XXX.com"}],
"recommend":"麦辣鸡腿堡套餐,麦乐鸡,全家桶",
"special":"免费wifi,外卖服务",
"introduction":"麦当劳是全球大型跨国连锁餐厅,1940 年创立于美国,在世界上大
约拥有3 万间分店。主要售卖汉堡包,以及薯条、炸鸡、汽水、冰品、沙拉、水果等快餐食品",
"open_time":"8:00-20:00",
"avg_price":35
"available_state":3
"update_status":0
}
}
}
*注其他字段同前
# 3.5查询门店列表
接口说明
商户可以通过该接口,批量查询自己名下的门店list,并获取已审核通过的poiid、商户自身sid 用于对应、商户名、分店名、地址字段。
接口调用请求说明
请求参数说明
POST数据示例
{
"begin":0,
"limit":10
}
字段说明
返回数据说明
数据示例:
为审核通过,有poi_id,全部字段;第二条为审核不通过,仅有基础字段;第三条为审核中,仅有基础字段。
{
"errcode":0,
"errmsg":"ok"
"business_list":[
{"base_info":{
"sid":"101",
"business_name":"麦当劳",
"branch_name":"艺苑路店",
"address":"艺苑路11号",
"telephone":"020-12345678",
"categories":["美食,快餐小吃"],
"city":"广州市",
"province":"广东省",
"offset_type":1,
"longitude":115.32375,
"latitude":25.097486,
"photo_list":[{"photo_url":"http: ...."}],
"introduction":"麦当劳是全球大型跨国连锁餐厅,1940 年创立于美国,在世界上大约拥有3 万间分店。主要售卖汉堡包,以及薯条、炸鸡、汽水、冰品、沙拉、水果等快餐食品",
"recommend":"麦辣鸡腿堡套餐,麦乐鸡,全家桶",
"special":"免费wifi,外卖服务",
"open_time":"8:00-20:00",
"avg_price":35,
"poi_id":"285633617",
"available_state":3,
"district":"海珠区",
"update_status":0
}},
{"base_info":{
"sid":"101",
"business_name":"麦当劳",
"branch_name":"北京路店",
"address":"北京路12号",
"telephone":"020-12345689",
"categories":["美食,快餐小吃"],
"city":"广州市",
"province":"广东省",
"offset_type":1,
"longitude":115.3235,
"latitude":25.092386,
"photo_list":[{"photo_url":"http: ...."}],
"introduction":"麦当劳是全球大型跨国连锁餐厅,1940 年创立于美国,在世界上大约拥有3 万间分店。主要售卖汉堡包,以及薯条、炸鸡、汽水、冰品、沙拉、水果等快餐食品",
"recommend":"麦辣鸡腿堡套餐,麦乐鸡,全家桶",
"special":"免费wifi,外卖服务",
"open_time":"8:00-20:00",
"avg_price":35,
"poi_id":"285633618",
"available_state":4,
"district":"越秀区",
"update_status":0
}},
{"base_info":{
"sid":"101",
"business_name":"麦当劳",
"branch_name":"龙洞店",
"address":"迎龙路122号",
"telephone":"020-12345659",
"categories":["美食,快餐小吃"],
"city":"广州市",
"province":"广东省",
"offset_type":1,
"longitude":115.32345,
"latitude":25.056686,
"photo_list":[{"photo_url":"http: ...."}],
"introduction":"麦当劳是全球大型跨国连锁餐厅,1940 年创立于美国,在世界上大约拥有3 万间分店。主要售卖汉堡包,以及薯条、炸鸡、汽水、冰品、沙拉、水果等快餐食品",
"recommend":"麦辣鸡腿堡套餐,麦乐鸡,全家桶",
"special":"免费wifi,外卖服务",
"open_time":"8:00-20:00",
"avg_price":35,
"poi_id":"285633619",
"available_state":2,
"district":"天河区",
"update_status":0
}},
],
"total_count":"3",
}
# 3.6修改门店服务信息
接口说明
商户可以通过该接口,修改门店的服务信息,包括:sid、图片列表、营业时间、推荐、特色服务、简介、人均价格、电话8个字段(名称、坐标、地址等不可修改)修改后需要人工审核。
接口调用请求说明
请求参数说明
POST数据示例
{"business ":{
"base_info":{
"poi_id ":"271864249"
"sid":"A00001"
"telephone ":"020-12345678"
"photo_list":[{"photo_url":"https:// XXX.com"},{"photo_url":"https://XXX.com"}],
"recommend":"麦辣鸡腿堡套餐,麦乐鸡,全家桶",
"special":"免费wifi,外卖服务",
"introduction":"麦当劳是全球大型跨国连锁餐厅,1940 年创立于美国,在世界上大约拥有3 万间分店。主要售卖汉堡包,以及薯条、炸鸡、汽水、冰品、沙拉、水果等快餐食品",
"open_time":"8:00-20:00",
"avg_price":35
}
}
}
字段说明:
全部字段内容同前。
特别注意:
以上8个字段,若有填写内容则为覆盖更新,若无内容则视为不修改,维持原有内容。 photo_list 字段为全列表覆盖,若需要增加图片,需将之前图片同样放入list 中,在其后增加新增图片。如:已有A、B、C 三张图片,又要增加D、E 两张图,则需要调用该接口,photo_list 传入A、B、C、D、E 五张图片的链接。
返回数据说明
数据示例:
{
"errcode":0,
"errmsg":"ok"
}
# 3.7删除门店
接口说明
商户可以通过该接口,删除已经成功创建的门店。请商户慎重调用该接口。
接口调用请求说明
请求参数说明
POST数据示例
{
"poi_id": "271262077"
}
字段说明:
返回数据说明
数据示例:
{
"errcode":0,
"errmsg":"ok"
}
# 4.门店类目表
接口说明
类目名称接口是为商户提供自己门店类型信息的接口。门店类目定位的越规范,能够精准的吸引更多用户,提高曝光率。
接口调用的请求说明
返回数据说明
{
"category_list":
["美食,江浙菜,上海菜","美食,江浙菜,淮扬菜","美食,江浙菜,浙江菜","美食,江浙菜,南京菜 ","美食,江浙菜,苏帮菜…"]
}
# 5.常见错误码
更多错误码请参考“基础支持-全局返回码说明”