0
# Shopping Guide Services
1

2
Comprehensive shopping guide functionality for WeChat Official Accounts, including guide management, buyer tracking, materials, tags, and mass job operations.
3

4
## Guide Service Interface
5

6
```java { .api }
7
interface WxMpGuideService {
8
  // Guide account management
9
  WxMpGuideResult addGuide(WxMpGuideAccount account) throws WxErrorException;
10
  WxMpGuideResult getGuide(String account, String guideOpenid) throws WxErrorException;
11
  WxMpGuideResult updateGuide(WxMpGuideAccount account) throws WxErrorException;
12
  WxMpGuideResult delGuide(String account, String guideOpenid) throws WxErrorException;
13
  WxMpGuideListResult getGuideList(Integer page, Integer num) throws WxErrorException;
14
  
15
  // Guide group management
16
  WxMpGuideGroupResult createGuideGroup(WxMpGuideGroup group) throws WxErrorException;
17
  WxMpGuideGroupResult getGuideGroup(String groupId) throws WxErrorException;
18
  WxMpGuideGroupResult updateGuideGroup(WxMpGuideGroup group) throws WxErrorException;
19
  WxMpGuideResult delGuideGroup(String groupId) throws WxErrorException;
20
  WxMpGuideGroupListResult getGuideGroupList(Integer page, Integer num) throws WxErrorException;
21
  
22
  // Guide configuration
23
  WxMpGuideConfigResult setGuideConfig(WxMpGuideConfig config) throws WxErrorException;
24
  WxMpGuideConfigResult getGuideConfig() throws WxErrorException;
25
  
26
  // QR code for guides
27
  WxMpGuideQrcodeResult genGuideQrcode(String guideAccount, String qrcodeInfo) throws WxErrorException;
28
}
29
```
30

31
## Guide Buyer Service Interface
32

33
```java { .api }
34
interface WxMpGuideBuyerService {
35
  // Buyer management
36
  WxMpGuideBuyerResult addGuideBuyer(WxMpGuideBuyer buyer) throws WxErrorException;
37
  WxMpGuideBuyerResult getGuideBuyer(String guideAccount, String openid) throws WxErrorException;
38
  WxMpGuideBuyerResult updateGuideBuyer(WxMpGuideBuyer buyer) throws WxErrorException;
39
  WxMpGuideBuyerResult delGuideBuyer(String guideAccount, String openid) throws WxErrorException;
40
  WxMpGuideBuyerListResult getGuideBuyerList(String guideAccount, Integer page, Integer num) throws WxErrorException;
41
  
42
  // Buyer relation management
43
  WxMpGuideBuyerRelationResult getGuideBuyerRelation(String guideAccount, String openid) throws WxErrorException;
44
  WxMpGuideBuyerRelationListResult getGuideBuyerRelationList(String guideAccount, Integer page, Integer num) throws WxErrorException;
45
  
46
  // Buyer statistics
47
  WxMpGuideBuyerChatRecordResult getGuideBuyerChatRecord(String guideAccount, String openid, 
48
                                                        Integer beginTime, Integer endTime, 
49
                                                        Integer page, Integer num) throws WxErrorException;
50
}
51
```
52

53
## Guide Tag Service Interface
54

55
```java { .api }
56
interface WxMpGuideTagService {
57
  // Tag management
58
  WxMpGuideTagResult newGuideTagOption(WxMpGuideTagOption tagOption) throws WxErrorException;
59
  WxMpGuideTagResult getGuideTagOption() throws WxErrorException;
60
  WxMpGuideTagResult delGuideTagOption(String optionName) throws WxErrorException;
61
  
62
  // Buyer tagging
63
  WxMpGuideTagResult addGuideBuyerTag(String guideAccount, String openid, List<String> tagValueList) throws WxErrorException;
64
  WxMpGuideTagResult getGuideBuyerTag(String guideAccount, String openid) throws WxErrorException;
65
  WxMpGuideTagResult queryGuideBuyerByTag(WxMpGuideBuyerTagQuery query) throws WxErrorException;
66
  WxMpGuideTagResult delGuideBuyerTag(String guideAccount, String openid, String tagValue) throws WxErrorException;
67
}
68
```
69

70
## Guide Material Service Interface
71

72
```java { .api }
73
interface WxMpGuideMaterialService {
74
  // Material management
75
  WxMpGuideMaterialResult addGuideMaterial(WxMpGuideMaterial material) throws WxErrorException;
76
  WxMpGuideMaterialResult getGuideMaterial(String type, Integer page, Integer num) throws WxErrorException;
77
  WxMpGuideMaterialResult delGuideMaterial(String mediaId) throws WxErrorException;
78
}
79
```
80

81
## Guide Mass Job Service Interface
82

83
```java { .api }
84
interface WxMpGuideMassedJobService {
85
  // Mass job management
86
  WxMpGuideMassedJobResult addGuideMassedJob(WxMpGuideMassedJob job) throws WxErrorException;
87
  WxMpGuideMassedJobResult getGuideMassedJob(String jobId) throws WxErrorException;
88
  WxMpGuideMassedJobResult updateGuideMassedJob(WxMpGuideMassedJob job) throws WxErrorException;
89
  WxMpGuideMassedJobListResult getGuideMassedJobList(String guideAccount, Integer page, Integer num) throws WxErrorException;
90
}
91
```
92

93
## Data Models
94

95
### Guide Account
96

97
```java { .api }
98
class WxMpGuideAccount implements Serializable {
99
  private String account;
100
  private String guideHeadimgUrl;
101
  private String guideNickname;
102
  private String guideOpenid;
103
  private String createTime;
104
  private String updateTime;
105
  
106
  public String getAccount();
107
  public void setAccount(String account);
108
  public String getGuideHeadimgUrl();
109
  public void setGuideHeadimgUrl(String guideHeadimgUrl);
110
  public String getGuideNickname();
111
  public void setGuideNickname(String guideNickname);
112
  public String getGuideOpenid();
113
  public void setGuideOpenid(String guideOpenid);
114
  public String getCreateTime();
115
  public void setCreateTime(String createTime);
116
  public String getUpdateTime();
117
  public void setUpdateTime(String updateTime);
118
}
119
```
120

121
### Guide Buyer
122

123
```java { .api }
124
class WxMpGuideBuyer implements Serializable {
125
  private String guideAccount;
126
  private String openid;
127
  private String buyerNickname;
128
  private String createTime;
129
  private String updateTime;
130
  
131
  public String getGuideAccount();
132
  public void setGuideAccount(String guideAccount);
133
  public String getOpenid();
134
  public void setOpenid(String openid);
135
  public String getBuyerNickname();
136
  public void setBuyerNickname(String buyerNickname);
137
  public String getCreateTime();
138
  public void setCreateTime(String createTime);
139
  public String getUpdateTime();
140
  public void setUpdateTime(String updateTime);
141
}
142
```
143

144
### Guide Group
145

146
```java { .api }
147
class WxMpGuideGroup implements Serializable {
148
  private String groupId;
149
  private String groupName;
150
  private String createTime;
151
  private String updateTime;
152
  
153
  public String getGroupId();
154
  public void setGroupId(String groupId);
155
  public String getGroupName();
156
  public void setGroupName(String groupName);
157
  public String getCreateTime();
158
  public void setCreateTime(String createTime);
159
  public String getUpdateTime();
160
  public void setUpdateTime(String updateTime);
161
}
162
```
163

164
### Guide Material
165

166
```java { .api }
167
class WxMpGuideMaterial implements Serializable {
168
  private String type;
169
  private String mediaId;
170
  private String title;
171
  private String picUrl;
172
  private String word;
173
  
174
  public String getType();
175
  public void setType(String type);
176
  public String getMediaId();
177
  public void setMediaId(String mediaId);
178
  public String getTitle();
179
  public void setTitle(String title);
180
  public String getPicUrl();
181
  public void setPicUrl(String picUrl);
182
  public String getWord();
183
  public void setWord(String word);
184
}
185
```
186

187
### Guide Mass Job
188

189
```java { .api }
190
class WxMpGuideMassedJob implements Serializable {
191
  private String jobId;
192
  private String guideAccount;
193
  private String taskName;
194
  private String taskRemark;
195
  private Integer pushTime;
196
  private Integer finishTime;
197
  private Integer taskStatus;
198
  
199
  public String getJobId();
200
  public void setJobId(String jobId);
201
  public String getGuideAccount();
202
  public void setGuideAccount(String guideAccount);
203
  public String getTaskName();
204
  public void setTaskName(String taskName);
205
  public String getTaskRemark();
206
  public void setTaskRemark(String taskRemark);
207
  public Integer getPushTime();
208
  public void setPushTime(Integer pushTime);
209
  public Integer getFinishTime();
210
  public void setFinishTime(Integer finishTime);
211
  public Integer getTaskStatus();
212
  public void setTaskStatus(Integer taskStatus);
213
}
214
```
215

216
## Usage Examples
217

218
### Guide Account Management
219

220
```java
221
// Add new guide
222
WxMpGuideAccount newGuide = new WxMpGuideAccount();
223
newGuide.setAccount("guide_account_001");
224
newGuide.setGuideNickname("Shopping Guide Alice");
225
newGuide.setGuideOpenid("guide_openid_123");
226

227
WxMpGuideResult result = wxService.getGuideService().addGuide(newGuide);
228
if (result.getErrcode() == 0) {
229
    System.out.println("Guide added successfully");
230
}
231

232
// Get guide information
233
WxMpGuideResult guideInfo = wxService.getGuideService()
234
    .getGuide("guide_account_001", "guide_openid_123");
235

236
// Update guide information
237
WxMpGuideAccount updateGuide = new WxMpGuideAccount();
238
updateGuide.setAccount("guide_account_001");
239
updateGuide.setGuideNickname("Senior Shopping Guide Alice");
240

241
wxService.getGuideService().updateGuide(updateGuide);
242

243
// Get all guides
244
WxMpGuideListResult guideList = wxService.getGuideService().getGuideList(1, 20);
245
for (WxMpGuideAccount guide : guideList.getGuideList()) {
246
    System.out.println("Guide: " + guide.getGuideNickname());
247
}
248
```
249

250
### Buyer Management
251

252
```java
253
// Add buyer to guide
254
WxMpGuideBuyer newBuyer = new WxMpGuideBuyer();
255
newBuyer.setGuideAccount("guide_account_001");
256
newBuyer.setOpenid("buyer_openid_456");
257
newBuyer.setBuyerNickname("Customer Bob");
258

259
WxMpGuideBuyerResult buyerResult = wxService.getGuideBuyerService().addGuideBuyer(newBuyer);
260

261
// Get buyer information
262
WxMpGuideBuyerResult buyerInfo = wxService.getGuideBuyerService()
263
    .getGuideBuyer("guide_account_001", "buyer_openid_456");
264

265
// Get all buyers for a guide
266
WxMpGuideBuyerListResult buyerList = wxService.getGuideBuyerService()
267
    .getGuideBuyerList("guide_account_001", 1, 20);
268

269
System.out.println("Total buyers: " + buyerList.getTotalNum());
270
for (WxMpGuideBuyer buyer : buyerList.getBuyerList()) {
271
    System.out.println("Buyer: " + buyer.getBuyerNickname());
272
}
273
```
274

275
### Tag Management
276

277
```java
278
// Create tag option
279
WxMpGuideTagOption tagOption = new WxMpGuideTagOption();
280
tagOption.setOptionName("VIP Level");
281
tagOption.setOptionValueList(Arrays.asList("Gold", "Silver", "Bronze"));
282

283
WxMpGuideTagResult tagResult = wxService.getGuideTagService().newGuideTagOption(tagOption);
284

285
// Add tag to buyer
286
List<String> tags = Arrays.asList("Gold", "Premium Customer");
287
wxService.getGuideTagService().addGuideBuyerTag("guide_account_001", "buyer_openid_456", tags);
288

289
// Query buyers by tag
290
WxMpGuideBuyerTagQuery query = new WxMpGuideBuyerTagQuery();
291
query.setGuideAccount("guide_account_001");
292
query.setTagValue("Gold");
293
query.setPage(1);
294
query.setNum(20);
295

296
WxMpGuideTagResult taggedBuyers = wxService.getGuideTagService().queryGuideBuyerByTag(query);
297
```
298

299
### Material Management
300

301
```java
302
// Add guide material
303
WxMpGuideMaterial material = new WxMpGuideMaterial();
304
material.setType("image");
305
material.setMediaId("media_id_123");
306
material.setTitle("Product Showcase");
307

308
WxMpGuideMaterialResult materialResult = wxService.getGuideMaterialService().addGuideMaterial(material);
309

310
// Get materials by type
311
WxMpGuideMaterialResult materials = wxService.getGuideMaterialService()
312
    .getGuideMaterial("image", 1, 20);
313

314
for (WxMpGuideMaterial mat : materials.getMaterialList()) {
315
    System.out.println("Material: " + mat.getTitle());
316
}
317
```
318

319
### Mass Job Operations
320

321
```java
322
// Create mass job
323
WxMpGuideMassedJob job = new WxMpGuideMassedJob();
324
job.setGuideAccount("guide_account_001");
325
job.setTaskName("Weekly Product Update");
326
job.setTaskRemark("Send weekly product updates to all VIP customers");
327
job.setPushTime((int) (System.currentTimeMillis() / 1000));
328

329
WxMpGuideMassedJobResult jobResult = wxService.getGuideMassedJobService().addGuideMassedJob(job);
330
String jobId = jobResult.getJobId();
331

332
// Check job status
333
WxMpGuideMassedJobResult jobStatus = wxService.getGuideMassedJobService().getGuideMassedJob(jobId);
334
System.out.println("Job status: " + jobStatus.getJob().getTaskStatus());
335

336
// Get all jobs for a guide
337
WxMpGuideMassedJobListResult jobList = wxService.getGuideMassedJobService()
338
    .getGuideMassedJobList("guide_account_001", 1, 20);
339

340
for (WxMpGuideMassedJob jobItem : jobList.getJobList()) {
341
    System.out.println("Job: " + jobItem.getTaskName() + " - Status: " + jobItem.getTaskStatus());
342
}
343
```
344

345
## Guide Material Types
346

347
- `image` - Image materials
348
- `word` - Text materials  
349
- `link` - Link materials
350
- `miniprogram` - Mini program materials
351
- `card` - Card materials
352

353
## Job Status Values
354

355
- `1` - Pending
356
- `2` - Running
357
- `3` - Completed
358
- `4` - Failed
359
- `5` - Cancelled
360

361
## Best Practices
362

363
1. **Account Management**: Use descriptive account names for easy identification
364
2. **Buyer Segmentation**: Use tags effectively to segment buyers for targeted campaigns
365
3. **Material Organization**: Keep materials organized by type and regularly clean up unused items
366
4. **Mass Jobs**: Schedule mass jobs during optimal engagement times
367
5. **Performance Monitoring**: Regularly check job completion rates and buyer engagement
368
6. **Tag Strategy**: Create a consistent tagging strategy across all guides
369
7. **Data Analysis**: Use buyer relation data to improve guide performance
370

371
## Error Handling
372

373
```java
374
try {
375
    WxMpGuideResult result = wxService.getGuideService().addGuide(newGuide);
376
    if (result.getErrcode() != 0) {
377
        System.err.println("Guide operation failed: " + result.getErrmsg());
378
    }
379
} catch (WxErrorException e) {
380
    int errorCode = e.getError().getErrorCode();
381
    
382
    switch (errorCode) {
383
        case 40013:
384
            System.err.println("Invalid AppID");
385
            break;
386
        case 45009:
387
            System.err.println("API rate limit exceeded");
388
            break;
389
        case 47001:
390
            System.err.println("Invalid guide account");
391
            break;
392
        default:
393
            System.err.println("Guide service error: " + e.getError().getErrorMsg());
394
    }
395
}
396
```