微信门店接口

更新日志：

版本号	更新内容	更新时间
V2.1	创建门店可以返回临时poiid	2016.7.18

微信门店接口文档

1.接口简介

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

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

门店信息全部需要经过审核方能生效，门店创建完成后，获得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 接口，获取到的扩展字段为更新的最新字段，但并不是最终结果，仍需等待微信编辑对扩展字段的建议进行采纳后，最终决定是否生效（有可能更新字段不被采纳）；

门店页面示例

2.开发者必读

2.1申请接入

拥有已认证的服务号可申请开通门店管理功能。

认证的订阅号拥有卡券、WI-FI、摇一摇、广告主等功能后会自动开通门店管理功能。

申请路径如下登录微信公众平台—添加功能插件—选择门店功能。

2.2开发流程

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

1、创建门店前的准备

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

2.创建门店

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

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 格式。

接口调用请求说明

协议	https
http请求方式	POST/FORM
请求Url	https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN
POST数据格式	buffer

请求参数说明

参数	说明	是否必填
access_token	调用接口凭证	是
buffer	图片文件的数据流	是

返回数据说明

返回成功示例：

插入失败示例（errcode 不为0，errmsg 为相应错误信息）：

字段	说明
errcode	错误码，0为正常
errmsg	错误信息

3.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数据示例

字段视图：

json 数据示例

门店基础信息字段（重要）

字段	说明	是否必填
sid	商户自己的id，用于后续审核通过收到poi_id 的通知时，做对应关系。请商户自己保证唯一识别性	否
business_name	门店名称（仅为商户名，如：国美、麦当劳，不应包含地区、地址、分店名等信息，错误示例：北京国美） 不能为空，15个汉字或30个英文字符内	是
branch_name	分店名称（不应包含地区信息，不应与门店名有重复，错误示例：北京王府井店） 10个字以内	是
province	门店所在的省份（直辖市填城市名,如：北京市） 10个字以内	是
city	门店所在的城市 10个字以内	是
district	门店所在地区 10个字以内	是
address	门店所在的详细街道地址（不要填写省市信息）	是 （东莞等没有“区”行政区划的城市，该字段可不必填写。其余城市必填。）
telephone	门店的电话（纯数字，区号、分机号均由“-”隔开）	是
categories	门店的类型（不同级分类用“,”隔开，如：美食，川菜，火锅。详细分类参见附件：微信门店类目表）	是
offset_type	坐标类型，1 为火星坐标（目前只能选1）	是
longitude	门店所在地理位置的经度	是
latitude	门店所在地理位置的纬度（经纬度均为火星坐标，最好选用腾讯地图标记的坐标）	是

门店服务信息字段

字段	说明	是否必填
photo_list	图片列表，url 形式，可以有多张图片，尺寸为 640*340px。必须为上一接口生成的url。图片内容不允许与门店不相关，不允许为二维码、员工合照（或模特肖像）、营业执照、无门店正门的街景、地图截图、公交地铁站牌、菜单截图等	否
recommend	推荐品，餐厅可为推荐菜；酒店为推荐套房；景点为推荐游玩景点等，针对自己行业的推荐内容 200字以内	否
special	特色服务，如免费wifi，免费停车，送货上门等商户能提供的特色功能或服务	否
introduction	商户简介，主要介绍商户信息等 300字以内	否
open_time	营业时间，24 小时制表示，用“-”连接，如 8:00-20:00	否
avg_price	人均价格，大于0 的整数	否

返回数据

返回成功示例：

插入失败示例（errcode 不为0，errmsg 为相应错误信息）：

字段	说明
errcode	错误码，0为正常
errmsg	错误信息

常见出错字段规范

1）门店名称

门店名：不能为空，15个汉字或30个英文字符内，不能含有括号和特殊字符，仅为商户（品牌）名称，如海底捞，苏宁电器，华景国旅，茂业百货；不应包含地区、地址、分店名等信息。错误及正确示例见下。

分店名：不超过10个字，不能含有括号和特殊字符，用于在同一商户（品牌）有多家分店时区分不同门店，如国贸店，春熙路店，万象城店；不应包含地区信息，不应与门店名有重复。错误及正确示例见下。

错误示例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":["美食,茶餐厅"],

出错原因：将麦当劳的类目信息写成“美食,茶餐厅”。

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）经纬度：

可利用以下工具找到各门店对应的经纬度坐标，导出相应坐标值。

详见链接：坐标拾取器地址。

http://lbs.qq.com/tool/getpoint/index.html

注意：经纬度坐标需要转换为腾讯地图坐标。

详见链接：

http://lbs.qq.com/webservice_v1/guide-convert.html

3.3审核事件推送

新创建的门店在审核通过后，会以事件形式推送给商户填写的回调URL（登陆公众平台进入“开发者中心”设置）

微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次。 关于重试的消息排重，推荐使用FromUserName + CreateTime 排重。

假如服务器无法保证在五秒内处理并回复，可以直接回复空串，微信服务器不会对此作任何处理，并且不会发起重试。

推送XML数据包示例：

参数说明：

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

3.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数据示例

返回数据说明

数据示例

字段	说明
errcode	错误码，0为正常
errmsg	错误信息
available_state	门店是否可用状态。1 表示系统错误、2 表示审核中、3 审核通过、4 审核驳回。当该字段为1、2、4 状态时，poi_id 为空
update_status	扩展字段是否正在更新中。1 表示扩展字段正在更新中，尚未生效，不允许再次更新； 0 表示扩展字段没有在更新中或更新已生效，可以再次更新
business	门店信息，字段内容同前

*注其他字段同前

3.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	返回数据条数，最大允许50，默认为20	是

返回数据说明

数据示例：

为审核通过，有poi_id，全部字段；第二条为审核不通过，仅有基础字段；第三条为审核中，仅有基础字段。

参数	说明
access_token	调用接口凭证
buffer	json数据
total_count	门店总数量

3.6修改门店服务信息

接口说明

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

接口调用请求说明

协议	https
http请求方式	POST/FROM
请求Url	https://api.weixin.qq.com/cgi-bin/poi/updatepoi?access_token=TOKEN
POST数据格式	buffer

请求参数说明

参数	说明	是否必填
access_token	调用接口凭证	是
buffer	json数据	是

POST数据示例

字段说明：

全部字段内容同前。

特别注意：

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

返回数据说明

数据示例：

字段	说明
errcode	错误码，0为正常
errmsg	错误信息

3.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	门店ID

返回数据说明

数据示例：

字段	说明
errcode	错误码，0为正常
errmsg	错误信息

4.门店类目表

接口说明

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

接口调用的请求说明

协议	https
http请求方式	GET
请求Url	http://api.weixin.qq.com/cgi-bin/poi/getwxcategory?access_token=TOKEN

返回数据说明

5.常见错误码

错误码	errmsg	说明
-1	system error	系统错误，请稍后重试
40009	Invalid image size	图片大小为0或者超过1M
40097	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 不正确

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

7.联系我们

遇到问题，可以加入开发者交流群 463320265联系我们，验证请说明所属商家和业务。