SeerMarTech API 文档

主题

获取 Google Shopping Sellers 已完成任务 ​

GET /v3/merchant/google/sellers/tasks_ready

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

text
/v3/merchant/google/sellers/tasks_ready

用于获取已完成但尚未被收取的 Google Shopping Sellers 任务列表。使用标准任务提交方式且未设置 postback_url 时，可通过本接口获取所有已完成任务的 id，然后使用任务结果获取接口收取结果。

> 已完成任务队列可能存在短暂延迟。若系统每分钟需要收取 1000 个任务，建议优使用回调方式接收结果，并将本接口用于查询回调失败的任务。

请求地址 ​

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

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

$se 替换为搜索引擎名称。

获取 Google Shopping Sellers 已完成任务：

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

获取 Merchant API 下所有已完成任务：

http
GET https://api.seermartech.cn/v3/merchant/tasks_ready

计费与调用限制 ​

  • 获取已完成任务列表不产生额外费用。
  • 每个任务会一直保留在列表中，直到被收取。
  • 每分钟最多调用 20 次。
  • 每次调用最多返回过去 3 天完成的 1000 个任务。
  • 已经收取的任务不会再次出现在列表中。
  • 完成后 3 天仍未收取的任务不会出现在列表中。
  • 如果任务设置了 postback_url，任务通常不会出现在本列表中。当平台向您的服务器发送回调失败，且服务器返回的 HTTP 状态码小于 200 或大于 300 时，任务才可能重新出现在列表中。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求示例 ​

cURL ​

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

PHP ​

php
<?php

require('RestClient.php');

$api_url = 'https://api.seermartech.cn/';

// 使用 SeerMarTech API Key 进行 Bearer 认证
$client = new RestClient($api_url, [
    'Authorization' => 'Bearer smt_live_YOUR_KEY',
    'Content-Type' => 'application/json'
]);

try {
    // 获取已完成任务列表
    // GET /v3/merchant/google/sellers/tasks_ready
    $result = $client->get('/v3/merchant/google/sellers/tasks_ready');
    print_r($result);
} catch (RestClientException $e) {
    echo "\n";
    print "HTTP 状态码: {$e->getHttpCode()}\n";
    print "错误码: {$e->getCode()}\n";
    print "错误信息: {$e->getMessage()}\n";
}

TypeScript ​

typescript
import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/merchant/google/sellers/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/google/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:
    data = response.json()
    if data.get("status_code") == 20000:
        print(data)
    else:
        print(
            "接口错误，错误码: %s，信息: %s"
            % (data.get("status_code"), data.get("status_message"))
        )
else:
    print("HTTP 请求失败:", response.status_code, response.text)

C# ​

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

namespace SeerMarTechDemos
{
    public static class Demos
    {
        public static async Task MerchantTasksReady()
        {
            using var httpClient = new HttpClient
            {
                BaseAddress = new Uri("https://api.seermartech.cn/")
            };

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

            // 获取已完成任务列表
            // GET /v3/merchant/google/sellers/tasks_ready
            var response = await httpClient.GetAsync(
                "/v3/merchant/google/sellers/tasks_ready"
            );

            var result = JsonConvert.DeserializeObject<dynamic>(
                await response.Content.ReadAsStringAsync()
            );

            if (result.status_code == 20000)
            {
                Console.WriteLine(result);
            }
            else
            {
                Console.WriteLine(
                    $"错误码: {result.status_code}，信息: {result.status_message}"
                );
            }
        }
    }
}

响应说明 ​

接口返回 JSON 数据 tasks 数组符合条件的已完成任务信息。

顶层字段 ​

字段类型说明
versionstring当前 API 版本
status_codeinteger通用状态码
status_messagestring通用状态信息
timestring接口执行耗时，单位为秒
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务对象数组

任务字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，通常在 10000-60000 范围
status_messagestring任务状态信息
timestring任务执行耗时，单位为秒
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量
patharray请求 URL 路径
dataobject创建任务时传的 URL 参数
resultarray任务结果数组

result 字段 ​

字段类型说明
idstring已完成任务的唯一标识，UUID 格式
sestring创建任务时指定的搜索引擎
se_typestring搜索引擎类型，可能为 shopping
date_postedstring任务提交时间，UTC 格式
tagstring用户自定义任务标识
endpoint_advancedstring用于获取 Google Shopping Sellers Advanced 任务结果的 URL
endpoint_htmlstring用于获取 Google Shopping Sellers HTML 任务结果的 URL

响应示例 ​

json
{
  "version": "0.1.20200416",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.1667 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "98765432-1234-5678-9abc-def012345678",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.8421 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "google",
        "sellers",
        "tasks_ready"
      ],
      "data": {
        "se_type": "sellers",
        "api": "merchant",
        "function": "sellers",
        "se": "google"
      },
      "result": [
        {
          "id": "12345678-1234-5678-9abc-def012345678",
          "se": "google",
          "se_type": "shopping",
          "date_posted": "2024-01-15 10:30:00 +00:00",
          "tag": "seller-task-001",
          "endpoint_advanced": "/v3/merchant/google/sellers/task_get/advanced",
          "endpoint_html": "/v3/merchant/google/sellers/task_get/html"
        }
      ]
    }
  ]
}

状态码与异常处理 ​

  • 顶层 status_code 表示本次 API 请求的整体处理状态。
  • 任务对象中的 status_code 表示单个任务的处理状态。
  • tasks_error 表示返回错误的任务数量。
  • 建议客户端对 HTTP 错误、通用状态码、任务状态码以及空任务列表进行完整处理，并结合 status_message 记录异常原因。

实用场景 ​

  • 轮询已完成任务 ID：在未回调地址的标准任务流程中发现已完成任务，并继续获取任务结果。
  • 补偿回调失败任务：定期查询因业务服务器异常而未成功回调的任务，任务结果丢失。
  • 构建任务消费队列：将返回的任务 ID 写队列，按优级分发给结果获取服务。
  • 监控 Merchant 数据处理进度：通过 tasks_count、tasks_error 和任务状态码统计 Google Shopping Sellers 任务的完成与失败。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API