获取 Amazon ASIN 已完成任务

GET /v3/merchant/amazon/asin/tasks_ready

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

/v3/merchant/amazon/asin/tasks_ready

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

对于 Amazon ASIN 任务，可根据返回结果中的以下地址获取任务结果：

• endpoint_advanced：领取 Amazon ASIN Advanced 任务结果
• endpoint_html：领取 Amazon ASIN HTML 任务结果

接口路径

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

GET /v3/merchant/$se/tasks_ready

，$se 为搜索引擎名称。

获取 Merchant API 的已完成任务：

GET /v3/merchant/tasks_ready

注意事项

• 已完成任务队列可能存在少量更新延迟。
• 每分钟最多调用本接口 20 次。
• 每次调用最多返回过去 3 天完成的 1000 个任务。
• 任务在被领取前会持续保留在列表中。
• 任务完成 3 天仍未领取后，将不会继续出现在列表中。
• 已经领取过的任务不会重复返回。
• 如果提交任务时设置了 postback_url，正常完成的任务不会出现在本接口列表中。
• 只有当向 postback_url 推送失败，且目标服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能出现在领取列表中。
• 如果系统每分钟需要领取 1000 个任务，建议优使用 pingback 或 postback 机制；本接口可用于补偿查询推送失败的任务。

计费

调用本接口获取已完成任务列表不收取费用。

任务本身的费用在创建任务时产生。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

本接口为 GET 请求，无请求体和查询参数。

请求示例

cURL

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

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

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

if data.get("status_code") == 20000:
    print(data)
    # 根据 tasks 中的 endpoint_advanced 或 endpoint_html 领取任务结果
else:
    print(
        "请求失败，错误码：%s，错误信息：%s"
        % (data.get("status_code"), data.get("status_message"))
    )

TypeScript

import axios from "axios";

axios
  .get("https://api.seermartech.cn/v3/merchant/amazon/asin/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);
      // 根据 tasks 中的 endpoint_advanced 或 endpoint_html 领取任务结果
    } else {
      console.error(
        `请求失败，错误码：${result.status_code}，错误信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络请求失败：", error.message);
  });

响应结构

接口返回 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	创建任务时传 URL 的参数
result	array	已完成任务信息数组

tasks.result 字段

字段	类型	说明
id	string	已完成任务的唯一标识，UUID 格式
se	string	创建任务时指定的搜索引擎，例如 amazon
se_type	string	搜索引擎类型，Amazon ASIN 任务为 shopping
date_posted	string	任务提交时间，UTC 格式
endpoint_advanced	string	获取 Amazon ASIN Advanced 任务结果的 URL
endpoint_html	string	获取 Amazon ASIN HTML 任务结果的 URL

响应示例

{
  "version": "0.1.20200416",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2756 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "/v3/merchant/amazon/asin/tasks_ready"
      ],
      "data": {
        "se_type": "asin",
        "api": "merchant",
        "function": "asin",
        "se": "amazon"
      },
      "result": [
        {
          "id": "01234567-89ab-cdef-0123-456789abcdef",
          "se": "amazon",
          "se_type": "shopping",
          "date_posted": "2024-04-16 12:00:00 +00:00",
          "endpoint_advanced": "/v3/merchant/amazon/asin/task_get/advanced",
          "endpoint_html": "/v3/merchant/amazon/asin/task_get/html"
        }
      ]
    }
  ]
}

错误处理

建议客户端同时检查以下状态：

1. HTTP 响应状态码；
2. 顶层 status_code；
3. tasks_error；
4. 每个任务对象中的 status_code 和 status_message。

当 status_code 不为 20000 时，应根据 status_message 记录错误并执行重试或人工排查。完整状态码和错误信息参见：

/v3/appendix/errors

实用场景

• 轮询领取任务：定期获取 Amazon ASIN 已完成任务 ID，遗漏未设置回调地址的任务结果。
• 批量领取商品数据：根据 endpoint_advanced 或 endpoint_html 批量获取商品，用于构建商品监控和竞品数据库。
• 补偿失败回调任务：查询因目标服务器异常而未成功推送的任务，降低 postback 失败造成的数据缺失。
• 监控任务处理延迟：结合 date_posted 和任务状态统计完成时间，识别采集链路中的异常延迟。
• 支撑高频商品分析：按时间窗口批量收集已完成任务，为 Amazon 商品排名、价格和库存趋势分析提供数据。