获取 Amazon Sellers 已完成任务

GET /v3/merchant/amazon/sellers/tasks_ready

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

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

接口说明

“Tasks Ready”接口用于获取已完成但尚未领取结果的 Amazon Sellers 任务列表。

如果使用标准任务提交方式，且未设置 postback_url，可通过本接口获取所有已完成任务的 id，再使用对应的任务结果接口获取详细结果。

此外，本接口也支持以下路径：

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

：

• $se：搜索引擎名称，例如 amazon
• 获取 Merchant API 的已完成任务时，使用 /v3/merchant/tasks_ready

> 注意：由于任务完成队列存在少量同步延迟，本接口不适合高频、大规模任务领取场景。如果系统每分钟需要领取 1000 个任务，建议优使用回调（pingback/postback）机制。本接口可用于补获取回调失败任务的 ID。

计费与调用限制

• 获取已完成任务列表不收取接口调用费用。
• 每个任务会一直保留在列表中，直到被领取。
• 每分钟最多调用 20 次。
• 每次调用最多返回过去 3 天完成的 1000 个任务。
• 已经领取的任务不会再次出现在列表中。
• 完成后 3 天仍未领取的任务将从列表中移除。
• 如果任务设置了 postback_url，正常不会出现在本接口返回列表中。
• 当向回调地址发送请求失败，且回调服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能出现在已完成任务列表中。
• 本接口本身不产生任务费用；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

本接口无需请求体和查询参数。

请求示例

cURL

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

axios
  .get(
    "https://api.seermartech.cn/v3/merchant/amazon/sellers/tasks_ready",
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    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.response?.data || error.message);
  });

响应结构

接口返回 JSON 数据 tasks 是已完成任务的数组。

顶层字段

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

tasks 字段

字段	类型	说明
version	string	当前 API 版本
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	搜索引擎类型，例如 sellers
date_posted	string	任务提交时间，采用 UTC 格式
tag	string	用户自定义任务标识
endpoint_advanced	string	获取 Amazon Sellers Advanced 任务结果的 URL
endpoint_html	string	获取 Amazon Sellers HTML 任务结果的 URL

响应示例

{
  "version": "0.1.20210610",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "2.1736 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "060a3e1e-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.2345 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "amazon",
        "sellers",
        "tasks_ready"
      ],
      "data": {
        "se_type": "sellers",
        "se": "amazon",
        "api": "merchant",
        "function": "sellers"
      },
      "result": [
        {
          "id": "060a3e1e-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "se": "amazon",
          "se_type": "sellers",
          "date_posted": "2024-01-15 10:30:00 +00:00",
          "tag": "seller-task-001",
          "endpoint_advanced": "/v3/merchant/amazon/sellers/task_get/advanced",
          "endpoint_html": "/v3/merchant/amazon/sellers/task_get/html"
        }
      ]
    }
  ]
}

任务结果获取流程

1. 调用 /v3/merchant/amazon/sellers/tasks_ready 获取已完成任务列表。
2. 从返回结果中读取任务 id。
3. 根据任务类型使用 endpoint_advanced 或 endpoint_html 获取任务结果。
4. 成功领取后，该任务将不再出现在后续的 Tasks Ready 列表中。

实用场景

• 轮询已完成任务：定期获取未领取的 Amazon Sellers 任务 ID，确保异步采集结果不会遗漏。
• 补偿回调失败任务：筛选因回调服务器异常而未成功推送的任务，重新触发结果领取流程。
• 控制任务领取频率：每分钟最多 20 次、单次最多 1000 个任务的限制设计调度策略，触发接口限流。
• 区分结果类型：根据 endpoint_advanced 和 endpoint_html 选择对应结果接口，分别处理结构化数据与 HTML 结果。
• 监控异步采集链路：结合 tasks_count、tasks_error 和任务状态码定位任务积压或执行异常。