海关贸易数据 API

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

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

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

两者可以独立组合。大多数查询使用前两种常用组合；只有需要从交易另一侧的数据目录反查时，才使用交叉组合：

company_role 回答“目标企业在交易中是什么角色”，catalog 回答“从哪一侧的记录目录查询”，因此两者不是重复字段。

查找可用的海关企业名称

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",
    "compare_catalogs": false,
    "country_codes": "IDN"
  }'

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

成功任务的 item.result 示例：

JSON复制
{
  "query": "Banbros Commercial Inc.",
  "date_range": { "start": "2025-08-01", "end": "2026-07-31" },
  "routing_evidence": {
    "mode": "explicit",
    "company_role": "exporter",
    "catalogs_checked": ["imports"]
  },
  "identity_notice": "Trade counts prove exact-name queryability only, not authoritative legal identity.",
  "candidates": [
    {
      "name": "BANBROS COMMERCIAL INC",
      "source": "company_list",
      "countries": ["Indonesia"],
      "company_ids": ["provider-company-id"],
      "trade_counts": {
        "start_date": "2025-08-01",
        "end_date": "2026-07-31",
        "company_role": "exporter",
        "catalog": "imports",
        "imports_as_exporter": 18,
        "total": 18,
        "queryable": true
      },
      "identity_status": "unverified"
    }
  ]
}

该接口当前不计费；任务返回 billing.status: not_billable 和 charged_credits: 0。

按商品和国家发现企业

POST/api/v2/customs/companies/search

不需要预先知道公司名称。该接口根据贸易记录中的商品、国家和时间条件，返回进口商或出口商公司列表；适合寻找某个市场的潜在买家、供应商或同行企业。

cURL复制
curl -X POST "https://revor.ai/api/v2/customs/companies/search" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=20" \
  -d '{
    "company_role": "importer",
    "catalog": "imports",
    "start_date": "2025-09-01",
    "end_date": "2026-08-31",
    "hs_code": "8429",
    "product_description": "excavator",
    "origin_country_code": "CHN",
    "destination_country_code": "BRA",
    "page": 1,
    "page_size": 20,
    "sort_by": "trade_count",
    "sort_order": "desc"
  }'

hs_code、product_description、origin_country_code、destination_country_code 至少提供一个，避免提交没有任何业务范围的全库查询。行业名称不是统一海关分类；“机械行业”这类宽泛需求应先选择合适的 HS Code 或商品关键词。

任务成功后，item.result.data.items 返回标准化企业字段：company_name、country、country_code、trade_count、amount_usd、quantity、weight 和金额占比等。不同数据覆盖范围不一定返回全部统计字段。查询按实际返回的企业行数结算 credits；返回 0 行时最终消耗 0 credits。

查询接口

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

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"
    }
  }'

共享请求字段

查询日期跨度最多一年。国家/地区代码统一使用三位代码；常见示例包括 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 全部成功。

Credits 计费

当前默认海关计费按实际返回行数计算：

执行前，服务可能按请求的 page size 和 sections 预留足额 Credits；最终按实际返回行数结算，将总费用向上取整到整数 Credits，并释放未使用的预留额度。应以完成任务中的 billing.charged_credits 为准；价格可能随当前计费配置调整。