1. 💡API使用说明
飞驼可视接口
简体中文
  • 简体中文
  • English
  • 💡API使用说明
    • 🥇API业务概述
    • 🥈产品效果展示
    • 🥉API对接流程
    • 📋接口状态码
    • 📋坐标系转换
    • 📋接口加密签名
    • ♥️获取Token
      POST
  • ⚓海运集装箱跟踪
    • ⚓集装箱综合跟踪
      • 📌智能甩柜预测
      • 📋业务覆盖范围-超90家
      • 📋节点状态码
      • 📋嵌套可视化地图
      • 集装箱综合跟踪（订阅+查询）
      • 集装箱综合跟踪（更新通知推送）
      • 集装箱综合跟踪（增量+预警推送）
      • 集装箱综合跟踪（停止推送）
      • 箱/单智能识别船公司📌
      • 箱号智能识别提单号📌
    • ⚓船司集装箱跟踪(原始)
      • 📋节点状态码
      • 📋业务覆盖范围
      • 船公司箱货跟踪（订阅）
      • 船公司箱货跟踪（推送）
      • 船公司箱货跟踪（查询）
    • 🏗中国港区+海关跟踪
      • 📋业务覆盖范围
      • 📋节点状态码
      • 中国港区跟踪（订阅）
      • 中国港区跟踪（查询）
      • 中国港区跟踪（推送）
      • 中国海关跟踪（提单号）
      • 中国海关跟踪（报关单号）
    • 🏗国外港区+海关跟踪
      • 📌美国CES查验站跟踪
      • 📋业务覆盖范围-超150个港
      • 📋节点状态码
      • 海外码头跟踪（订阅）
      • 海外码头跟踪（查询）
      • 美国海关跟踪（订阅）
      • 美国海关跟踪（查询）
      • 美国海关原始数据（查询）
      • CBP进口商Bond 查询
    • 🚛EIR放单+提/还箱跟踪
      • 📋业务覆盖范围
      • 📋节点状态码
      • 中国EIR跟踪（订阅）
      • 中国EIR跟踪（查询）
    • 🕒码头作业计划
      • 📋业务覆盖范围
      • 码头船舶计划
      • 船司航次转码头航次
  • 🚢 散货/RORO跟踪
    • 📋业务覆盖范围
    • 📋嵌套可视化地图
    • 船舶AIS定位+ETA（查询）单船
      GET
    • 船舶AIS定位+ETA（查询）多船
      GET
    • 船舶历史轨迹（查询）
      GET
    • 船舶当前挂靠港（查询）
      GET
    • 船舶历史挂靠港（查询）
      GET
    • 海运港拥堵分析📌（查询）
      GET
    • RORO港口拥堵分析📌（查询）
      GET
    • 船舶轨迹预测📌（查询 ）
      GET
    • 船舶跟踪ETA预测📌（查询）
      GET
    • 船舶档案（查询）
      GET
    • 船舶搜索（查询）
      GET
  • 🚂铁路货运跟踪
    • 🚂北美海铁联运
      • 📋业务覆盖范围
      • 📋海铁节点状态码
      • 📋嵌套可视化地图
      • 海铁联运跟踪（订阅+查询）
      • 海铁联运跟踪（更新通知推送）
      • 海铁联运跟踪（增量+预警推送）
      • 海铁联运跟踪（停止推送）
      • 北美铁运实时跟踪（查询）
      • 北美铁运历史跟踪（查询）
    • 🚂中欧+中亚铁路
      • 📋业务覆盖范围
      • 📋嵌套可视化地图
      • 中欧+中亚铁路跟踪（订阅）
      • 中欧+中亚铁路跟踪（查询）
  • 🛫航空货运跟踪
    • 📋业务覆盖范围-超180家
    • 📋节点状态码
    • 📋嵌套可视化地图
    • 航空货运跟踪（订阅）
    • 航空货运跟踪（查询）
    • 航空货运跟踪（推送）
    • 飞机实时跟踪ADSB（查询）
    • 美国海关空运跟踪（查询）
  • 📦快递包裹跟踪
    • 📋业务覆盖范围-超1500家
    • 📋节点状态码
    • 快递跟踪（订阅）
    • 快递跟踪（查询）
    • 快递公司搜索（查询）
  • 🚚国内汽运跟踪
    • 📋嵌套可视化地图
    • 货车定位（查询）
    • 货车定位+ETA（查询）
    • 货车轨迹（查询）
    • 货车综合跟踪（查询）
    • 货车电子围栏（订阅）
    • 货车电子围栏（推送）
  • 📅海运船期计划
    • 📋业务覆盖范围📌
    • 港到港船期（直达+中转）- 新版
    • 港到港船期（直达+中转）
    • 港到港船期（全球直达）
    • 船舶船期（船名+航次）
    • 船舶船期（船名）
  • 🗓航空航班计划
    • 📋业务覆盖范围
    • 全球航班计划
  1. 💡API使用说明

📋接口加密签名

一、接口调用规范#

1.1 接口基础信息#

接口前缀：所有业务接口均需添加统一前缀 /api/v1/exchange
拼接规则：/api/v1/exchange + 原始业务接口路径
示例：原始接口 /application/v1/query，实际请求路径为 /api/v1/exchange/application/v1/query

二、签名规范（Signature）#

2.1 请求头参数#

所有请求均需在 Header 中携带以下鉴权参数：
参数名说明
X-Auth-AppId应用 ID
X-Auth-Timestamp当前时间戳（毫秒）
X-Auth-Sign签名值
Authorization鉴权令牌
⚠️ 例外：获取 Token 接口无需携带 Authorization Header。

2.2 签名生成算法#

第一步：准备固定字符串#

按顺序拼接：AppId + 时间戳(毫秒) + AppSecret

第二步：准备业务字符串#

请求方式处理规则
GET将所有参数按 Key 的字母顺序排序，拼接为 key=value 格式（多个参数用 & 连接，忽略空值，不进行 UrlEncode）
POST直接使用请求体（Body）的原始内容

第三步：生成签名#

将"固定字符串"与"业务字符串"首尾相连，对完整字符串进行 SHA-256 哈希运算，输出小写十六进制字符串。

三、数据加密规范（Encryption）#

为保证数据安全，接口数据需进行加密传输。
⚠️ 例外：获取 Token 接口无需加密但需要签名，直接以明文方式传输即可。

3.1 加密前置准备#

参数说明
密钥（data_secret）由后台分配，作为 AES 加密的密码
偏移量（IV）客户端随机生成 16 字节数据，并进行 Base64 URL Safe 编码
加密算法AES-256-CBC，填充模式：PKCS5

3.2 GET 请求加密流程#

1.
构造明文：将所有业务参数拼接为 key=value 格式（多个参数用 & 连接，Key 和 Value 均需进行 UrlEncode）
2.
执行加密：使用 data_secret 和 IV 对明文进行 AES 加密，再进行 Base64 URL Safe 编码，得到密文
3.
重组请求：将原有的 Query 参数替换为以下两个参数：
data = 加密后的密文
iv = 生成的 IV 字符串

3.3 POST 请求加密流程#

1.
构造明文：直接使用原始请求体（Body）内容
2.
执行加密：使用 data_secret 和 IV 对明文进行 AES 加密，再进行 Base64 URL Safe 编码，得到密文
3.
重组请求：将请求体替换为以下 JSON 格式：
{
  "data": "加密后的密文",
  "iv": "生成的IV字符串"
}

4.响应内容规范 (Response)#

服务端返回的响应内容同样遵循上述加密与签名机制，具体规则如下：
●响应加密：响应体（Body）的加密逻辑与请求端完全一致，使用 AES-256-CBC + PKCS5 算法，并将加密后的密文与新的 IV 一并返回（Token 相关接口除外）。
●响应签名：响应 Header 中同样会携带X-Auth-Timestamp 和 X-Auth-Sign 供客户端验签。
●鉴权参数更新：响应中的 X-Auth-Timestamp 为服务端生成响应时的新时间戳。客户端需使用新时间戳及响应体内容重新计算签名，以验证响应的真实性与完整性。

5.错误响应 (Error Response)#

statusCode 说明 触发场景
40000 参数错误 缺少必填参数或参数格式不合法
40100 鉴权失败 鉴权失败、签名校验不通过、数据解密失败
40000 错误响应示例：
{
  "statusCode": 40000,
  "message": "缺少必填参数"
}
40100 错误响应示例：
{
  "statusCode": 40100,
  "message": "鉴权失败"
}
💡 排查建议：
●收到 40000 时：检查请求中是否遗漏了必填参数，参数类型和格式是否符合接口要求。
●收到 40100 时：检查 AppId / AppSecret 配置是否正确、时间戳是否存在较大偏差、签名拼接逻辑是否符合规范、加密密钥与 IV 是否匹配。

接口调用规范说明#

1. 接口基础信息#

接口前缀：所有业务接口均需添加统一前缀 /api/v1/exchange。
拼接规则：/api/v1/exchange + 原始业务接口路径。
示例：原始接口 /application/v1/query，实际请求路径为 /api/v1/exchange/application/v1/query。

2. 签名规范 (Signature)#

所有请求均需在 Header 中携带以下三个鉴权参数：
X-Auth-AppId：应用 ID
X-Auth-Timestamp：当前时间戳
X-Auth-Sign：签名值
Authorization：鉴权令牌
⚠ 例外：获取Token 接口无需携带 Authorization Header
签名生成算法：
1.
准备固定字符串：按顺序拼接 AppId + 时间戳(毫秒) + AppSecret。
2.
准备业务字符串：
GET 请求：将所有参数按 Key 的字母顺序 排序，拼接为 key=value 格式（多个参数用 & 连接，忽略空值，不进行 UrlEncode）。
POST 请求：直接使用请求体（Body）的原始内容。
3.
生成签名：将"固定字符串"与"业务字符串"首尾相连，对完整字符串进行 SHA-256 哈希运算，输出 小写十六进制 字符串。

3. 数据加密规范 (Encryption)#

为保证数据安全，接口数据需进行加密传输。
⚠ 例外：获取Token接口无需加密但需要签名，直接以明文方式传输即可。
加密前置准备：
密钥 (data_secret)：由后台分配，作为 AES 加密的密码。
偏移量 (IV)：客户端随机生成 16 字节数据，并进行 Base64 URL Safe 编码。
加密算法：AES-256-CBC，填充模式：PKCS5。
各请求类型加密流程：
GET 请求：
1.
构造明文：将所有业务参数拼接为 key=value 格式（多个参数用 & 连接，Key 和 Value 均需进行 UrlEncode）。
2.
执行加密：使用 data_secret 和 IV 对明文进行 AES 加密，得到密文。
3.
重组请求：将原有的 Query 参数替换为以下两个参数：
data = 加密后的密文
iv = 生成的 IV 字符串
POST 请求：
1.
构造明文：直接使用原始请求体（Body）内容。
2.
执行加密：使用 data_secret 和 IV 对明文进行 AES 加密，得到密文。
3.
重组请求：将请求体替换为 JSON 格式：
{
  "data": "加密后的密文",
  "iv": "生成的IV字符串"
}

4. 响应内容规范 (Response)#

服务端返回的响应内容同样遵循上述加密与签名机制，具体规则如下：
响应加密：响应体（Body）的加密逻辑与请求端完全一致，使用 AES-256-CBC + PKCS5 算法，并将加密后的密文与新的 IV 一并返回（Token 相关接口除外）。
响应签名：响应 Header 中同样会携带X-Auth-Timestamp 和 X-Auth-Sign 供客户端验签。
鉴权参数更新：响应中的 X-Auth-Timestamp 为服务端生成响应时的新时间戳。客户端需使用新时间戳及响应体内容重新计算签名，以验证响应的真实性与完整性。

5. 错误响应 (Error Response)#

statusCode说明触发场景
40000参数错误缺少必填参数或参数格式不合法
40100鉴权失败鉴权失败、签名校验不通过、数据解密失败
40000 错误响应示例：
{
  "statusCode": 40000,
  "message": "缺少必填参数"
}
40100 错误响应示例：
{
  "statusCode": 40100,
  "message": "鉴权失败"
}
💡 排查建议：
收到 40000 时：检查请求中是否遗漏了必填参数，参数类型和格式是否符合接口要求。
收到 40100 时：检查 AppId / AppSecret 配置是否正确、时间戳是否存在较大偏差、签名拼接逻辑是否符合规范、加密密钥与 IV 是否匹配。
上一页
📋坐标系转换
下一页
♥️获取Token
Built with