商户任务 ID 列表

POST /v3/merchant/id_list

本接口使用 POST 方法，请求路径为 /v3/merchant/id_list。用于获取指定时间范围创建的商户任务 ID 及数据，结果已完成、成功、失败和未完成的任务。

> 时间范围限制 > > - include_metadata 为 true 时，查询起始时间最多可追溯至当前时间前 1 个月。 > - include_metadata 为 false 时，查询起始时间最多可追溯至当前时间前 6 个月。 > - 单次请求最多返回 1000 个任务 ID。 > - 接口调用频率限制为每分钟最多 10 次。

计费说明

本接口不收取调用费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求

请求地址

text

POST https://api.seermartech.cn/v3/merchant/id_list

所有请求数据使用 UTF-8 编码的 JSON 格式。请求体是 JSON 数组，即使只查询一组条件，也需要使用数组对象。

请求参数

参数名	类型	填	说明
`datetime_from`	string	是	结果筛选的起始时间。<br>当 `include_metadata` 为 `true` 时，最多可查询当前时间前 1 个月；当 `include_metadata` 为 `false` 时，最多可查询当前时间前 6 个月。<br>使用 UTC 时间格式：`yyyy-mm-dd hh-mm-ss +00:00`。示例：`2023-01-15 12:57:46 +00:00`
`datetime_to`	string	是	结果筛选的结束时间，不能晚于当前时间。使用 UTC 时间格式。示例：`2023-01-31 13:57:46 +00:00`
`limit`	integer	否	返回的最大任务数量。默认值为 `1000`，最大值为 `1000`。
`offset`	integer	否	结果偏移量，默认值为 `0`。例如设置为 `10` 时，将跳过结果数组中的前 10 条任务。
`sort`	string	否	按任务执行时间排序。可选值：`asc`、`desc`。默认值为 `asc`。
`include_metadata`	boolean	否	是否在响应中返回任务数据。默认值为 `false`。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/merchant/id_list" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "datetime_from": "2023-01-31 00:00:00 +00:00",
      "datetime_to": "2023-02-01 00:00:00 +00:00",
      "limit": 100,
      "offset": 0,
      "sort": "desc",
      "include_metadata": true
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/merchant/id_list"

payload = [
    {
        "datetime_from": "2023-01-31 00:00:00 +00:00",
        "datetime_to": "2023-02-01 00:00:00 +00:00",
        "limit": 100,
        "offset": 0,
        "sort": "desc",
        "include_metadata": True
    }
]

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：{}，错误信息：{}".format(
            result.get("status_code"),
            result.get("status_message")
        )
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    datetime_from: "2023-01-31 00:00:00 +00:00",
    datetime_to: "2023-02-01 00:00:00 +00:00",
    limit: 100,
    offset: 0,
    sort: "desc",
    include_metadata: true
  }
];

axios.post(
  "https://api.seermartech.cn/v3/merchant/id_list",
  payload,
  {
    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);
});

响应

接口返回 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	本次 POST 请求中提交的参数。
`result`	array	任务结果数组。

`tasks.result` 字段

字段名	类型	说明
`id`	string	任务 ID。
`url`	string	创建该任务时使用的 API URL。
`datetime_posted`	string	任务创建时间，使用 UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`datetime_done`	string	任务完成时间，使用 UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。任务未完成时可能为空。
`status`	string	任务状态说明。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`metadata`	object	创建任务时提交的参数在 `include_metadata` 为 `true` 时返回。

响应示例

json

{
  "version": "0.1.20221214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.4434 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "2f6d7b8e-3e3f-4c2b-9b6c-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "id_list"
      ],
      "data": {
        "api": "merchant",
        "function": "id_list",
        "datetime_from": "2023-01-11 00:00:00 +00:00",
        "datetime_to": "2023-02-10 17:47:00 +00:00",
        "limit": 100,
        "sort": "desc",
        "include_metadata": true
      },
      "result": [
        {
          "id": "8b7f3f4a-7c5e-4b10-a9e2-123456789abc",
          "url": "https://api.seermartech.cn/v3/merchant/id_list",
          "datetime_posted": "2023-01-15 12:57:46 +00:00",
          "datetime_done": "2023-01-15 12:57:47 +00:00",
          "status": "Ok.",
          "cost": 0,
          "metadata": {
            "datetime_from": "2023-01-11 00:00:00 +00:00",
            "datetime_to": "2023-02-10 17:47:00 +00:00",
            "limit": 100,
            "sort": "desc",
            "include_metadata": true
          }
        }
      ]
    }
  ]
}

状态码与错误处理

顶层 status_code 用于判断本次请求是否成功。
tasks_count 表示返回的任务数量。
tasks_error 表示任务级错误数量。
当 tasks_error 大于 0 时，应进一步检查对应任务中的 status_code 和 status_message。
成功响应通常使用状态码 20000。
完整响应码和错误说明请参考 /v3/appendix/errors。

实用场景

回溯指定时间范围的商户任务，批量获取历史任务 ID，便于补偿处理遗漏的数据。
筛选未完成或失败任务，结合任务状态码建立重试队列，提升数据采集任务的成功率。
同步任务数据，通过 include_metadata 获取任务创建参数，方便审计请求来源和复现任务。
分页拉取大量任务记录，使用 limit 与 offset 分批获取任务，适用于后台任务管理和运营报表。
按执行时间排序任务，使用 sort 区分优处理最新任务或最早任务，优化 SEO 数据处理流程。

商户任务 ID 列表 ​

计费说明 ​

请求 ​

请求地址 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应 ​

顶层响应字段 ​

tasks 数组字段 ​

tasks.result 字段 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​