【西邮LMS】新增燃油费率批量查询接口，支持合作方稳定获取各渠道实时费率

需求背景

合作方现状： COSCO系统、AUK打单系统等作为我司的重要合作方，目前需通过燃油费率来计算向终端客户收取的物流费用，确保费用的准确性和完整性。

当前痛点： COSCO原通过爬虫抓取FedEx、UPS等官网燃油费率，但因对方官网频繁改版及反爬机制升级，导致抓取失败率高、数据不稳定，直接影响物流费计算准确性及客户账单管理。

合作诉求： 西邮WMS已整合各尾程承运商资源，燃油费率数据全面、准确。为提升合作方系统稳定性及数据一致性，希望贵司开放燃油费率批量查询接口，由COSCO系统直接调用获取，实现一次对接、永久适用，避免因承运商官网变动而频繁调整。

预期效益： 该接口上线后，COSCO可稳定获取燃油费率，保障下游客户账单准确，同时减少双方因费用争议带来的沟通成本，提升合作体验。

需求描述

1. 总体目标
   开放一个稳定、高效的燃油费率查询接口，支持合作方（如COSCO）通过西邮渠道代码批量获取对应燃油费率，确保数据及时、准确。

2. 接口详细要求
   2.1 接口基本信息

接口名称： 燃油费率批量查询接口

接口类型： HTTP/HTTPS POST 或 GET（建议POST以支持批量）

认证方式： 使用已有API密钥或分配独立权限（沿用西邮现有鉴权机制）

频率限制： 建议允许每日调用1-2次（如每日凌晨各一次），若需更高频率请明确告知

2.2 入参说明

参数名 类型 是否必填 说明
channel_codes array 是 西邮渠道代码列表，支持批量传入（如：[“FEDEX_US”, “UPS_GROUND”, “DHL_EXP”]）
query_date string 否 查询指定日期的燃油费率，格式 YYYY-MM-DD；不传则返回最新生效费率
2.3 出参说明

参数名 类型 说明
code int 响应码，如200成功，其他见错误码说明
message string 响应信息
data array 费率列表，每个元素包含以下字段
└ channel_code string 西邮渠道代码
└ fuel_rate decimal 燃油费率，如 0.155 表示15.5%，建议保留3-4位小数
└ effective_date string 生效日期，格式 YYYY-MM-DD
└ expiry_date string 失效日期，格式 YYYY-MM-DD（若长期有效可返回空或2099-12-31）
└ update_time string 最后更新时间，格式 YYYY-MM-DD HH:MM:SS
2.4 业务逻辑要求

批量支持： 必须支持一次性传入多个渠道代码，并批量返回对应费率，提升调用方效率。

生效规则： 返回的费率应基于查询日期（query_date）确定。若不传查询日期，则返回每个渠道当前最新的生效费率。

费率来源： 确保返回的燃油费率与贵司内部用于成本计算的费率一致，避免数据差异。

历史可追溯： 如有能力，建议支持按生效日期区间返回历史费率（非必须，可作为二期优化）。

2.5 异常处理

错误码定义： 需提供明确的错误码说明，如渠道代码不存在、系统内部错误等。

降级方案： 若接口异常，建议返回最近一次成功抓取的缓存数据，并附带标识告知非实时数据（可选）。

2.6 对接文档要求

提供详细的API对接文档，包括：接口地址、请求示例（CURL/Python/Java）、响应示例、错误码列表、频率限制说明等。

提供测试环境及账号用于联调，确保上线前充分验证。

3. 其他建议
   数据更新频率： 燃油费率通常每周或每月更新，建议贵司在费率变更时及时维护，并确保接口实时返回最新数据。

告警通知： 如有条件，可在费率变更时主动推送通知给合作方（如通过邮件或webhook），但非强制要求。

开发设计

接口地址：http://localhost:8082/woms_api/fuelRate
鉴权：请求头携带：tokenKey
请求参数：

{
    "channelCodes": ["US_FEDEX_ZJ6","US_FEDEX_ZJ1"],
    "queryDate": "2025-06-01"
}

响应结果：

{
    "success": true,
    "message": "查询成功",
    "showMessage": null,
    "data": [
        {
            "channelCode": "US_FEDEX_ZJ6",
            "fuelRate": 0.105000,
            "effectiveDate": "2025-06-01 00:00:00",
            "expiryDate": "2025-06-30 23:59:59",
            "updateTime": "2026-03-17 15:34:22"
        },
        {
            "channelCode": "US_FEDEX_ZJ1",
            "fuelRate": 0.100000,
            "effectiveDate": "2025-06-01 00:00:00",
            "expiryDate": "2026-06-30 23:59:59",
            "updateTime": "2025-06-17 10:38:04"
        }
    ],
    "code": 200,
    "result": "success",
    "next": null
}

除了返回字段数据不是下划线形式，采用更常见的驼峰命名。