Google Shopping 商品信息已完成任务

GET /v3/merchant/google/product_info/tasks_ready

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

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

用于获取 Google Shopping 商品信息任务中已经完成、但尚未被收取的任务列表。通过标准任务提交方式且未设置 postback_url 时，可调用本接口获取已完成任务的 id，再通过对应的任务结果接口获取详细结果。

> 本接口返回的是任务 ID 列表，不直接返回任务结果。获取结果时，请使用任务查询接口。

请求地址

http

GET /v3/merchant/google/product_info/tasks_ready

也可以使用以下通用路径：

http

GET /v3/merchant/$se/tasks_ready

，$se 为搜索引擎名称。

获取 Merchant API 下所有已完成任务时，可使用：

http

GET /v3/merchant/tasks_ready

请求头

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

本接口无需请求体。

处理说明

每个已完成任务会一直保留在列表中，直到被成功收取。
每分钟最多调用本接口 20 次。
每次调用最多返回过去 3 天完成的 1000 个任务。
已被收取的任务不会再次出现在列表中。
任务完成 3 天仍未被收取后，将不会继续保留在列表中。
如果创建任务时设置了 postback_url，正常该任务不会出现在本接口返回列表中。
只有当平台向回调地址推送失败，且回调服务器返回小于 200 或大于 300 的 HTTP 状态码时，该任务才可能出现在已完成任务列表中。
已完成任务队列可能存在少量更新延迟。对于每分钟需要收取 1000 个任务的高并发场景，建议优使用回调机制，并将本接口作为补偿机制，用于查询回调失败的任务 ID。

计费说明

获取已完成任务列表不产生额外费用。
本接口响应中的 cost 通常为 0。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应结构

接口返回 JSON 数据 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	请求级状态码，完整状态码列表请参考错误码文档
`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`
`status_message`	string	任务状态说明
`time`	string	任务处理耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量
`path`	array	请求 URL 路径
`data`	object	创建任务时传的请求参数及 URL 信息
`result`	array	已完成任务信息列表

`result` 数组字段

字段	类型	说明
`id`	string	已完成任务的唯一标识，UUID 格式
`se`	string	创建任务时指定的搜索引擎
`se_type`	string	搜索引擎类型，当前为 `shopping_specifications`
`date_posted`	string	任务提交时间，UTC 格式
`endpoint_advanced`	string	Google Shopping 商品规格高级结果查询地址
`endpoint_html`	string / null	Google Shopping 商品规格 HTML 结果查询地址；该端点不提供 HTML 结果，因此通常为 `null`

请求示例

cURL

bash

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

PHP

php

<?php
$apiUrl = 'https://api.seermartech.cn';
$endpoint = '/v3/merchant/google/product_info/tasks_ready';

$ch = curl_init($apiUrl . $endpoint);

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

$response = curl_exec($ch);

if ($response === false) {
    echo '请求失败：' . curl_error($ch);
} else {
    $result = json_decode($response, true);

    if (($result['status_code'] ?? 0) === 20000) {
        // 处理已完成任务列表
        print_r($result);
    } else {
        echo '错误码：' . ($result['status_code'] ?? '');
        echo '，错误信息：' . ($result['status_message'] ?? '');
    }
}

curl_close($ch);

JavaScript

javascript

const axios = require('axios');

axios({
  method: 'get',
  url: 'https://api.seermartech.cn/v3/merchant/google/product_info/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);
    } else {
      console.error(
        `错误码：${result.status_code}，错误信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error('请求失败：', error.message);
  });

Python

python

import requests

url = "https://api.seermartech.cn/v3/merchant/google/product_info/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;

public static class SeerMarTechDemos
{
    public static async Task GetGoogleProductInfoTasksReady()
    {
        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/google/product_info/tasks_ready"
        );

        var responseText = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            // 处理 JSON 响应
            Console.WriteLine(responseText);
        }
        else
        {
            Console.WriteLine($"HTTP 请求失败：{(int)response.StatusCode}");
            Console.WriteLine(responseText);
        }
    }
}

响应示例

json

{
  "version": "0.1.20220627",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1163 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1000 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "google",
        "product_info",
        "tasks_ready"
      ],
      "data": {
        "se_type": "product_info",
        "api": "merchant",
        "function": "product_info",
        "se": "google"
      },
      "result": [
        {
          "id": "01234567-89ab-cdef-0123-456789abcdef",
          "se": "google",
          "se_type": "shopping_specifications",
          "date_posted": "2024-01-15 10:30:00 +00:00",
          "endpoint_advanced": "/v3/merchant/google/product_info/task_get/advanced",
          "endpoint_html": null
        }
      ]
    }
  ]
}

状态码与异常处理

请在客户端程序中同时检查：

HTTP 响应状态；
顶层 status_code；
tasks_error；
每个任务对象中的 status_code 和 status_message。

建议为任务收取程序增加以下机制：

记录已收取的任务 ID，重复处理；
对暂时性网络错误进行重试；
对 3 天未收取的任务进行监控和告警；
当 tasks_error 大于 0 时，保存异常任务的完整响应；
在高吞吐场景中优使用回调，并定期调用本接口进行失败补偿。

实用场景

轮询已完成任务 ID：批量发现 Google Shopping 商品信息任务的完成状态，驱动后续结果抓取流程。
补偿失败回调任务：定期检查未成功推送到业务服务器的任务，商品数据处理链路出现遗漏。
构建任务调度队列：任务完成时间和任务 ID 拉取处理任务，提升商品信息采集系统的吞吐能力。
监控商品数据采集进度：结合 tasks_count、tasks_error 和任务状态码，统计采集成功率并及时发现异常。
衔接高级商品规格结果：读取 endpoint_advanced，自动获取已完成任务的详细商品规格数据，用于商品目录分析和竞品研究。

Google Shopping 商品信息已完成任务 ​

请求地址 ​

请求头 ​

处理说明 ​

计费说明 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

请求示例 ​

cURL ​

PHP ​

JavaScript ​

Python ​

C# ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​

Google Shopping 商品信息已完成任务

请求地址

请求头

处理说明

计费说明

响应结构

顶层字段

`tasks` 数组字段

`result` 数组字段

请求示例

cURL

PHP

JavaScript

Python

C#

响应示例

状态码与异常处理

实用场景