首页开放平台文档快速接入

快速接入

本页将引导你在 5 分钟内完成第一次成功调用。从注册账号到拿到真实运价响应，全程只需要三步。

第 1 步：注册账号

访问 5688.cn 首页右上角「注册」按钮，使用手机号注册账号。注册成功后，进入开发者控制台即可免费领取 100 积分体验包。

提示：体验包和积分套餐注册后即可直接领取 / 购买，无需实名认证；仅月度 / 年度不限量套餐购买前需完成实名认证（企业或个人任一）。

第 2 步：创建应用获取 AppKey / AppSecret

访问开发者控制台 → 应用管理，点击「创建应用」按钮。

填写应用名称（仅自己看，用于多应用区分）
选择初始套餐（推荐先用免费 100 积分包试用）
建议立即配置 IP 白名单（可填多个 IP，逗号分隔）
创建成功后页面会显示 AppKey 和 AppSecret，AppSecret 仅展示一次，请立刻复制保存

⚠️ 安全警示：AppSecret 绝不可上传到 GitHub / GitLab 等公开仓库，也不可写在前端 JS 里。泄漏后请立即到控制台「重置 Secret」。建议存放在服务端环境变量或配置中心。

第 3 步：复制示例代码调用

以下是 PHP 完整可运行示例，复制后替换 $appKey 和 $appSecret 即可运行。

<?php
// 海运 FCL 运价查询 - PHP 完整可运行示例
$appKey    = 'AK_xxxxxxxxxxxxxxxx';        // ① 替换为你的 AppKey
$appSecret = 'SK_yyyyyyyyyyyyyyyyyy';      // ② 替换为你的 AppSecret
// pol / pod 同时支持 国际标准代码 5 位 / 中文 / 英文，三种形态任选一种
//   国际标准代码   'CNSHA' / 'USLSA'        最快，生产推荐
//   中文     '上海'   / '洛杉矶'        模糊匹配，多义自动返回各港运价
//   英文     'shanghai' / 'los angeles'
$body      = json_encode([
    'pol'     => 'CNSHA',                  // 起运港（也可填 '上海' 或 'shanghai'）
    'pod'     => 'USLSA',                  // 目的港（也可填 '洛杉矶' 或 'los angeles'）
    'carrier' => 'MSK',                    // 船公司（可选）
]);
$ts        = time();                       // Unix 时间戳（秒）
$nonce     = bin2hex(random_bytes(8));     // 16 字节随机串
$path      = '/openapi/v1/freight/fcl/search';

// 签名：HMAC-SHA256( METHOD + "\n" + PATH + "\n" + TS + "\n" + NONCE + "\n" + md5(BODY) )
$message = "POST\n{$path}\n{$ts}\n{$nonce}\n" . md5($body);
$sign    = hash_hmac('sha256', $message, $appSecret);

$ch = curl_init('https://www.5688.cn/api' . $path);
curl_setopt_array($ch, [
    CURLOPT_POST           => 1,
    CURLOPT_POSTFIELDS     => $body,
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        "X-Awice-AppKey: {$appKey}",
        "X-Awice-Timestamp: {$ts}",
        "X-Awice-Nonce: {$nonce}",
        "X-Awice-Signature: {$sign}",
    ],
]);
$resp = curl_exec($ch);
curl_close($ch);

$result = json_decode($resp, true);
print_r($result);

预期响应

请求成功后，你会收到类似下面的 JSON 响应：

{
  "code": 0,
  "msg": "success",
  "data": {
    "resolved": {
      "pol": { "code": "CNSHA", "name": "Shanghai" },
      "pod": { "code": "USLSA", "name": "Los Angeles" }
    },
    "total": 12,
    "page": 1,
    "limit": 20,
    "list": [
      {
        "carrier": "MSK",
        "carrier_name": "MAERSK",
        "container_20gp": 1850,
        "container_40gp": 2950,
        "container_40hq": 2980,
        "currency": "USD",
        "transit": 18,
        "valid_from": "2026-05-01",
        "valid_to": "2026-05-31",
        "update_time": 1746086400
      }
    ]
  },
  "credit_used": 1,
  "credit_balance": 9499
}

常见首次接入问题

现象	原因	解决
返回 2002 签名错误	JSON 序列化空格差异	参考鉴权页严格按规范拼接
返回 2003 时间戳过期	服务器时钟未同步	运行 ntpdate 或开启系统自动同步
返回 2005 IP 未在白名单	出口 IP 没加入白名单	到控制台「应用管理」补充白名单

下一步：鉴权 & 签名