Merchant 任务 ID 列表

接口说明

/v3/merchant/id_list 用于获取指定时间范围创建的 Merchant 任务 ID 列表及数据，已成功完成和未完成的任务。

需要注意：

• 可查询的时间范围最长为当前调用时间向前 6 个月
• 当 include_metadata=true 时可获取最近 1 个月任务的数据
• 单次调用最多返回 1000 个任务 ID
• 调用频率限制：每分钟最多 10 次
• 本接口不收费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求信息

请求方式： POST请求地址： https://api.seermartech.cn/v3/merchant/id_list

POST 请求体需使用 JSON 数组格式：

[
 {
 "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
 }
]

请求参数

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

响应结构

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

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，由平台 API 生成，范围通常为 10000-60000
status_message	string	任务状态信息
time	string	任务执行时间，单位秒
cost	float	单个任务成本，单位 USD
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	与提交请求时相同的参数集合
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
metadata	object	任务数据，创建任务时传的参数；在 include_metadata=true 且时间范围满足要求时可用

调用示例

cURL

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

import requests

url = "https://api.seermartech.cn/v3/merchant/id_list"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
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
 }
]

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

TypeScript

import axios from "axios";

const postArray = [
 {
 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({
 method: "post",
 url: "https://api.seermartech.cn/v3/merchant/id_list",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
}).then((response) => {
 // 响应结果
 console.log(response.data);
}).catch((error) => {
 console.error(error);
});

响应示例

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.4434 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "merchant",
 "function": "id_list",
 "datetime_from": "2023-01-11 00:00:00 +02:00",
 "datetime_to": "2023-02-10 17:47:00 +02:00",
 "limit": 100,
 "sort": "desc",
 "include_metadata": true
 },
 "result": []
 }
 ]
}

状态码说明

• 顶层 status_code=20000 表示请求成功
• 单个任务下的 status_code 用于表示该任务执行状态
• 完整错误码与状态信息请参考 /v3/appendix/errors

使用注意事项

1. 如果需要返回 metadata，请确保 datetime_from 不早于当前时间前 1 个月
2. 如果需任务 ID 列表，建议将 include_metadata 设为 false，可查询最近 6 个月数据
3. 当返回结果较多时，可通过 limit + offset 分页拉取
4. 若需按最近任务优查看，建议使用 sort="desc"

实用场景

• 追踪任务历史：按时间范围拉取 Merchant 任务 ID，快速核对某一批次任务是否已创建并处理流程
• 补拉任务结果：通过 ID 列表找到未库或处理中断的任务，再按任务 ID 逐个补拉，减少数据缺口
• 审计任务提交参数：开启 include_metadata 后回查历史任务参，验证不同采集批次的是否一致
• 监控任务完成：结合 datetime_posted、datetime_done 和 status 字段，统计任务完成率与处理时效
• 实现分页归档：通过 limit 与 offset 分页遍历近 6 个月任务，构建任务台账或报表数据源