获取 Amazon ASIN 已完成任务列表

接口说明

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

如果你使用标准投递方式创建任务，且未设置 postback_url，可以通过本接口获取所有已完成任务的 id，随后再调用对应的 Task GET 结果接口拉取。

如需了解任务完成后的回调与拉取机制，可参考帮助文档。

适用路径

获取 Amazon ASIN 已完成任务列表：

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

此外，平台 API 还支持以下容路径：

• 按指定搜索引擎获取已完成任务：GET /v3/merchant/$se/tasks_ready
• 获取 Merchant API 已完成任务：GET /v3/merchant/tasks_ready

处理机制与使用限制

• 本接口返回已完成且尚未被获取结果的任务；
• 每个任务会一直保留在列表中，直到你成功获取结果；
• 单次调用最多可返回近 3 天完成的 1000 个任务；
• 每分钟最多调用 20 次；
• 完成后 3 天仍未拉取的任务，不会再出现在列表中；
• 已经拉取过结果的任务，不会再次出现在列表中。

postback_url

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

只有在以下，该任务才可能出现在本接口返回中：

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

高并发场景说明

由于平台架构特性，已完成任务队列的更新会有轻微延迟。对于高吞吐场景，如果你的系统需要每分钟处理 1000 个任务，建议优使用 pingback/postback 机制，本接口更适合作为：

• 补拉已完成任务 ID；
• 获取回调失败任务的 ID；
• 底对账。

计费说明

接收本接口返回结果不额外收费。

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

请求信息

请求方法

GET

请求地址

https://api.seermartech.cn/v3/merchant/amazon/asin/tasks_ready

请求头

名称	类型	填	说明
Authorization	string	是	使用 Bearer Token：Bearer smt_live_YOUR_KEY
Content-Type	string	是	固定为 application/json

响应结构

接口返回 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	任务数组

建议在接时对 status_code、status_message 以及任务级错误做完善的异常处理。

tasks[] 字段

字段	类型	说明
id	string	当前任务标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态说明
time	string	任务执行时间，单位秒
cost	float	该任务成本，单位 USD
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	URL 中传的参数信息
result	array	已完成任务结果列表

tasks[].result[] 字段

字段	类型	说明
id	string	已完成任务的任务 ID，UUID 格式
se	string	创建任务时指定的搜索引擎
se_type	string	搜索引擎类型；该接口中为 shopping
date_posted	string	任务提交时间，UTC 格式
tag	string	自定义任务标识
endpoint_advanced	string	获取 Amazon ASIN Advanced 结果的接口地址
endpoint_html	string	获取 Amazon ASIN HTML 结果的接口地址

调用示例

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"
}

# 获取已完成但尚未拉取的 Amazon ASIN 任务列表
response = requests.get(url, headers=headers)
result = response.json

# 建议结合 /v3/appendix/errors 处理状态码
if result.get("status_code") == 20000:
 print(result)
 # 可继续读取 result 中的 endpoint_advanced / endpoint_html 拉取
else:
 print(f'error. Code: {result.get("status_code")} Message: {result.get("status_message")}')

TypeScript

import axios from "axios";

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

 const result = response.data;
 console.log(result);
 } catch (error) {
 console.error(error);
 }
}

getAmazonAsinTasksReady;

响应示例

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

使用建议

1. 调用本接口获取已完成任务的 id；
2. 从 result 中读取任务条目；
3. 根据返回的 endpoint_advanced 或 endpoint_html 调用对应结果接口；
4. 如果你的系统依赖实时处理，建议优使用回调机制，本接口用于补偿拉取与失败重试。

错误处理

你需要重点处理以下两层状态：

• 接口级状态：顶层 status_code 和 status_message
• 任务级状态：tasks[].status_code 和 tasks[].status_message

完整错误码与说明可参考：

• /v3/appendix/errors

建议至少覆盖以下：

• 鉴权失败；
• 请求频率限；
• 任务列表为空；
• 下游回调失败后需要重新拉取；
• 单个任务返回异常状态码。

实用场景

• 补拉漏接回调的任务：当业务系统未成功接收回调时，定时轮询本接口找回已完成任务 ID，结果丢失。
• 批量回收结果：获取最近完成的 Amazon ASIN 任务列表，再按 endpoint_advanced 或 endpoint_html 批量拉取，提高结果采集效率。
• 对账任务执行状态：将已创建任务与本接口返回的完成列表做比对，快速识别未完成、已完成但未库的任务。
• 底处理高可靠采集链路：将本接口作为 postback 机制的补偿通道，降低网络抖动或服务异常导致的数据遗漏风险。
• 筛查回调失败任务：针对了 postback_url 的系统，定位因回调失败而重新拉取列表的任务，便于自动重试与告警。