海运运价 API:整柜 FCL 报价接口
海运费查询接口按起运港、目的港和船公司返回整柜集装箱报价,提供 20GP、40GP、40HQ 箱型运价、币种、有效期与可用附加费。适合货代报价系统、海运运费计算器及 TMS / ERP 对接;具体字段和费用口径见下文。
接口信息#
| 请求地址 | POST https://www.5688.cn/api/openapi/v1/freight/fcl/search |
| 积分消耗 | 1 积分 / 次 |
| 数据更新 | 每日更新 |
| 超时建议 | 客户端 timeout ≥ 3 秒 |
请求参数#
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| pol | string | 是 | 起运港,支持 5 位代码(精确)/ 中文 / 英文(模糊)查代码 ↗ | CNSHA / 上海 / Shanghai |
| pod | string | 是 | 目的港,支持 5 位代码(精确)/ 中文 / 英文(模糊)查代码 ↗ | USLSA / 洛杉矶 / Los Angeles |
| carrier | string | 否 | 船公司,支持代码(精确)/ 中文 / 英文(模糊)查代码 ↗ | MSK / 马士基 / Maersk |
| page | int | 否 | 页码,默认 1 | 1 |
| limit | int | 否 | 每页条数,默认 20,最大 50 | 20 |
| pol_country | string | 否 | 起运港国家码(2 位 ISO,可选),pol 同名多港时锁定国家 | CN |
| pod_country | string | 否 | 目的港国家码(2 位 ISO,可选)。pod 同名多港(如「圣安东尼奥」对应智利/美国/阿根廷)时,不传则返回所有同名港运价、按命中港口数计费;传此参数锁定单一国家 | US |
响应字段#
| 字段名 | 类型 | 说明 |
|---|---|---|
| resolved.pol / pod | object | 回显本次解析的港口(含 input 原始输入、code 解析后代码、name 中文、name_en 英文),便于客户端确认 |
| list[].id | string | 运价记录唯一 ID |
| list[].pol / pod | object | 起运港 / 目的港 { code, name, name_en } |
| list[].carrier | object | 船公司 { code, name }(如 EMC 长荣海运、MSK 马士基、ONE 海洋网联) |
| list[].transit | object | { is_direct: 是否直航, days: 航程天数, port/port_en: 中转港中英文 } |
| list[].schedule.cutoff_date | string | 截关日期(YYYY-MM-DD,订舱后必须在此日前提交舱单/送货进仓) |
| list[].schedule.departure_date | string | 开船日期 ETD(YYYY-MM-DD) |
| list[].schedule.arrival_date | string | 预计到港日期 ETA |
| list[].schedule.vessel_name / voyage | string | 船名 / 航次号(部分船公司可能为空) |
| list[].schedule.service_code | string | 航线服务编码(船公司给固定航线起的编号,如 TP6 = TransPacific 第 6 号跨太平洋航线,可用于预判固定班期;部分船公司可能为空) |
| list[].schedule.is_real | boolean | true = 开船/到港/截关来自船公司官网的真实航次(附带船名航次);false = 该船公司暂无船期数据,日期按每周固定班期推算,仅供参考 |
| list[].prices | object | 三种箱型的 USD 海运费(20GP、40GP、40HQ);附加费另列在 surcharges,不在此处合并。 |
| list[].surcharges | array | 附加费列表:code、name、name_en、20GP、40GP、40HQ、currency、remark、charge_unit、singleprice;按charge_unit确定计费方式。 |
| list[].surcharges[].charge_unit | string | 计费方式代码:CONTAINER按集装箱,BILL按票,MIXED按箱加单票;UNKNOWN表示上游信息不完整,不能自动计算。 |
| list[].surcharges[].singleprice | number | 单票金额,与currency使用同一币种。BILL只计一次;MIXED在箱费合计上加一次;CONTAINER为0。 |
| list[].valid_until | string | 运价有效期截止日(YYYY-MM-DD) |
| credit_used | int | 本次扣减的积分数(FCL 固定 1 积分) |
| credit_balance | int | 扣减后剩余积分 |
海运费、附加费与目的港费用#
同一次 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 请求示例#
# 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
}'成功响应示例#
{
"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 多匹配则自动取主港,不展开。
{
"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
}