RevorRevor

海关贸易数据 API

海关 API 提供企业名称候选、交易对手、商品类别、趋势、国家分布和完整贸易报告。所有接口均为异步 POST。Idempotency-Key 可选；需要安全重试时建议发送并复用同一个值。

查询时需要区分两个维度：

  • company_role 表示目标企业在交易中的角色：importer（进口商）或 exporter（出口商）。
  • catalog 表示查询的数据目录：imports（进口记录）或 exports（出口记录）。

两者可以独立组合。例如，查找某出口企业在目的国进口记录中的买家时，可以使用 company_role: exporter 与 catalog: imports。

先解析企业名称

POST/api/v2/customs/company-candidates

企业名称候选用于确认哪个名称在指定时间范围内可以查询到贸易记录。返回的 identity_status: unverified 表示“精确名称可查询”，不代表已经核实法律主体身份。

cURL
curl -X POST "https://revor.ai/api/v2/customs/company-candidates" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=20" \
  -d '{
    "company_name": "Banbros Commercial Inc.",
    "start_date": "2025-08-01",
    "end_date": "2026-07-31",
    "page": 1,
    "page_size": 20,
    "company_role": "exporter",
    "catalog": "imports",
    "country_codes": "IDN"
  }'

company_role 和 catalog 可选，但应同时提供。两者都省略时，接口会检查 importer/imports 与 exporter/exports 两条常用查询组合；只提供其中一个时，另一个按常用组合补全。

字段类型必填说明
company_namestring是待解析的企业名称。
company_rolestring否importer 或 exporter。
catalogstring否imports 或 exports。
start_datedate是YYYY-MM-DD。
end_datedate是YYYY-MM-DD，查询跨度最多一年。
pageinteger否默认 1。
page_sizeinteger否1-20，默认 20。
country_codesstring否一个或多个 ISO 3166-1 alpha-3 国家/地区代码，以逗号分隔，例如 USA,IDN。

查询接口

路径结果说明
/api/v2/customs/counterparties主要交易对手。
/api/v2/customs/categories主要 HS 商品类别。
/api/v2/customs/trends按月、季度或年份聚合趋势。
/api/v2/customs/countries来源国或目的国分布。
/api/v2/customs/trade-reports一次执行以上四个 section，允许部分 section 失败。

这些接口共享同一请求结构：

cURL
curl -X POST "https://revor.ai/api/v2/customs/trade-reports" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=20" \
  -d '{
    "company_name": "BANBROS COMMERCIAL INC",
    "company_role": "importer",
    "catalog": "imports",
    "start_date": "2025-08-01",
    "end_date": "2026-07-31",
    "page": 1,
    "page_size": 20,
    "period_unit": "months",
    "filters": {
      "hs_code": "8429",
      "product_description": "excavator",
      "origin_country_code": "CHN",
      "destination_country_code": "USA"
    }
  }'

共享请求字段

字段类型必填说明
company_namestring是2-300 字符，建议使用候选接口确认后的精确名称。
company_rolestring是importer 或 exporter。
catalogstring否imports 或 exports；表示数据目录，与 company_role 可独立选择。省略时按 company_role 使用常用目录。
start_datedate是YYYY-MM-DD。
end_datedate是YYYY-MM-DD，不得早于 start_date。
pageinteger否1-1000，默认 1。
page_sizeinteger否1-20，默认 20。超出范围会归一到边界值。
period_unitstring否months、quarters、years，默认 months。
filters.hs_codestring否HS Code 过滤。
filters.product_descriptionstring否商品描述过滤。
filters.origin_country_codestring否来源国 ISO 3166-1 alpha-3 代码，例如 CHN。
filters.destination_country_codestring否目的国 ISO 3166-1 alpha-3 代码，例如 USA。

查询日期跨度最多一年。国家/地区代码统一使用三位代码；常见示例包括 USA、CHN、IDN、PHL、GBR。日期格式、企业名称、company_role、catalog 或国家码不合法时，请求直接失败，不会创建任务。

单 section 结果

任务成功后，item.result 包含查询口径和 data 分页对象：

JSON
{
  "company_name": "BANBROS COMMERCIAL INC",
  "company_role": "importer",
  "catalog": "imports",
  "date_range": {
    "start": "2025-08-01",
    "end": "2026-07-31"
  },
  "section": "counterparties",
  "data": {
    "total": 42,
    "page": 1,
    "page_size": 20,
    "returned_rows": 20,
    "items": [
      {
        "name": "Example Trading Co.",
        "country": "United States",
        "countryCode": "US",
        "tradeCount": 18,
        "sumOfUSD": 250000,
        "amountSharePct": 21.4
      }
    ]
  }
}

公开行只可能包含稳定字段：name、country、countryCode、date、hsCode、hsDescriptionCn、hsDescriptionEn、companyCount、weight、quantity、sumOfUSD、weightAvgPrice、quantityAvgPrice、tradeCount、amountSharePct。不同 section 不一定返回全部字段。

完整报告结果

trade-reports 的 item.result 按 section 返回：

JSON
{
  "company_name": "BANBROS COMMERCIAL INC",
  "company_role": "importer",
  "catalog": "imports",
  "date_range": {
    "start": "2025-08-01",
    "end": "2026-07-31"
  },
  "status": "partial",
  "sections": {
    "counterparties": {
      "status": "complete",
      "data": {
        "total": 42,
        "page": 1,
        "page_size": 20,
        "returned_rows": 20,
        "items": []
      }
    },
    "categories": {
      "status": "complete",
      "data": {}
    },
    "trend": {
      "status": "failed",
      "error": {
        "code": "customs_section_failed"
      }
    },
    "countries": {
      "status": "complete",
      "data": {}
    }
  }
}

完整报告允许部分成功。应逐个检查 section 的 status，不要因为 job 为 succeeded 就假设四个 section 全部成功。