获取 Google Shopping Sellers 已完成任务列表

接口说明

Tasks Ready 接口用于获取已执行完成但尚未被获取结果的任务列表。

如果你使用标准提交方式，且没有设置 postback_url，可以通过本接口拿到所有已完成任务的 id，然后再调用对应的 Task GET 接口获取详细结果。

接口地址：

GET /v3/merchant/google/sellers/tasks_ready

此外，Merchant 系列也支持以下容路径：

• 指定搜索引擎：GET /v3/merchant/$se/tasks_ready
• 获取 Merchant API 已完成任务：GET /v3/merchant/tasks_ready

使用说明

• 本接口返回的是最近 3 天完成、且尚未被拉取的任务。
• 每次调用最多可返回 1000 个任务。
• 调用频率上限为 20 次/分钟。
• 某个任务只要尚未被采集结果，就会一直保留在列表中。
• 已经拉取过结果的任务，不会再次出现在列表中。
• 完成后 3 天未拉取的任务，也不会再出现在列表中。

postback_url 的注意事项

如果任务提交时设置了 postback_url，该任务通常不会出现在已完成任务列表中。

只有在以下，任务才可能出现在本接口返回中：

• 本平台向你的服务器推送回调失败；
• 你的服务器返回的 HTTP 状态码 小于 200 或大于 300。

高并发场景建议

由于平台架构特性，已完成任务队列的更新会存在轻微延迟。 如果你的系统需要每分钟采集 1000 个任务，建议优使用 pingback/postback 方式，本接口更适合：

• 轮询获取常规完成任务；
• 补捞回调失败的任务 ID。

计费说明

获取已完成任务列表不收取费用。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/merchant/google/sellers/tasks_ready" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

url = "https://api.seermartech.cn/v3/merchant/google/sellers/tasks_ready"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json)

TypeScript

import axios from "axios";

// 获取已完成但尚未拉取的任务列表
axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/merchant/google/sellers/tasks_ready",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	接口整体状态码，完整列表见 /v3/appendix/errors
status_message	string	接口整体状态信息，完整列表见 /v3/appendix/errors
time	string	执行耗时，单位为秒
cost	float	本次请求总费用
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务数组

建议在接时对异常状态和错误码建立完善的处理机制。

tasks 数组字段

字段	类型	说明
id	string	本次任务查询请求的任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表见 /v3/appendix/errors
status_message	string	任务状态说明
time	string	任务执行耗时，单位为秒
cost	float	该任务费用
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	请求 URL 中传的参数
result	array	已完成任务列表

result 数组字段

字段	类型	说明
id	string	已完成任务的任务 ID，UUID 格式
se	string	创建任务时指定的搜索引擎
se_type	string	搜索引擎类型；该接口固定为 shopping
date_posted	string	任务提交时间，UTC 格式
tag	string	用户自定义任务标识
endpoint_advanced	string	获取 Google Shopping Sellers Advanced 结果的 URL
endpoint_html	string	获取 Google Shopping Sellers HTML 结果的 URL

响应示例

{
 "version": "0.1.20200416",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.1667 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "merchant",
 "google",
 "sellers",
 "tasks_ready"
 ],
 "data": {
 "se_type": "sellers",
 "api": "merchant",
 "function": "sellers",
 "se": "google"
 },
 "result": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "se": "google",
 "se_type": "shopping",
 "date_posted": "2024-01-01 12:00:00 +00:00",
 "tag": "example_tag",
 "endpoint_advanced": "https://api.seermartech.cn/v3/merchant/google/sellers/task_get/advanced/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "endpoint_html": "https://api.seermartech.cn/v3/merchant/google/sellers/task_get/html/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 }
 ]
 }
 ]
}

状态码与错误处理

你可以通过以下字段判断请求是否成功：

• 顶层 status_code
• tasks[].status_code

常见处理建议：

• 20000：请求成功；
• 状态码：根据 /v3/appendix/errors 进行错误处理与重试策略设计；
• 若 tasks_error > 0，说明部分任务返回异常，需要逐条检查 tasks的状态字段。

结果获取流程建议

型使用流程如下：

1. 提交 Google Shopping Sellers 任务；
2. 轮询 GET /v3/merchant/google/sellers/tasks_ready；
3. 获取返回结果中的任务 id；
4. 使用 endpoint_advanced 或 endpoint_html 获取结果；
5. 将已获取结果的任务从你的业务队列中标记完成。

实用场景

• 轮询已完成任务：批量获取最近完成的 Sellers 任务 ID，减少逐任务探测的请求开销。
• 补捞回调失败任务：当 postback_url 推送失败时，通过本接口找回遗漏任务，结果丢失。
• 构建异步采集流水线：创建任务、后统一拉取完成列表，适合高并发的商品卖家信息采集流程。
• 追踪任务处理状态：结合 tag 和 date_posted 字段，将平台任务与订单、或采集批次。
• 分流结果拉取方式：根据返回的 endpoint_advanced 与 endpoint_html，按不同业务需求拉取结构化结果或原始 HTML。