获取 Amazon Reviews 已完成任务

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

/v3/merchant/amazon/reviews/tasks_ready

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

如果任务设置了 postback_url，通常不会出现在本接口返回列表中。当向你的服务器发送回调失败，且服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在领取列表中。

> 已完成任务队列存在少量同步延迟。若系统需要每分钟领取 1000 个任务，建议优使用回调或推送机制，并将本接口用于补偿获取回调失败任务的 ID。

请求地址

http

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

也可以通过以下路径获取范围的已完成任务：

http

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

：

$se：搜索引擎名称，例如 amazon
Amazon Reviews 的固定路径为 /v3/merchant/amazon/reviews/tasks_ready

计费与领取限制

获取已完成任务列表不收取费用，参考价约 ¥0 / 次。
每个任务会一直保留在列表中，直到被成功领取。
每分钟最多调用 20 次。
每次调用最多返回 1000 个任务。
返回过去 3 天完成且尚未领取的任务。
已完成 3 天仍未领取的任务不会继续保留在列表中。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求头

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

返回结构

接口返回 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`。完整列表请参考 `/v3/appendix/errors`
`status_message`	string	任务状态说明
`time`	string	任务执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果数量
`path`	array	用于领取任务结果的 URL 路径
`data`	object	创建任务时传的请求参数
`result`	array	任务结果信息

`tasks.result` 字段

字段	类型	说明
`id`	string	已完成任务的唯一标识，UUID 格式
`se`	string	创建任务时指定的搜索引擎，例如 `amazon`
`se_type`	string	搜索引擎类型，例如 `reviews`
`date_posted`	string	任务提交时间，UTC 格式
`tag`	string	用户自定义任务标识
`endpoint_advanced`	string	Amazon Reviews Advanced 任务结果领取地址
`endpoint_html`	string	Amazon Reviews HTML 任务结果领取地址

请求示例

cURL

bash

curl --location --request GET \
  "https://api.seermartech.cn/v3/merchant/amazon/reviews/tasks_ready" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

PHP

php

<?php

$apiUrl = 'https://api.seermartech.cn/';
$apiKey = 'smt_live_YOUR_KEY';

$ch = curl_init($apiUrl . 'v3/merchant/amazon/reviews/tasks_ready');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPGET => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}

curl_close($ch);

$result = json_decode($response, true);

// 处理返回结果
print_r($result);

TypeScript

typescript

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/merchant/amazon/reviews/tasks_ready",
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理返回数据
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

Python

python

import requests

url = "https://api.seermartech.cn/v3/merchant/amazon/reviews/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(
        "请求失败，状态码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

C#

csharp

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json.Linq;

namespace SeerMarTechDemos
{
    public static class Demos
    {
        public static async Task GetAmazonReviewsTasksReady()
        {
            using var httpClient = new HttpClient();

            httpClient.DefaultRequestHeaders.Authorization =
                new AuthenticationHeaderValue(
                    "Bearer",
                    "smt_live_YOUR_KEY"
                );

            httpClient.DefaultRequestHeaders.Accept.Add(
                new MediaTypeWithQualityHeaderValue("application/json")
            );

            var response = await httpClient.GetAsync(
                "https://api.seermartech.cn/v3/merchant/amazon/reviews/tasks_ready"
            );

            var content = await response.Content.ReadAsStringAsync();
            var result = JObject.Parse(content);

            if ((int?)result["status_code"] == 20000)
            {
                // 在这里处理已完成任务列表
                Console.WriteLine(result);
            }
            else
            {
                Console.WriteLine(
                    $"请求失败，状态码：{result["status_code"]}，消息：{result["status_message"]}"
                );
            }
        }
    }
}

返回示例

json

{
  "version": "0.1.20220407",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.3481 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "03092354-2806-1234-9f2d-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.2134 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "amazon",
        "reviews",
        "tasks_ready"
      ],
      "data": {
        "se_type": "reviews",
        "api": "merchant",
        "function": "reviews",
        "se": "amazon"
      },
      "result": [
        {
          "id": "03092354-2806-1234-9f2d-123456789abc",
          "se": "amazon",
          "se_type": "reviews",
          "date_posted": "2024-01-15 08:30:00 +00:00",
          "tag": "amazon-review-task-001",
          "endpoint_advanced": "/v3/merchant/amazon/reviews/task_get/advanced",
          "endpoint_html": "/v3/merchant/amazon/reviews/task_get/html"
        }
      ]
    }
  ]
}

任务结果领取

从 tasks.result 中获取任务 ID 及对应的结果领取地址后，可调用 Amazon Reviews 的任务结果接口获取数据：

endpoint_advanced：领取 Advanced 任务结果
endpoint_html：领取 HTML 任务结果

每个任务领取成功后，将从已完成任务列表中移除。建议在业务系统中记录已领取的任务 ID，重复处理。

状态码与异常处理

请根据以下字段判断请求及任务是否成功：

顶层 status_code：判断本次列表请求是否成功。
tasks[].status_code：判断单个任务的状态。
tasks_error：统计返回错误的任务数量。
status_message：获取对应的错误或提示信息。

完整状态码和错误信息请参考：

text

/v3/appendix/errors

建议实现以下异常处理机制：

处理 HTTP 请求时、网络中断和服务端错误。
根据 status_code 区分可重试错误和不可重试错误。
记录已领取的任务 ID，防止重复消费。
对 3 天未领取的任务设置告警，因为这些任务可能不再出现在列表中。
高并发场景遵守每分钟 20 次的调用限制。

实用场景

轮询已完成任务：定时获取 Amazon Reviews 已完成任务 ID，驱动后续结果领取流程，遗漏异步任务。
补偿失败回调任务：筛选因回调请求失败而重新列表的任务，恢复评论数据同步，降低数据丢失风险。
批量采集商品评论：集中领取多个商品的评论任务结果，为评分统计、评论分析和竞品研究提供数据。
监控任务处理状态：结合 tasks_error、status_code 和 status_message 统计异常任务，及时定位采集链路问题。
构建任务消费队列：使用任务 ID 和 date_posted 组织处理队列，支持去重、重试和任务处理进度跟踪。

获取 Amazon Reviews 已完成任务 ​

请求地址 ​

计费与领取限制 ​

请求头 ​

返回结构 ​

顶层字段 ​

tasks 字段 ​

tasks.result 字段 ​

请求示例 ​

cURL ​

PHP ​

TypeScript ​

Python ​

C# ​

返回示例 ​

任务结果领取 ​

状态码与异常处理 ​

实用场景 ​

获取 Amazon Reviews 已完成任务

请求地址

计费与领取限制

请求头

返回结构

顶层字段

`tasks` 字段

`tasks.result` 字段

请求示例

cURL

PHP

TypeScript

Python

C#

返回示例

任务结果领取

状态码与异常处理

实用场景