海关数据

海关数据通过 REST API 和 MCP 提供，可以按公司、产品、HS 编码和国家查询进出口记录。这一页列出 7 个查询、请求参数和计费规则；单价统一写在 额度如何计算。

可以查询什么

查询	返回内容	端点
公司名称解析	匹配到的公司与可查到的记录数、最近交易日期（免费）	POST /v1/customs/company-candidates
发现公司	按进口或出口方向、产品、HS 编码、国家、日期筛出的公司及贸易汇总	POST /v1/customs/discover-companies
贸易对手方	一家公司的对手方列表	POST /v1/customs/counterparties
HS 品类分布	一家公司按 HS 品类的贸易占比	POST /v1/customs/categories
贸易趋势	按月、季或年的贸易额与数量趋势	POST /v1/customs/trend
来源与去向国家	一家公司的进出口国家分布	POST /v1/customs/countries
综合报告	把对手方、品类、趋势、国家四个维度合成一份报告	POST /v1/customs/full-report

MCP 服务提供同样的 7 个查询，工具名带统一前缀，名称里包含对应的查询，例如 customs_counterparties。

请求参数

参数	说明
name（公司名称解析）或 companyName（其他查询）	公司名称，最多 512 个字符
role（公司名称解析）或 companyRole（其他查询）	importer 或 exporter
startDate、endDate	YYYY-MM-DD；两个日期之间的跨度不超过 365 天
hsCode	单个 HS 编码，2、4、6、8 或 10 位数字
product、productDescription	产品描述，最多 256 个字符
originCountryCode、destinationCountryCode	ISO 3166-1 三位国家代码，大写，例如 CHN、DEU
filters	公司级查询的筛选对象，可包含 hsCode、productDescription、originCountryCode、destinationCountryCode
periodUnit	趋势查询用：month、quarter 或 year
page、pageSize	page 1–1000；pageSize 1–20
sortBy、sortOrder	trade_count、amount_usd、quantity、weight；desc 或 asc

参数不合法时返回 400，code 是 invalid_request。

计费

• 公司名称解析免费。
• 其他查询按返回的行数计费：没有返回行就不收费。
• 查询前按 pageSize 预留；综合报告按四个部分分别预留。结束后按实际返回行数结算，多预留的部分退回。
• 计费查询必须带 Idempotency-Key 请求头；MCP 工具用 idempotency_key 参数。用同一个键重试不会重复扣费。
• 额度不足返回 402，code 是 insufficient_credits。

结果

分页的行查询（发现公司、贸易对手方、HS 品类分布、贸易趋势、来源与去向国家）返回 status、page、pageSize、totalRows、hasMore、costUnits、latencyMs 和 provenance。公司名称解析返回 candidates 列表，以及 status、costUnits、latencyMs 和 provenance。综合报告返回四个部分，以及公司、日期、costUnits、latencyMs 和 provenance。

其中 costUnits 是本次计费的行数。每条记录带来源信息，便于核对数据从哪里来。

什么时候不可用

• 数据源没有配置或暂时不可用时，接口返回 503（provider_unavailable）或 502，并且不扣额度。
• 目标客户的搜索计划里，海关获客未启用或数据源未配置时，海关记录 渠道显示 不可用，开关不可启用，因此不会产生费用。
• 综合报告在一次调用里取四个维度；调用失败时整次查询的预留全部退回。

示例

公司名称解析（免费）：

curl "https://www.renewsell.com/v1/customs/company-candidates" \
  -H "Authorization: Bearer $RENEWSELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Siemens","role":"exporter"}'

趋势查询（计费，需要幂等键）：

curl "https://www.renewsell.com/v1/customs/trend" \
  -H "Authorization: Bearer $RENEWSELL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: trend-2026-10-23-001" \
  -d '{"companyName":"Siemens","companyRole":"exporter","startDate":"2026-01-01","endDate":"2026-10-01","filters":{},"periodUnit":"month","page":1,"pageSize":20}'

相关

• 额度如何计算
• REST API 概览
• MCP 服务