文档目录

海运运价 API:整柜 FCL 报价接口

海运费查询接口按起运港、目的港和船公司返回整柜集装箱报价,提供 20GP、40GP、40HQ 箱型运价、币种、有效期与可用附加费。适合货代报价系统、海运运费计算器及 TMS / ERP 对接;具体字段和费用口径见下文。

接口信息#

请求地址POST https://www.5688.cn/api/openapi/v1/freight/fcl/search
积分消耗1 积分 / 次
数据更新每日更新
超时建议客户端 timeout ≥ 3 秒

请求参数#

字段名类型必填说明示例
polstring是起运港,支持 5 位代码(精确)/ 中文 / 英文(模糊)查代码 ↗CNSHA / 上海 / Shanghai
podstring是目的港,支持 5 位代码(精确)/ 中文 / 英文(模糊)查代码 ↗USLSA / 洛杉矶 / Los Angeles
carrierstring否船公司,支持代码(精确)/ 中文 / 英文(模糊)查代码 ↗MSK / 马士基 / Maersk
pageint否页码,默认 11
limitint否每页条数,默认 20,最大 5020
pol_countrystring否起运港国家码(2 位 ISO,可选),pol 同名多港时锁定国家CN
pod_countrystring否目的港国家码(2 位 ISO,可选)。pod 同名多港(如「圣安东尼奥」对应智利/美国/阿根廷)时,不传则返回所有同名港运价、按命中港口数计费;传此参数锁定单一国家US

响应字段#

字段名类型说明
resolved.pol / podobject回显本次解析的港口(含 input 原始输入、code 解析后代码、name 中文、name_en 英文),便于客户端确认
list[].idstring运价记录唯一 ID
list[].pol / podobject起运港 / 目的港 { code, name, name_en }
list[].carrierobject船公司 { code, name }(如 EMC 长荣海运、MSK 马士基、ONE 海洋网联)
list[].transitobject{ is_direct: 是否直航, days: 航程天数, port/port_en: 中转港中英文 }
list[].schedule.cutoff_datestring截关日期(YYYY-MM-DD,订舱后必须在此日前提交舱单/送货进仓)
list[].schedule.departure_datestring开船日期 ETD(YYYY-MM-DD)
list[].schedule.arrival_datestring预计到港日期 ETA
list[].schedule.vessel_name / voyagestring船名 / 航次号(部分船公司可能为空)
list[].schedule.service_codestring航线服务编码(船公司给固定航线起的编号,如 TP6 = TransPacific 第 6 号跨太平洋航线,可用于预判固定班期;部分船公司可能为空)
list[].schedule.is_realbooleantrue = 开船/到港/截关来自船公司官网的真实航次(附带船名航次);false = 该船公司暂无船期数据,日期按每周固定班期推算,仅供参考
list[].pricesobject三种箱型的 USD 海运费(20GP、40GP、40HQ);附加费另列在 surcharges,不在此处合并。
list[].surchargesarray附加费列表:code、name、name_en、20GP、40GP、40HQ、currency、remark、charge_unit、singleprice;按charge_unit确定计费方式。
list[].surcharges[].charge_unitstring计费方式代码:CONTAINER按集装箱,BILL按票,MIXED按箱加单票;UNKNOWN表示上游信息不完整,不能自动计算。
list[].surcharges[].singlepricenumber单票金额,与currency使用同一币种。BILL只计一次;MIXED在箱费合计上加一次;CONTAINER为0。
list[].valid_untilstring运价有效期截止日(YYYY-MM-DD)
credit_usedint本次扣减的积分数(FCL 固定 1 积分)
credit_balanceint扣减后剩余积分

海运费、附加费与目的港费用#

同一次 FCL 查询分别返回 list[].prices(USD 海运费)和 list[].surcharges(已配置的适用附加费及各自币种、备注),附加费不会自动并入海运费。按费用对应柜型、币种及备注使用,不能直接把不同币种相加。

当前附加费主要按起运港本地费用维护,不能保证包含每个目的港的全部 THC、DO(提货单费)、文件费等。费用名称或目的港匹配条件不能单独证明费用发生在目的港;当前响应没有明确的起运港/目的港费用发生地字段,也没有独立目的港费用查询接口。未返回的费用不代表免费,具体目的港费用及是否包含在报价内请与业务员确认。

附加费计费代码与计算方法#

charge_unit代码含义计算方式
CONTAINER按集装箱20GP×20GP箱量 + 40GP×40GP箱量 + 40HQ×40HQ箱量。
BILL按票只取singleprice,每票计一次,不乘箱量,也不再叠加三个柜型金额。
MIXED按集装箱加单票各柜型金额×对应箱量之和,再加一次singleprice;同一费用同时维护两种金额时使用。
UNKNOWN信息不完整不自动计算,也不要根据remark、金额相同或缺少字段猜单位;联系技术支持核对。

为兼容原接入,纯单票费用在20GP/40GP/40HQ中仍重复显示同一金额;这些字段不是每箱收费。新接入必须先判断charge_unit,BILL只用singleprice。柜型金额相同不能用于判断按票,remark只作文字说明。

例:2个20GP,文件费BILL、singleprice=300时共300;码头费CONTAINER、20GP=900时共1800;一项MIXED费用20GP=900、singleprice=300时共2100。均在该费用的currency内计算,不混加币种。

完整 curl 请求示例#

BASH
# pol / pod 同时支持 国际标准代码 5 位 / 中文 / 英文(如 "CNSHA" / "上海" / "shanghai")
curl -X POST https://www.5688.cn/api/openapi/v1/freight/fcl/search \
  -H "Content-Type: application/json" \
  -H "X-Awice-AppKey: AK_xxxxxxxxxxxxxxxx" \
  -H "X-Awice-Timestamp: 1746086400" \
  -H "X-Awice-Nonce: a1b2c3d4e5f6a7b8" \
  -H "X-Awice-Signature: 7f8e9d6c5b4a3f2e1d0c9b8a7e6d5c4b3a2f1e0d9c8b7a6e5d4c3b2a1f0e9d8c" \
  -d '{
    "pol": "CNSHA",
    "pod": "USLSA",
    "carrier": "MSK",
    "page": 1,
    "limit": 20
  }'

成功响应示例#

JSON
{
  "code": 0,
  "msg": "success",
  "request_id": "req_xxxxxxxxxxxxxxxx",
  "data": {
    "resolved": {
      "pol": {
        "input": "CNSHA",
        "code": "CNSHA",
        "name": "上海",
        "name_en": "shanghai"
      },
      "pod": {
        "input": "USLSA",
        "code": "USLSA",
        "name": "洛杉矶",
        "name_en": "los angeles,ca"
      },
      "carrier": null
    },
    "list": [
      {
        "id": "14848",
        "pol": {
          "code": "CNSHA",
          "name": "上海",
          "name_en": "shanghai"
        },
        "pod": {
          "code": "USLSA",
          "name": "洛杉矶",
          "name_en": "los angeles,ca"
        },
        "carrier": {
          "code": "EMC",
          "name": "长荣海运"
        },
        "transit": {
          "is_direct": true,
          "days": 16,
          "port": "",
          "port_en": ""
        },
        "schedule": {
          "cutoff_date": "2026-05-23",
          "departure_date": "2026-05-25",
          "arrival_date": "2026-06-10",
          "vessel_name": "EVER GIVEN",
          "voyage": "025E",
          "service_code": "TP6"
        },
        "prices": {
          "20GP": 2300,
          "40GP": 2850,
          "40HQ": 2850,
          "currency": "USD"
        },
        "surcharges": [
          {
            "code": "DOC",
            "name": "文件费",
            "name_en": "DOCUMENT FEE",
            "20GP": 300,
            "40GP": 300,
            "40HQ": 300,
            "currency": "CNY",
            "remark": "每票",
            "charge_unit": "BILL",
            "singleprice": 300
          },
          {
            "code": "THC",
            "name": "码头操作费",
            "name_en": "TERMINAL HANDLING CHARGE",
            "20GP": 900,
            "40GP": 1400,
            "40HQ": 1400,
            "currency": "CNY",
            "remark": "示例金额",
            "charge_unit": "CONTAINER",
            "singleprice": 0
          }
        ],
        "valid_until": "2026-12-31"
      }
    ]
  },
  "credit_used": 1,
  "credit_balance": 9499
}

目的港多匹配:返回所有同名港运价#

当 pod 匹配到多个同名港口(如「圣安东尼奥」对应智利 / 美国 / 阿根廷)时,接口会自动查询每个港口的运价并合并返回,list 中每条运价带 pod 标注所属港口,并按命中运价的港口数计费(N 港扣 N 倍积分;无运价数据的港口不计费)。如只需某一国,传 pod_country(2 位 ISO 国家码)即可锁定单一港口、只扣 1 次。起运港 pol 多匹配则自动取主港,不展开。

JSON
{
  "code": 0,
  "msg": "success",
  "request_id": "req_xxxxxxxxxxxxxxxx",
  "data": {
    "resolved": {
      "pol": { "input": "广州", "code": "CNGZG", "name": "广州", "name_en": "guangzhou" },
      "pod": {
        "input": "圣安东尼奥",
        "matched": [
          { "code": "CLSAN", "name": "圣安东尼奥", "name_en": "san antonio", "country_code": "CL" },
          { "code": "USSAT", "name": "圣安东尼奥", "name_en": "san antonio,tx", "country_code": "US" }
        ]
      },
      "carrier": null
    },
    "multi_pod": true,
    "matched_ports": 2,
    "charged_ports": 2,
    "skipped_ports": 0,
    "total": 2,
    "list": [
      {
        "id": "20015",
        "pod": { "code": "CLSAN", "name": "圣安东尼奥", "country_code": "CL" },
        "carrier": { "code": "MSK", "name": "马士基" },
        "prices": { "20GP": 1850, "40GP": 3200, "40HQ": 3200, "currency": "USD" }
      },
      {
        "id": "20016",
        "pod": { "code": "USSAT", "name": "圣安东尼奥", "country_code": "US" },
        "carrier": { "code": "ONE", "name": "海洋网联" },
        "prices": { "20GP": 2100, "40GP": 3600, "40HQ": 3600, "currency": "USD" }
      }
    ]
  },
  "credit_used": 2,
  "credit_balance": 9498
}