朋友的券-朋友的券管理接口


上一篇 : 朋友的券-朋友的券核销 下一篇: 特殊票券



朋友的券管理接口

更新朋友的券信息接口

接口说明

创建朋友的券成功之后开发者可调用该接口更改卡券信息,某些需要修改后送审的字段开发者需慎重处理

开发者注意事项

  1. 更改卡券的部分字段后会重新提交审核,详情见字段说明,更新成功后可通过调用查看卡券详情接口核查更新结果;

  2. 仅填入需要更新的字段,许多开发者在调用该接口时会填入brandname(品牌名称)等不支持修改的字段,导致更新不成功。

  3. 调用该接口后更改卡券信息后,请务必调用查看卡券详情接口验证是否已成功更改。

    接口调用请求说明

    http请求方式: POST https://api.weixin.qq.com/card/update?access_token=TOKEN

    参数说明

    参数 是否必须 说明
    access_token 调用接口凭证
    POST数据 JSON数据

    POST示例

    {
       "card_id": "pbLatjgOY1_Cxi3mnWBThtG90HGg",
       "cash": {
           "base_info": {
               "code_type": "CODE_TYPE_TEXT",
               "color": "Color010",
               "service_phone": "020-88888888",
               "description": "不可与其他优惠同享如需团购券发票,请在消费时向商户提出",
               "can_share": false,
               "can_give_friend": false,
               "location_id_list": [
                   272981040,
                   400183234
               ],
               "custom_url_name": "立即使用",
               "custom_url": "http://www.qq.com ",
               "custom_url_sub_title": "6个汉字tips",
               "promotion_url_name": "更多优惠",
               "promotion_url": "http://www.qq.com"
           },
           "advanced_info": {
               "time_limit": [
                   {
                       "type": "MONDAY"
                   },
                   {
                       "type": "HOLIDAY"
                   }
               ],
               "text_image_list": [
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "此菜品精选食材,以独特的烹饪方法,最大程度地刺激食客的味蕾"
                   },
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "此菜品迎合大众口味,老少皆宜,营养均衡"
                   }
               ],
               "business_service": [
                   "BIZ_SERVICE_FREE_WIFI",
                   "BIZ_SERVICE_WITH_PET",
                   "BIZ_SERVICE_FREE_PARK",
                   "BIZ_SERVICE_DELIVER"
               ],
               "consume_share_card_list": [
                   {
                       "card_id": "pbLatjpvp0Xq6jtgRRxCKtudkBz8k",
                       "num": 1
                   }
               ],
               "consume_share_self_num": 0,
               "abstract": {
                   "abstract": "微信餐厅推出多种新季菜品,期待您的光临",
                   "icon_url_list": [
                       "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
                   ]
               }
           }
       }
    }

    字段说明

    Base_info(卡券基础信息)字段修改:

    参数名 是否提审 类型 示例值 描述
    base_info - JSON结构
    卡券基础信息字段。
    logo_url string(128) http://mmbiz.qpic.cn/ 卡券的商户logo,建议像素为300*300。
    notice string(48) 请出示二维码核销卡券。 使用提醒,字数上限为16个汉字。
    description string(3072) 不可与其他优惠同享\n如需团购券发票,请在消费时向商户提出\n店内均可使用,仅限堂食。 使用说明。
    service_phone string(24) 40012234 客服电话。
    color string(3072) Color010 卡券颜色。
    location_id_list string(3072) 1234,2314 支持更新适用门店列表。
    center_title string(18) 快速使用 顶部居中的自定义cell。
    center_sub_title string(24) 点击快速核销卡券 顶部居中的自定义cell说明。
    center_url string(128) www.qq.com 顶部居中的自定义cell的跳转链接。
    location_id_list string(3072) 1234,2314 支持更新适用门店列表。
    custom_url_name string(16) 立即使用 自定义跳转入口的名字。
    custom_url string(128) www.qq.com 自定义跳转的URL。
    custom_url_sub_title string(18) 更多惊喜 显示在入口右侧的提示语。
    promotion_url_name string(16) 产品介绍。 营销场景的自定义入口名称。
    promotion_url string(128) www.qq.com; 入口跳转外链的地址链接。
    promotion_url_sub_title string(18) 卖场大优惠。 显示在营销入口右侧的提示语。
    code_type string(16) CODE_TYPE_TEXT。 Code码展示类型,"CODE_TYPE_TEXT",文本;"CODE_TYPE_BARCODE",一维码 ;"CODE_TYPE_QRCODE",二维码;"CODE_TYPE_ONLY_QRCODE",二维码无code显示;"CODE_TYPE_ONLY_BARCODE",一维码无code显示;"CODE_TYPE_NONE",无code类型
    get_limit int 1 每人可领券的数量限制。
    can_share bool false 卡券原生领取页面是否可分享。
    can_give_friend bool false 卡券是否可转赠。
    date_info Json结构 见上述示例 使用日期,有效期的信息,有效期时间修改仅支持有效区间的扩大。
    type string DATE_TYPE_FIX_TIME_RANGE 有效期类型,仅支持更改type为DATE_TYPE_FIX_TIME_RANGE 的时间戳。
    begin_timestamp unsigned int 14300000 固定日期区间专用,表示起用时间。(单位为秒)
    end_timestamp unsigned int 15300000 固定日期区间专用,表示结束时间。最长可将卡券有效期延长至三个月。

    Advanced_info(卡券高级信息)字段修改:

    特别注意,以下支持更新的字段不在基本信息base_info的结构中。

    参数名 是否提审 类型 示例值 描述
    advanced_info JSON结构

    abstract JSON结构 优惠详情摘要字段。
    abstract string(60) 简介。 本券限领一张,不能与其他优惠共同使用。
    icon_url_list string(3072) 图片列表,仅支持填入一个封面图片链接,上传图片接口上传获取图片获得链接,填写非CDN链接会报错,并在此填入。建议图片尺寸像素900*375 http://mmbiz.qpic.cn/mmbiz/xxxxx
    text_image_list string(3072) 图文列表,显示在详情内页,优惠券券开发者须至少传入一组图文列表
    image_url string(3072) 图片链接,必须调用上传图片接口上传图片获得链接,并在此填入,否则报错 http://mmbiz.qpic.cn/mmbiz/xxxxx。
    text string(3072) 图文描述,5000字以内 一般为商品详情介绍
    business_service string(24) 商家服务类型 可多选,此处仅控制展示,不填则不显示 BIZ_SERVICE_DELIVER 外卖服务;BIZ_SERVICE_FREE_PARK 停车位;BIZ_SERVICE_WITH_PET 可带宠物;BIZ_SERVICE_FREE_WIFI 免费Wi-Fi
    time_limit string(24) 使用时段限制
    type string(24) MONDAY 周一 TUESDAY 周二 WEDNESDAY 周三 THURSDAY 周四 FRIDAY 周五 SATURDAY 周六 SUNDAY 周日 HOLIDAY 假期通用 限制类型,可多选,此处仅控制展示,不填则不显示
    consume_share_self_num int 核销后送券的数量,可设置核销后送本券的数量,限制传入1张,与consume_share_card_list互斥 1
    consume_share_card_list JSON 核销后赠送其他卡券的列表
    card_id string(24) pbLatjhvf1xBtaOIhYOCnp7Wv4DA 核销后赠送的其他卡券card_id,目前仅支持填入一个共享券card_id,注意此处必须填入共享券
    num unsigned int 1 核销后赠送的该card_id数目,目前仅支持填1

    返回数据说明

    数据示例:

    {"errcode":0, "errmsg":"ok", "send_check":false}
    参数名 描述
    errcode 错误码,0为正常。
    errmsg 错误信息。
    send_check 是否提交审核,false为修改后不会重新提审,true为修改字段后重新提审,该卡券的状态变为审核中。

    拉取朋友的券数据接口

    接口简介及开发注意事项

    为支持开发者调用API查看卡券相关数据,微信卡券团队封装数据接口并面向具备卡券功能权限的开发者开放使用。开发者调用该接口可获取本商户下的所有卡券相关的总数据以及指定卡券的相关数据。

    拉取卡券概况数据接口

    接口说明

    支持调用该接口拉取本商户的总体数据情况,包括时间区间内的各指标总量。

    接口调用请求说明

    http请求方式: POST https://api.weixin.qq.com/datacube/getcardbizuininfo?access_token=ACCESS_TOKEN

    请求参数说明

    参数 是否必须 说明
    access_token 调用接口凭证
    POST数据 Json数据

    POST数据

    {
       "begin_date": "2015-06-15",
       //请开发者按示例格式填写日期,否则会报错dateformaterror"end_date": "2015-06-30",
       "cond_source": 0
    }

    参数说明:

    字段 说明 是否必填 类型 示例值
    begin_date 查询数据的起始时间。 string(16) 2015-06-15
    end_date 查询数据的截至时间。 string(16) 2015-06-30
    cond_source 卡券来源,0为公众平台创建的卡券数据、1是API创建的卡券数据 unsigned int 0

    返回数据说明 数据示例:

    {
       "list": [
           {
               "ref_date": "2015-06-23",
               "view_cnt": 1,
               "view_user": 1,
               "receive_cnt": 1,
               "receive_user": 1,
               "verify_cnt": 0,
               "verify_user": 0,
               "given_cnt": 0,
               "given_user": 0,
               "expire_cnt": 0,
               "expire_user": 0
           }
       ]
    }

    字段说明:

    字段 说明
    ref_date 日期信息
    view_cnt 浏览次数
    view_user 浏览人数
    receive_cnt 领取次数
    receive_user 领取人数
    verify_cnt 使用次数
    verify_user 使用人数
    given_cnt 转赠次数
    given_user 转赠人数
    expire_cnt 过期次数
    expire_user 过期人数

    注意:

    1. 查询时间区间需<=62天,否则报错{errcode: 61501,errmsg: "date range error"};

    2. 传入时间格式需严格参照示例填写”2015-06-15”,否则报错{errcode":61500,"errmsg":"date format error"}

    获取朋友的券数据接口

    接口说明

    支持开发者调用该接口拉取朋友的券在固定时间区间内的相关数据。

    接口调用请求说明

    http请求方式: POST https://api.weixin.qq.com/datacube/getcardcardinfo?access_token=ACCESS_TOKEN

    请求参数说明

    参数 是否必须 说明
    access_token 调用接口凭证
    POST数据 Json数据

    POST数据

    {
       "begin_date": "2015-06-15",
       "end_date": "2015-06-30",
       "cond_source": 0,
       "card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE"}

    参数说明:

    字段 说明 是否必填 类型 示例值
    begin_date 查询数据的起始时间。 string(16) 2015-06-15
    end_date 查询数据的截至时间。 string(16) 2015-06-30
    cond_source 卡券来源,0为公众平台创建的卡券数据、1是API创建的卡券数据 unsigned int 0
    card_id 卡券ID。填写后,指定拉出该卡券的相关数据。 string(32) po8pktyDLmakNY2fn2VyhkiEPqGE

    返回数据说明 数据示例:

    {
       "list": [
           {
               "ref_date": "2015-06-23",
               "card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE",
               "card_type": 3,
               "view_cnt": 1,
               "view_user": 1,
               "receive_cnt": 1,
               "receive_user": 1,
               "verify_cnt": 0,
               "verify_user": 0,
               "given_cnt": 0,
               "given_user": 0,
               "expire_cnt": 0,
               "expire_user": 0
           }
       ]
    }

    字段说明:

    字段 说明
    ref_date 日期信息
    card_id 卡券ID
    card_type cardtype:0:折扣券,1:代金券,2:礼品券,3:优惠券,4:团购券(暂不支持拉取特殊票券类型数据,电影票、飞机票、会议门票、景区门票)
    view_cnt 浏览次数
    view_user 浏览人数
    receive_cnt 领取次数
    receive_user 领取人数
    verify_cnt 使用次数
    verify_user 使用人数
    given_cnt 转赠次数
    given_user 转赠人数
    expire_cnt 过期次数
    expire_user 过期人数

    注意:

    1. 查询时间区间需<=62天,否则报错{"errcode:" 61501,errmsg: "date range error"};

    2. 传入时间格式需严格参照示例填写如”2015-06-15”,否则报错{"errcode":"date format error"}

    我是第三方开发者/服务商

    朋友的券目前率先开通了MP流程,同样支持接口创建朋友的券。目前第三方/服务商可以利用现有能力帮助没有开发能力的商户创建、投放并核销朋友的券,并管理朋友的券数据。

    第三方/服务商可以通过以下流程完成朋友的券基本流程:

    1、第三方/服务商须登录微信开放平台申请成为公众号第三方平台,并全网发布,详情点击公众号第三方平台

    2、商户通过公众号授权将公众账号的卡券权限集授权给第三方代调用接口,详情点击代公众号调用接口

    3、开发者根据垂直行业特点,帮助商户完成创建朋友的券、投放朋友的券、 接口兑换库存、充值券点、核销朋友的券并完成朋友的券数据管理。

    4、对于有能力的开发者可以融合第三方授权授权第三方协助制券等模式搭建自己的 卡券平台供子商户使用。

    交流反馈

    朋友的券开发者可以加入开发者交流五群、六群(QQ群):512568283、205482166,若开发过程中遇到问题,也可以发送邮件到weixin_card@foxmail.com 反馈。


    上一篇 : 朋友的券-朋友的券核销 下一篇: 特殊票券