获取 Amazon 商品已完成任务列表

接口说明

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

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

对于 Amazon 商品任务，可使用以下接口：

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

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

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

，$se 代表搜索引擎名称。

使用说明

• 本接口返回的是最近三天已完成且尚未被获取的任务。
• 每次调用最多返回 1000 个任务。
• 调用频率上限为 每分钟 20 次。
• 已被成功拉取的任务，不会再次出现在列表中。
• 任务完成后 三天仍未拉取，也不会再出现在列表中。

postback_url 的说明

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

只有在以下，任务才可能出现在本列表中：

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

高并发场景建议

由于平台架构特性，已完成任务队列的更新会有轻微延迟。对于高并发任务采集场景，如果你的系统需要每分钟处理 1000 个任务，建议优使用回调机制将本接口用于补偿获取回调失败任务的 ID。

计费说明

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

• 参考价约 ¥0.0000 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求示例

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)
result = response.json

if result.get("status_code") == 20000:
 print(result)
else:
 print(f"error. Code: {result.get('status_code')} Message: {result.get('status_message')}")

TypeScript

import axios from "axios";

// 获取已完成但尚未拉取的 Amazon 商品任务列表
axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/merchant/amazon/products/tasks_ready",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
}).then(function (response) {
 const result = response.data;
 console.log(result);
}).catch(function (error) {
 console.log(error);
});

响应结构

服务端返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段名	类型	说明
version	string	API 当前版本号
status_code	integer	通用状态码，完整列表见 /v3/appendix/errors
status_message	string	通用状态信息，完整列表见 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次请求总费用，USD
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
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	请求 URL 中传的参数
result	array	结果数组

tasks[].result[] 字段

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

响应示例

{
 "version": "0.1.20200416",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2228 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "products",
 "api": "merchant",
 "function": "products",
 "se": "amazon"
 },
 "result": []
 }
 ]
}

结果获取流程建议

推荐按以下流程使用本接口：

1. 提交 Amazon 商品任务；
2. 轮询 /v3/merchant/amazon/products/tasks_ready；
3. 获取已完成任务的 id；
4. 使用对应的 Task GET 结果接口拉取任务；
5. 将已获取结果库，重复处理。

错误处理建议

请务根据返回的 status_code 和 status_message 做异常处理，特别以下：

• 请求频率限；
• 认证失败；
• 任务结果已过期；
• 任务已被拉取，不再出现在完成列表中；
• 回调失败导致任务补偿拉取列表。

错误码完整列表可参考：

/v3/appendix/errors

实用场景

• 轮询已完成任务：批量获取最近完成但尚未消费的 Amazon 商品任务 ID，构建稳定的结果采集流程。
• 补偿回调失败任务：当业务系统未成功接收 postback_url 回调时，通过本接口找回漏掉的任务并补拉结果。
• 搭建任务消费队列：将返回的任务 ID 写消息队列或调度系统，提升商品数据采集链路的自动化程度。
• 监控任务产出效率：结合完成任务数量、时间窗口和后续结果拉取，评估采集任务执行吞吐与稳定性。
• 理积压未消费任务：定期扫描三天未拉取的已完成任务，结果过期丢失。