微信小店
微信门店
微信智能接口
微信设备功能

微信门店接口

出自微信公众平台开发者文档
跳转到: 导航, 搜索

目录

微信门店接口文档

一、接口简介

门店管理接口为商户提供门店批量导入、查询、修改、删除等主要功能,方便商户快速、高效进行门店管理和操作。

商户在使用门店管理接口时需注意以下几个问题:

  • 门店信息全部需要经过审核方能生效,门店创建完成后,获得poi_id,但该id不一定为最终id,在审核通过后id可能发生变化,只有收到微信推送的审核结果通知中的poi_id才为最终id,并使用在微信各个业务场景中(若在审核期间使用临时poi_id造成相应影响,由开发者自身承担);
  • 为保证在审核通过后,获取到的poi_id 能与商户自身数据做对应,将会允许商户在创建时提交自己内部或自定义的sid(字符串格式,微信不会对唯一性进行校验,请商户自己保证),用于后续获取poi_id 后对数据进行对应;
  • 门店的可用状态available_state,将标记门店相应审核状态,只有审核通过状态,才能进行更新,更新字段仅限扩展字段(表1 中前11 个字段);
  • 扩展字段属于公共编辑信息,提交更新后将由微信进行审核采纳,但扩展字段更新并不影响门店的可用状态(即available_state 仍为审核通过),但update_status 状态变为1,更新中状态,此时不可再次对门店进行更新,直到微信审核采纳后;
  • 在update_status 为1,更新中状态下的门店,此时调用getpoi 接口,获取到的扩展字段为更新的最新字段,但并不是最终结果,仍需等待微信编辑对扩展字段的建议进行采纳后,最终决定是否生效(有可能更新字段不被采纳);

门店页面示例

01.png

二、开发者必读

申请接入

商户接入卡券,需要在公众平台(http://mp.weixin.qq.com ) 拥有已认证的公众号,提交相关资质。申请路径如下登录微信公众平台—添加功能插件—选择门店功能

02.png

如何成为优质门店

商户门店符合“优质”标准:全部字段(含选填)完整填写,内容真实、准确,无违规内容;至少上传三张相关的门店清晰图片。


开发流程

获取接口权限后,商户开发者需按照以下步骤开发和调试,请开发者务必仔细阅读以下流程!

1、创建门店前的准备

上传图片:上传商户新建门店时所使用的图片。上传的图片url必须为微信自己域名的url。

2.创建门店

调用创建门店接口,调用成功后返回errcode、errmsg,会返回临时poi_id,该id可能与最终id不同。

3.审核结果事件推送

新创建的门店在审核通过后,会以事件形式推送给商户填写的回调url(登陆公众平台进入“开发者中心”设置)审核通过获取门店唯一id:poi_id。

03.png

4.查询门店信息

在审核通过并获取poi_id 后,商户可以利用poi_id,查询具体某条门店的信息。

5.查询门店列表

商户可以通过该接口,批量查询自己名下的门店list,并获取已审核通过的poi_id以及商户自身用于对应、商户名、分店名、地址字段的sid

6.修改门店服务信息

商户可以通过该接口,修改门店的服务信息,包括:图片列表、营业时间、推荐、特色服务、简介、人均价格、电话7 个字段(名称、坐标、地址等不可修改)修改后需要人工审核。

7.删除门店

商户可以通过该接口,删除已经成功创建的门店。


三、创建门店

1.上传图片

  • 接口说明

用POI 接口新建门店时所使用的图片url 必须为微信域名的url,因此需要先用上传图片接口上传图片并获取url,再创建门店。

上传的图片限制文件大小限制1MB,支持JPG 格式。

  • 接口调用请求说明
协议 https
http请求方式 POST/FORM
请求Url https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN
POST数据格式 buffer
  • 请求参数说明
参数 说明 是否必填
access_token 调用接口凭证
buffer 图片文件的数据流
  • 返回数据说明

返回成功示例:

{
"url":"http://mmbiz.qpic.cn/XXXXX"
}

插入失败示例(errcode 不为0,errmsg 为相应错误信息):

{ 
"errcode":40001,
"errmsg":"invalid credential"
}
字段 说明
errcode 错误码,0为正常
errmsg 错误信息

2.创建门店

  • 接口说明

创建门店接口是为商户提供创建自己门店数据的接口,门店数据字段越完整,商户页面展示越丰富,越能够吸引更多用户,并提高曝光度。

创建门店接口调用成功后会返回errcode 0、errmsg ok,但不会实时返回poi_id。

成功创建后,会生成poi_id,但该id不一定为最终id。门店信息会经过审核,审核通过后方可获取最终poi_id,该id为门店的唯一id,强烈建议自行存储审核通过后的最终poi_id,并为后续调用使用。

  • 接口调用请求说明
协议 https
http请求方式 POST
请求Url http://api.weixin.qq.com/cgi-bin/poi/addpoi?access_token=TOKEN
POST数据格式 json
  • 请求参数说明
参数 说明 是否必填
access_token 调用接口凭证
buffer json数据
  • POST数据示例

字段视图:

04.png

json 数据示例

{"business":{
   "base_info":{
                   "sid":"33788392",
                   "business_name":"麦当劳",
                   "branch_name":"艺苑路店",
                   "province":"广东省",
                   "city":"广州市",
                   "district":"海珠区",
                   "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
             }
    }
}
字段 说明 是否必填
business_name 门店名称(仅为商户名,如:国美、麦当劳,不应包含地区、地址、分店名等信息,错误示例:北京国美)
branch_name 分店名称(不应包含地区信息,不应与门店名有重复,错误示例:北京王府井店)
province 门店所在的省份(直辖市填城市名,如:北京市)
city 门店所在的城市
district 门店所在地区
address 门店所在的详细街道地址(不要填写省市信息)
telephone 门店的电话(纯数字,区号、分机号均由“-”隔开)
categories 门店的类型(不同级分类用“,”隔开,如:美食,川菜,火锅。详细分类参见附件:微信门店类目表)
offset_type 坐标类型,1 为火星坐标(目前只能选1)
longitude 门店所在地理位置的经度
latitude 门店所在地理位置的纬度(经纬度均为火星坐标,最好选用腾讯地图标记的坐标)
photo_list 图片列表,url 形式,可以有多张图片,尺寸为

640*340px。必须为上一接口生成的url。图片内容不允许与门店不相关,不允许为二维码、员工合照(或模特肖像)、营业执照、无门店正门的街景、地图截图、公交地铁站牌、菜单截图等

special 特色服务,如免费wifi,免费停车,送货上门等商户能提供的特色功能或服务
open_time 营业时间,24 小时制表示,用“-”连接,如 8:00-20:00
avg_price 人均价格,大于0 的整数
sid 商户自己的id,用于后续审核通过收到poi_id 的通知时,做对应关系。请商户自己保证唯一识别性
introduction 商户简介,主要介绍商户信息等
recommend 推荐品,餐厅可为推荐菜;酒店为推荐套房;景点为推荐游玩景点等,针对自己行业的推荐内容
  • 返回数据

返回成功示例:

{
"errcode":0,
"errmsg":"ok"
}

插入失败示例(errcode 不为0,errmsg 为相应错误信息):

{
"errcode":40001,
"errmsg":"invalid credential"
}
字段 说明
errcode 错误码,0为正常
errmsg 错误信息

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>

参数说明:

字段 说明
ToUserName 发送方帐号(一个OpenID)
FromUserName 错误信息
CreateTime 消息创建时间(整型)
MsgType 消息类型,event
Event 事件类型,poi_check_notify
UniqId 商户自己内部ID,即字段中的sid
PoiId 微信的门店ID,微信内门店唯一标示ID
Result 审核结果,成功succ 或失败fail
Msg 成功的通知信息,或审核失败的驳回理由

4.查询门店信息

  • 接口说明

创建门店后获取poi_id 后,商户可以利用poi_id,查询具体某条门店的信息。 若在查询时,update_status 字段为1,表明在5 个工作日内曾用update 接口修改过门店扩展字段,该扩展字段为最新的修改字段,尚未经过审核采纳,因此不是最终结果。最终结果会在5 个工作日内,最终确认是否采纳,并前端生效(但该扩展字段的采纳过程不影响门店的可用性,即available_state仍为审核通过状态

  • 注:扩展字段为公共编辑信息(大家都可修改),修改将会审核,并决定是否对修改建议进行采纳,但不会影响该门店的生效可用状态。

  • 接口调用请求说明
协议 https
http请求方式 POST
请求Url http://api.weixin.qq.com/cgi-bin/poi/getpoi?access_token=TOKEN
POST数据格式 json
  • 请求参数说明
参数 说明 是否必填
access_token 调用接口凭证
buffer json数据
  • 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
                }
        }
 }
字段 说明
errcode 错误码,0为正常
errmsg 错误信息
available_state 门店是否可用状态。1 表示系统错误、2 表示审核中、3 审核通过、4 审核驳回。当该字段为1、2、4 状态时,poi_id 为空
update_status 扩展字段是否正在更新中。1 表示扩展字段正在更新中,尚未生效,不允许再次更新; 0 表示扩展字段没有在更新中或更新已生效,可以再次更新
business 门店信息,字段内容同前

*注其他字段同前

5.查询门店列表

  • 接口说明

商户可以通过该接口,批量查询自己名下的门店list,并获取已审核通过的poi_id(所有状态均会返回poi_id,但该poi_id不一定为最终id)、商户自身sid 用于对应、商户名、分店名、地址字段。

  • 接口调用请求说明
协议 https
http请求方式 POST
请求Url https://api.weixin.qq.com/cgi-bin/poi/getpoilist?access_token=TOKEN
POST数据格式 json
  • 请求参数说明
参数 说明 是否必填
access_token 调用接口凭证
buffer json数据
  • POST数据示例
{
"begin":0,
"limit":10
}

字段说明

字段 说明 是否必填
begin 开始位置,0 即为从第一条开始查询
limit 返回数据条数,最大允许50,默认为20
  • 返回数据说明

数据示例:

第一条为审核通过,有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",
}
参数 说明
access_token 调用接口凭证
buffer json数据
total_count 门店总数量

*注其他字段同前

6.修改门店服务信息

  • 接口说明

商户可以通过该接口,修改门店的服务信息,包括:图片列表、营业时间、推荐、特色服务、简介、人均价格、电话7 个字段(名称、坐标、地址等不可修改)修改后需要人工审核。

  • 接口调用请求说明
协议 https
http请求方式 POST/FROM
请求Url https://api.weixin.qq.com/cgi-bin/poi/updatepoi?access_token=TOKEN
POST数据格式 buffer
  • 请求参数说明
参数 说明 是否必填
access_token 调用接口凭证
buffer json数据
  • POST数据示例
{"business ":{
   "base_info":{
                  "poi_id ":"271864249"
                  "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
              }
      }
}

字段说明:

全部字段内容同前。

特别注意:

以上7 个字段,若有填写内容则为覆盖更新,若无内容则视为不修改,维持原有内容。 photo_list 字段为全列表覆盖,若需要增加图片,需将之前图片同样放入list 中,在其后增加新增图片。如:已有A、B、C 三张图片,又要增加D、E 两张图,则需要调用该接口,photo_list 传入A、B、C、D、E 五张图片的链接。

  • 返回数据说明

数据示例:

{
"errcode":0,
"errmsg":"ok"
}
字段 说明
errcode 错误码,0为正常
errmsg 错误信息

7.删除门店

  • 接口说明

商户可以通过该接口,删除已经成功创建的门店。请商户慎重调用该接口,门店信息被删除后,可能会影响其他与门店相关的业务使用,如卡券等。同样,该门店信息也不会在微信的商户详情页显示,不会再推荐入附近功能。

  • 接口调用请求说明
协议 https
http请求方式 POST/FROM
请求Url https://api.weixin.qq.com/cgi-bin/poi/delpoi?access_token=TOKEN
POST数据格式 buffer
  • 请求参数说明
参数 说明
access_token 调用接口凭证
POST json数据
  • POST数据示例
{
"poi_id": "271262077"
}

字段说明:

字段 说明
poi_id 门店ID
  • 返回数据说明

数据示例:

{
"errcode":0,
"errmsg":"ok"
}
字段 说明
errcode 错误码,0为正常
errmsg 错误信息

四.门店类目表

  • 接口说明

类目名称接口是为商户提供自己门店类型信息的接口。门店类目定位的越规范,能够精准的吸引更多用户,提高曝光率。

  • 接口调用的请求说明
协议 https
http请求方式 GET
请求Url http://api.weixin.qq.com/cgi-bin/poi/getwxcategory?access_token=TOKEN
  • 返回数据说明
{
  "category_list":
            ["美食,江浙菜,上海菜","美食,江浙菜,淮扬菜","美食,江浙菜,浙江菜","美食,江浙菜,南京菜 ","美食,江浙菜,苏帮菜…"]
}

五.常见错误码

错误码 errmsg 说明
-1 system error 系统错误,请稍后重试
40009 Invalid image size 图片大小为0或者超过1M
40094 invalid args 参数不正确,请检查json 字段
65104 invalid category 门店的类型不合法,必须严格按照附表的分类填写
65105 invalid photo url 图片url 不合法,必须使用接口1 的图片上传接口所获取的url
65106 poi audit state must be approved 门店状态必须未审核通过
65107 not allow modify 扩展字段为不允许修改的状态
65109 invalid business 门店名为空
65110 invalid address 门店所在详细街道地址为空
65111 invalid telephone 门店的电话为空
65112 invalid city 门店所在的城市为空
65113 invalid province 门店所在的省份为空
65114 empty photo list 图片列表为空
65115 invalid poi id poi_id 不正确

更多错误码请参考“基础支持-全局返回码说明”:

../19/451ebe08a82d2031dcbfcf747aa58dd3.html

六.附件:微信门店类目表

微信门店接口文档 V2.3下载

七.联系我们

遇到问题,可以通过邮箱weixin_shop@foxmail.com 联系我们。也可以加入开发者交流群 463320265,验证请说明所属商家和业务。