# Manage Extension Interface

# I. Declare the identity of promoter

# Interface Dxplaination

Weixin Mini Program The relationship with promoter is two-way, i.e. the Mini Program developer must first declare the identity of the user (e.g., a merchant, etc.) and invite the user to open the Mini Program function before the user officially becomes the Mini Program promoter. Weixin Mini Program Businesses need to declare the basic information of the promotion staff first, before inviting the promotion staff to open the function through the invitation material. Note: Each Weixin Mini Program binds a maximum of 100 thousand promoters.

# Request address

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

# Request parameters

parameter type Is it compulsory? Introductions
openid string yes Promoter's openid or unionid
role_id uint32 yes Role id, role_id need to adjust the "query role" interface query
retail_id string no Store id, no longer than 20 characters
extra_info string no Promoter parameters, for customizing the logo promoter, cannot exceed 80 characters in length
name string no Promoter name, not more than 30 characters long
phone string no Promoter's mobile phone number cannot be more than 20 characters long

Note: A promoter under the same AppID is only allowed to bind a role and store, a single declaration of the total number of promoters can not exceed 10, the total number can not exceed 50000.

# Example Requests

{
  "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"
    }
  ]
}

# Return value

attribute type Introductions
total_cnt uint32 Declaration of total number of promoters
fail_cnt uint32 Announce number of promoter failures
openid string Failed to declare the openid of the promoter
role_id uint32 Roleid
retail_id string Store ID
extra_info string Promoter parameters
name string Name of promoter
phone string Promoter's mobile phone number
errcode int32 Error code
errmsg string Error message

Note: Error declarations such as an invalid length of argument, incorrect openid, or duplicate will be returned in fail_list as is, with errcode and errmsg in fail_list indicating the cause of the error. Returns the outermost JSON errcode and errmsg to indicate whether the call to the API interface was successful or not.

# Return data example

{
  "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"
}

# II. Inquire about the identity of promoters

# Interface Dxplaination

The merchant can invite the promoter after (send the promoter the invitation material,Or direct the promoter to the authentication page from their own kiosk Weixin Mini Program, query whether the invited promoter accepted the invitation and when the invitation was accepted, and remind promoters who have not accepted the offer for a long time in due course. This interface can query the state of Weixin Mini Program binding to the promoter under all / specific role id / specific store id. If both decl_status and auth_status are 1 then the promotioner and the Mini Program are bound in both directions.After the promoter completes the two-way bonding, the merchant can check the promotional effectiveness of the promoter and send business notice to the promoter.

# Request address

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

# Request parameters

Note: All character strings in this document are string.length (), the string to utf8 encoding, a Chinese character length of 3

parameter type Is it compulsory? Introductions
openid string no Promoter's openid or unionid
role_id uint32 no Roleid
retail_id string no Store id, no longer than 20 characters
begin_time uint32 no Initial second timestamp for promotional authorization status changes
end_time uint32 no End-second timestamp for promotional authorization status changes
start_id string no For paging, the maximum number of pulls per page is 2,000, and more than 2,000 must be paged
need_unionid uint32 no Returns openid by default, fill 1: returns unionid
auth_status uint32 no 0: Promoter is not authorized 1: Promoter is authorized 2: Promoter cancels authorization
decl_status string no 1: The merchant has declared 2: The merchant has cancelled the declaration

# Example Requests

{
  "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
}

# Return value

attribute type Introductions
openid string The openid of the promoter
role_id uint32 Roleid
retail_id string Store ID
extra_info string Promoter parameters
name string Name of promoter
phone string Promoter's mobile phone number
auth_status uint32 0: Promoter is not authorized 1: Promoter is authorized 2: Promoter cancels authorization
decl_status string 1: The merchant has declared 2: The merchant has cancelled the declaration
update_time uint32 Second timestamp for a change in a promoter authorization status
id string Unique id, paging, and backtracking when updating
total_cnt uint32 Total number of promoters in Ryder
errcode int32 Error code
errmsg string Error message

Note: Sort by id from small to large. When paging needs to be done, squeeze the largest id into start_id. If total_cnt is less than 2000 or returns empty (error code: 103006, data does not exist), the data pull is complete.

# Return data example

{
  "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"
}

# III. Modifying the Promoter's Status

# Interface Dxplaination

In the event of a promotional representative's change of duties (such as a change of role, a change in the stores served), or a departure, the merchant may change the promotional declaration information or cancel the declaration through this interface.

# Request address

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

# Request parameters

Note: All character strings in this document are string.length (), the string to utf8 encoding, a Chinese character length of 3

parameter type Is it compulsory? Introductions
id string yes The unique ID of the promoter
role_id uint32 no Roleid
retail_id string no Store id, no longer than 20 characters
extra_info string no Promoter parameters, cannot exceed 80 characters in length
name string no Promoter name, not more than 30 characters long
phone string no Promoter's mobile phone number cannot be more than 20 characters long
decl_status string no 1: The merchant has declared 2: The merchant has cancelled the declaration

# Example Requests

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

# Return value

attribute type Introductions
errcode int32 Error code
errmsg string Error message

# Return data example

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