获取 Google Shopping 商品已完成任务

GET /v3/merchant/google/products/tasks_ready

本接口使用 GET 方法，请求路径为：

GET https://api.seermartech.cn/v3/merchant/google/products/tasks_ready

用于获取 Google Shopping 商品任务中已完成但尚未领取结果的任务列表。对于未设置 postback_url 的标准任务，可通过本接口获取已完成任务的 id，再调用对应的任务结果接口获取。

> 提示：已完成任务队列可能存在少量更新延迟。若系统每分钟需要领取 1000 个任务，建议优使用回调通知机制；本接口可用于补查询回调失败的任务。

请求路径

获取指定搜索引擎的已完成任务：

GET https://api.seermartech.cn/v3/merchant/{se}/tasks_ready

获取 Merchant API 下所有已完成任务：

GET https://api.seermartech.cn/v3/merchant/tasks_ready

，{se} 为搜索引擎名称，例如 google。

计费与调用限制

• 获取已完成任务列表不产生额外费用。
• 每个任务在成功领取前都会保留在列表中。
• 每分钟最多调用 20 次。
• 每次调用最多返回 1000 个任务。
• 接口返回最近 3 天完成且尚未领取的任务。
• 任务完成 3 天仍未领取后，将从列表中移除。
• 如果创建任务时设置了 postback_url，任务通常不会出现在本列表中。
• 只有当平台向回调地址发送请求失败，且目标服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在列表中。

本接口本身不收取任务结果查询费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应结构

接口返回 JSON 数据，顶层 tasks 数组。每个数组代表一个已完成任务及结果领取信息。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	请求级状态码。完整状态码请参考 /v3/appendix/errors
status_message	string	请求级说明信息。完整说明请参考 /v3/appendix/errors
time	string	请求执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	已完成任务列表

tasks 数组字段

字段	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，通常在 10000-60000 范围。完整状态码请参考 /v3/appendix/errors
status_message	string	任务状态说明
time	string	任务执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的数量
path	array	用于领取任务结果的 URL 路径信息
data	object	创建任务时传的请求参数信息
result	array	已完成任务信息数组

result 数组字段

字段	类型	说明
id	string	已完成任务的唯一标识，UUID 格式
se	string	创建任务时指定的搜索引擎
se_type	string	搜索引擎类型，例如 products
date_posted	string	任务提交时间，使用 UTC 格式
tag	string	用户自定义任务标识
endpoint_advanced	string	获取 Google Shopping Products Advanced 任务结果的 URL
endpoint_html	string	获取 Google Shopping Products HTML 任务结果的 URL

请求示例

cURL

curl --location --request GET \
  "https://api.seermartech.cn/v3/merchant/google/products/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/products/tasks_ready"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

# 获取 Google Shopping 商品已完成任务
response = requests.get(url, headers=headers)

if response.status_code == 200:
    result = response.json()
    if result.get("status_code") == 20000:
        print(result)
    else:
        print(
            "接口错误：Code=%s Message=%s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 错误：", response.status_code)

TypeScript

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/merchant/google/products/tasks_ready",
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    // 处理网络或接口异常
    console.error(error.response?.data || error.message);
  });

响应示例

{
  "version": "0.1.20200416",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2543 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1234 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "google",
        "products",
        "tasks_ready"
      ],
      "data": {
        "se_type": "products",
        "api": "merchant",
        "function": "products",
        "se": "google"
      },
      "result": [
        {
          "id": "01234567-89ab-cdef-0123-456789abcdef",
          "se": "google",
          "se_type": "products",
          "date_posted": "2024-01-15 10:30:00 +00:00",
          "tag": "shopping_batch_001",
          "endpoint_advanced": "/v3/merchant/google/products/task_get/advanced",
          "endpoint_html": "/v3/merchant/google/products/task_get/html"
        }
      ]
    }
  ]
}

处理建议

1. 成功获取任务列表后，保存每个任务的 id。
2. 根据 endpoint_advanced 或 endpoint_html 调用对应的任务结果接口。
3. 任务结果成功领取后，该任务会从已完成任务列表中移除。
4. 对 status_code 不为 20000 的任务执行重试、记录或人工排查。
5. 对高并发任务领取场景进行限流，每分钟 20 次的调用限制。

实用场景

• 轮询已完成商品任务：定期获取 Google Shopping 商品采集任务的 id，及时结果处理流程，减少任务状态管理成本。
• 补偿回调失败任务：筛选未成功推送到业务服务器的任务，商品数据因回调异常而丢失。
• 批量领取商品：根据 endpoint_advanced 或 endpoint_html 批量获取商品搜索结果，支持价格、库存和商品信息分析。
• 监控异步任务积压：统计 tasks_count、tasks_error 和任务完成时间，识别采集延迟或接口异常。
• 构建商品数据同步流程：将任务发现、结果领取和数据库串联起来，持续更新电商平台的竞品与商品数据库。