获取 Amazon Products 已完成任务

GET /v3/merchant/amazon/products/tasks_ready

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

/v3/merchant/amazon/products/tasks_ready

用于获取已完成但尚未领取的 Amazon Products 任务列表。使用标准任务提交方式且未设置 postback_url 时，可通过本接口获取已完成任务的 id，再调用对应的任务结果接口获取详细数据。

请求地址

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

也可以使用通用路径获取指定搜索引擎的已完成任务：

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

$se 为搜索引擎名称。

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

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

认证方式

请求头使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY

计费与限制

• 获取任务列表本身不产生额外费用。
• 每个任务在被领取前都会保留在列表中。
• 每分钟最多调用 20 次。
• 每次调用最多返回 1000 个任务。
• 任务完成 3 天仍未领取后，将不会继续出现在列表中。
• 任务队列可能存在少量同步延迟，高并发场景下明显。
• 如果系统需要每分钟领取 1000 个任务，建议使用回调机制；本接口可用于补偿查询回调失败的任务。
• 如果提交任务时指定了 postback_url，任务通常不会出现在已完成任务列表中。只有当回调请求失败，且回调服务器返回的 HTTP 状态码小于 200 或大于 300 时，才可能通过本接口查询到该任务。
• 响应中的 cost 通常为 0。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应字段

接口返回 JSON 数据 tasks 数组。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	请求级状态码。完整错误码请参考 /v3/appendix/errors
status_message	string	请求级提示信息
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 范围
status_message	string	任务状态说明
time	string	任务执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的数量
path	array	任务请求路径
data	object	创建任务时传的请求参数
result	array	已完成任务信息数组

result 数组字段

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

请求示例

cURL

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

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

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

if response.status_code == 200:
    result = response.json()
    if result.get("status_code") == 20000:
        # 处理已完成任务列表
        print(result)
    else:
        print(
            "API 错误：%s %s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 错误：%s" % response.status_code)

TypeScript

import axios from "axios";

async function getAmazonProductsTasksReady() {
  try {
    const response = await axios.get(
      "https://api.seermartech.cn/v3/merchant/amazon/products/tasks_ready",
      {
        headers: {
          Authorization: "Bearer smt_live_YOUR_KEY",
          "Content-Type": "application/json",
        },
      }
    );

    const result = response.data;

    if (result.status_code === 20000) {
      // 处理已完成任务列表
      console.log(result);
    } else {
      console.error(
        `API 错误：${result.status_code} ${result.status_message}`
      );
    }
  } catch (error) {
    console.error("请求失败：", error);
  }
}

getAmazonProductsTasksReady();

响应示例

{
  "version": "0.1.20200416",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2228 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "0325e7c0-0696-438d-9c24-xxxxxxxxxxxx",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1800 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "amazon",
        "products",
        "tasks_ready"
      ],
      "data": {
        "se_type": "products",
        "api": "merchant",
        "function": "products",
        "se": "amazon"
      },
      "result": [
        {
          "id": "0325e7c0-0696-438d-9c24-xxxxxxxxxxxx",
          "se": "amazon",
          "se_type": "organic",
          "date_posted": "2024-04-16 12:00:00 +00:00",
          "tag": "amazon-products-task",
          "endpoint_advanced": "/v3/merchant/amazon/products/task_get/advanced",
          "endpoint_html": "/v3/merchant/amazon/products/task_get/html"
        }
      ]
    }
  ]
}

任务处理流程

1. 通过任务提交接口创建 Amazon Products 任务。
2. 在未设置 postback_url 的，定期调用本接口。
3. 从 tasks 或 result 中读取已完成任务的 id。
4. 根据 endpoint_advanced 或 endpoint_html 调用对应的 Task GET 接口。
5. 成功领取结果后，该任务将从已完成任务列表中移除。

实用场景

• 轮询已完成任务：批量获取 Amazon 商品采集任务的任务 ID，及时触发结果下载并减少人工查询。
• 补偿失败回调任务：定期检查未成功回调的任务，商品数据因网络异常或服务端障丢失。
• 管理大批量商品监控：按批次读取已完成任务，持续更新商品价格、排名、库存等监控数据。
• 构建异步数据流水线：将任务状态查询与结果获取拆分，提升 Amazon 商品数据采集系统的吞吐量和稳定性。