小程序
  • 中文
  • EN
取消
开发
  • 中文
  • EN
中文
EN
取消
  • 平台能力

    • # 管理推广员接口

    # 一、声明推广员身份

    # 接口说明

    小程序与推广员是双向绑定的关系，即小程序开发者需先对用户（如导购等）做推广员身份的声明，并邀请其开通推广员功能，该用户才正式成为小程序的推广员。 小程序商家需先声明推广员的基本信息，才可通过邀请素材邀请推广员开通功能。 注：每个小程序最多绑定10万个推广员。

    # 请求地址

    POST https://api.weixin.qq.com/promoter/addpromoter?access_token=ACCESS_TOKEN

    # 请求参数

    参数 类型 是否必填 说明
    openid string 是 推广员的openid或unionid
    role_id uint32 是 角色id，role_id需调「查询角色」接口查询
    retail_id string 否 门店id，长度不能超过20个字符
    extra_info string 否 推广员参数，用于自定义标识推广员，长度不能超过80个字符
    name string 否 推广员名称，长度不能超过30个字符
    phone string 否 推广员手机号，长度不能超过20个字符

    注：一个推广员在同一appid下只允许绑定一个角色和门店，单次声明推广员总数不能超过10，总数不能超过50000。

    # 请求示例

    {
  "promoter_list":
  [
    {
      "openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "name": "xxxxx",
      "phone": "xxxxx"
    },
    {
      "openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "name": "xxxxx",
      "phone": "xxxxx"
    }
  ]
}

    # 返回值

    属性 类型 说明
    total_cnt uint32 声明推广员总数
    fail_cnt uint32 声明推广员失败数
    openid string 声明失败推广员的openid
    role_id uint32 角色id
    retail_id string 门店id
    extra_info string 推广员参数
    name string 推广员名称
    phone string 推广员手机号
    errcode int32 错误码
    errmsg string 错误信息

    注：参数长度不合法、openid有误或重复等错误声明会放入fail_list原样返回，同时fail_list里有errcode和errmsg表明错误原因。返回Json最外层的errcode和errmsg表示api接口的调用成功与否。

    # 返回数据示例

    {
  "total_cnt": 200,
  "fail_cnt": 2,
  "fail_list":
  [
    {
      "openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "name": "xxxxx",
      "phone": "xxxxx"
    },
    {
      "openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "name": "xxxxx",
      "phone": "xxxxx",
      "errcode": 103003,
      "errmsg": "data already exists"
    }
  ],
  "errcode": 0,
  "errmsg": "OK"
}

    # 二、查询推广员身份

    # 接口说明

    商家可以在邀请完推广员（向推广员发送邀请素材、或引导推广员从自有导购小程序进入认证页面）后，查询所邀请推广员是否接受邀请、以及接受邀请的时间，适时提醒较久未接受邀请的推广员。 通过此接口可查询全部/特定角色id/特定门店id下小程序与推广员的绑定状态，若decl_status和auth_status的值都为1，则推广员与小程序为双向绑定的状态。推广员完成双向绑定后，商家可查询推广员的推广效果，并向推广员下发业务通知。

    # 请求地址

    POST https://api.weixin.qq.com/promoter/getpromoter?access_token=ACCESS_TOKEN

    # 请求参数

    注：本文档所有字符串长度均取string.length()，字符串以utf8编码，一个汉字长度为3

    参数 类型 是否必填 说明
    openid string 否 推广员的openid或unionid
    role_id uint32 否 角色id
    retail_id string 否 门店id，长度不能超过20个字符
    begin_time uint32 否 推广员授权状态变更开始秒级时间戳
    end_time uint32 否 推广员授权状态变更结束秒级时间戳
    start_id string 否 用于分页时透传，单次拉取上限为2000，超过2000须分页
    need_unionid uint32 否 默认返回openid，填1：返回unionid
    auth_status uint32 否 0：推广员未授权 1：推广员已授权 2：推广员取消授权
    decl_status string 否 1：商家已声明 2：商家取消声明

    # 请求示例

    {
  "openid": "xxxxx",
  "role_id": 1,
  "retail_id": "xxxxx",
  "begin_time": 1668614400,
  "end_time": 1668666429,
  "start_id": "123",
  "need_unionid": 1,
  "auth_status": 1,
  "decl_status": 1
}

    # 返回值

    属性 类型 说明
    openid string 推广员的openid
    role_id uint32 角色id
    retail_id string 门店id
    extra_info string 推广员参数
    name string 推广员名称
    phone string 推广员手机号
    auth_status uint32 0：推广员未授权 1：推广员已授权 2：推广员取消授权
    decl_status string 1：商家已声明 2：商家取消声明
    update_time uint32 推广员授权状态变更秒级时间戳
    id string 唯一id，分页和更新时回传
    total_cnt uint32 拉取的推广员总数
    errcode int32 错误码
    errmsg string 错误信息

    注：按id从小到大排序，需要分页时把最大的id塞到start_id里，如果total_cnt小于2000或者返回为空（错误码：103006，数据不存在）表明数据拉取完成。

    # 返回数据示例

    {
  "promoter_list":
  [
    {
      "openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "auth_status": 1,
      "decl_status": 1,
      "update_time": 1668667349,
      "id": "100",
      "name": "xxxxx",
      "phone": "xxxxx"
    },
    {
      "openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "auth_status": 1,
      "decl_status": 1,
      "update_time": 1668667349,
      "id": "123",
      "name": "xxxxx",
      "phone": "xxxxx"
    }
  ],
  "total_cnt": 2,
  "errcode": 0,
  "errmsg": "OK"
}

    # 三、修改推广员身份

    # 接口说明

    若推广员出现职责变更（比如角色变化、所服务门店变化）、或离职等情况，商家可通过本接口更改推广员的声明信息或取消声明。

    # 请求地址

    POST https://api.weixin.qq.com/promoter/updatepromoter?access_token=ACCESS_TOKEN

    # 请求参数

    注：本文档所有字符串长度均取string.length()，字符串以utf8编码，一个汉字长度为3

    参数 类型 是否必填 说明
    id string 是 推广员的唯一id
    role_id uint32 否 角色id
    retail_id string 否 门店id，长度不能超过20个字符
    extra_info string 否 推广员参数，长度不能超过80个字符
    name string 否 推广员名称，长度不能超过30个字符
    phone string 否 推广员手机号，长度不能超过20个字符
    decl_status string 否 1：商家已声明 2：商家取消声明

    # 请求示例

    {
  "id": "123",
  "role_id": 1,
  "retail_id": "xxxxx",
  "extra_info": "xxxxx",
  "decl_status": 2,
  "name": "xxxxx",
  "phone": "139xxxxxxxx"
}

    # 返回值

    属性 类型 说明
    errcode int32 错误码
    errmsg string 错误信息

    # 返回数据示例

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