澜湄联盟 · 开放 API 接入文档

1. 概述

澜湄联盟官网对外开放数据接口，供第三方系统调用获取联盟相关数据。

架构示意（鉴权开启时）

2. 管理后台使用

鉴权开启后，需在管理后台创建应用并分配权限。入口：系统管理 → 开放接口。

2.1 创建应用

1. 进入 系统管理 → 开放接口
2. 点击 创建应用，填写应用名称
3. 勾选 数据权限（Scope）
4. 保存后弹窗展示 AppId 和 AppSecret（仅展示一次，请立即复制保存）

2.2 应用配置项

3. 鉴权开关

open:
  api:
    auth-enabled: true   # 或环境变量 OPEN_API_AUTH_ENABLED=true

4. 签名认证（auth-enabled=true 时生效）

4.1 请求 Header

4.2 签名算法

signContent = appId + "\n"
            + timestamp + "\n"
            + nonce + "\n"
            + METHOD + "\n"
            + path + "\n"
            + sortedQueryString + "\n"
            + sha256(body)

sign = HMAC-SHA256(appSecret, signContent).toHexLowerCase()

• path：不含域名，如 /api/open/v1/regions/countries
• sortedQueryString：Query 参数按 key 字典序，URL 编码后用 & 连接；无参数时为空字符串
• body：GET 为空字符串的 SHA256；POST/PUT 为 raw body 的 SHA256

5. 接口列表

5.1 快速开始（当前无需鉴权）

直接 GET 请求即可，示例（请将域名替换为实际地址）：

5.2 连通性测试

鉴权开启时用于验证 AppId 与签名是否正确。

5.3 地区数据 已开放

鉴权开启时需 Scope：region:read

响应示例 — countries

{
  "code": 200,
  "message": "success",
  "data": [
    { "id": 1, "code": "CN", "name": "中国", "sort": 1 },
    { "id": 2, "code": "TH", "name": "泰国", "sort": 2 }
  ]
}

响应示例 — children

{
  "code": 200,
  "message": "success",
  "data": [
    { "id": 10, "code": "110000", "name": "北京市", "parentId": 1, "level": 2, "sort": 1 }
  ]
}

5.4 CMS 分类 已开放

鉴权开启时需 Scope：cms:category:read

字段说明 — category 节点

响应示例 — category 树（完整数据，lang=zh-CN）

GET /api/open/v1/cms/category?lang=zh-CN

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "deleted": null,
      "createTime": "2026-05-16 09:28:29",
      "updateTime": "2026-07-05 17:06:11",
      "parentId": 0,
      "slug": "news",
      "sort": 0,
      "status": 1,
      "name": "中国文旅",
      "children": []
    },
    {
      "id": 2,
      "deleted": null,
      "createTime": "2026-06-01 17:03:31",
      "updateTime": "2026-07-01 20:45:42",
      "parentId": 0,
      "slug": "other_news",
      "sort": 0,
      "status": 1,
      "name": "国际视野",
      "children": []
    },
    {
      "id": 9,
      "deleted": null,
      "createTime": "2026-07-05 17:06:23",
      "updateTime": "2026-07-05 17:06:23",
      "parentId": 0,
      "slug": "",
      "sort": 0,
      "status": 1,
      "name": "柬埔寨文旅",
      "children": []
    },
    {
      "id": 11,
      "deleted": null,
      "createTime": "2026-07-05 17:06:44",
      "updateTime": "2026-07-05 17:06:44",
      "parentId": 0,
      "slug": "老挝文旅",
      "sort": 0,
      "status": 1,
      "name": "老挝文旅",
      "children": []
    },
    {
      "id": 12,
      "deleted": null,
      "createTime": "2026-07-05 17:06:55",
      "updateTime": "2026-07-05 17:06:55",
      "parentId": 0,
      "slug": "缅甸文旅",
      "sort": 0,
      "status": 1,
      "name": "Category-12",
      "children": []
    },
    {
      "id": 13,
      "deleted": null,
      "createTime": "2026-07-05 17:07:02",
      "updateTime": "2026-07-05 17:07:02",
      "parentId": 0,
      "slug": "泰国文旅",
      "sort": 0,
      "status": 1,
      "name": "Category-13",
      "children": []
    },
    {
      "id": 14,
      "deleted": null,
      "createTime": "2026-07-05 17:07:12",
      "updateTime": "2026-07-05 17:07:12",
      "parentId": 0,
      "slug": "越南文旅",
      "sort": 0,
      "status": 1,
      "name": "Category-14",
      "children": []
    }
  ]
}

6. Scope 权限一览（鉴权开启时生效）

7. 错误码

8. 代码示例

8.1 直接调用（当前，无需鉴权）

# curl
curl "https://your-domain.com/api/open/v1/regions/countries?lang=zh-CN"

# Python
import requests
r = requests.get("https://your-domain.com/api/open/v1/regions/countries", params={"lang": "zh-CN"})
print(r.json())

8.2 Python 签名示例（鉴权开启时）

import hashlib, hmac, time, uuid, urllib.parse, requests

APP_ID = "lm_xxxxxxxxxxxx"
APP_SECRET = "your-secret-here"
BASE = "https://your-domain.com"

def sha256_hex(s):
    return hashlib.sha256(s.encode("utf-8")).hexdigest()

def build_query(params):
    items = []
    for key in sorted(params.keys()):
        val = params[key]
        if val is None: continue
        items.append(f"{urllib.parse.quote(key, safe='')}={urllib.parse.quote(str(val), safe='')}")
    return "&".join(items)

def sign(method, path, params, body=""):
    ts = str(int(time.time()))
    nonce = uuid.uuid4().hex
    content = "\n".join([APP_ID, ts, nonce, method.upper(), path, build_query(params), sha256_hex(body)])
    sig = hmac.new(APP_SECRET.encode(), content.encode(), hashlib.sha256).hexdigest()
    return ts, nonce, sig

path = "/api/open/v1/regions/countries"
params = {"lang": "zh-CN"}
ts, nonce, sig = sign("GET", path, params)
r = requests.get(BASE + path, params=params, headers={
    "X-App-Id": APP_ID, "X-Timestamp": ts, "X-Nonce": nonce, "X-Sign": sig,
})
print(r.json())

8.3 curl 签名示例（鉴权开启时）

curl -G "https://your-domain.com/api/open/v1/regions/countries" \
  -H "X-App-Id: lm_xxxxxxxxxxxx" \
  -H "X-Timestamp: 1719900000" \
  -H "X-Nonce: abc123def4567890" \
  -H "X-Sign: <computed_hmac>" \
  --data-urlencode "lang=zh-CN"

9. 服务端配置（运维参考）

open:
  api:
    auth-enabled: ${OPEN_API_AUTH_ENABLED:false}
    encrypt-key: ${OPEN_API_ENCRYPT_KEY:lm-open-api-key!}
    timestamp-skew-seconds: 300
    nonce-ttl-seconds: 600