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

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

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

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

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

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

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": []
    }
  ]
}

5.5 CMS 标签 已开放

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

字段说明 — tag 节点

响应示例 — tag 列表（lang=zh-CN）

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

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "deleted": null,
      "createTime": "2026-07-05 10:00:00",
      "updateTime": "2026-07-05 10:00:00",
      "slug": "tag1",
      "sort": 0,
      "status": 1,
      "name": "标签一"
    },
    {
      "id": 2,
      "deleted": null,
      "createTime": "2026-07-05 10:00:00",
      "updateTime": "2026-07-05 10:00:00",
      "slug": "tag2",
      "sort": 1,
      "status": 1,
      "name": "标签二"
    },
    {
      "id": 3,
      "deleted": null,
      "createTime": "2026-07-05 10:00:00",
      "updateTime": "2026-07-05 10:00:00",
      "slug": "policy_updates",
      "sort": 2,
      "status": 1,
      "name": "政策动态"
    }
  ]
}

5.6 CMS 文章推送 已开放

允许外部第三方平台通过 Open API 将文章推送到澜湄联盟平台，支持创建和更新操作。

鉴权开启时需 Scope：cms:article:write

请求参数（JSON Body）

下表字段同时适用于创建与更新接口。创建时 categoryId、i18n 为必填；更新时为部分更新，所有字段均可选，仅传入字段被覆盖。

I18n 子对象

请求示例 — 推送文章

POST /api/open/v1/cms/article
Content-Type: application/json

{
  "categoryId": 1,
  "coverImg": "https://example.com/cover.jpg",
  "isRecommend": 0,
  "isTop": 0,
  "sort": 0,
  "status": 1,
  "publishTime": "2026-08-05 10:00:00",
  "tagIds": [1, 2],
  "i18n": [
    {
      "lang": "zh-CN",
      "title": "澜湄合作新进展",
      "subtitle": "多国共同推进区域互联互通",
      "summary": "近日，澜湄合作机制迎来新进展...",
      "content": "<p>详细正文内容...</p>",
      "author": "联盟秘书处",
      "source": "合作伙伴平台A",
      "seoTitle": "澜湄合作新进展 - 官网",
      "seoKeywords": "澜湄,合作,区域互联",
      "seoDescription": "澜湄合作机制最新进展报告"
    },
    {
      "lang": "en",
      "title": "New Progress in Lancang-Mekong Cooperation",
      "subtitle": "Countries Jointly Promote Regional Connectivity",
      "summary": "Recently, the LMC mechanism has made new progress...",
      "content": "<p>Detailed content...</p>",
      "author": "LMC Secretariat",
      "source": "Partner Platform A"
    }
  ]
}

成功响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "article": {
      "id": 123,
      "categoryId": 1,
      "coverImg": "https://example.com/cover.jpg",
      "isRecommend": 0,
      "isTop": 0,
      "sort": 0,
      "status": 1,
      "publishTime": "2026-08-05 10:00:00",
      "viewCount": 0,
      "createTime": "2026-08-05 10:00:00",
      "updateTime": "2026-08-05 10:00:00"
    },
    "i18n": [
      {
        "id": 456,
        "articleId": 123,
        "lang": "zh-CN",
        "title": "澜湄合作新进展",
        "subtitle": "多国共同推进区域互联互通",
        "summary": "近日，澜湄合作机制迎来新进展...",
        "content": "<p>详细正文内容...</p>",
        "author": "联盟秘书处",
        "source": "合作伙伴平台A",
        "seoTitle": "澜湄合作新进展 - 官网",
        "seoKeywords": "澜湄,合作,区域互联",
        "seoDescription": "澜湄合作机制最新进展报告",
        "createTime": "2026-08-05 10:00:00",
        "updateTime": "2026-08-05 10:00:00"
      },
      {
        "id": 457,
        "articleId": 123,
        "lang": "en",
        "title": "New Progress in Lancang-Mekong Cooperation",
        "subtitle": "Countries Jointly Promote Regional Connectivity",
        "summary": "Recently, the LMC mechanism has made new progress...",
        "content": "<p>Detailed content...</p>",
        "author": "LMC Secretariat",
        "source": "Partner Platform A",
        "seoTitle": "",
        "seoKeywords": "",
        "seoDescription": "",
        "createTime": "2026-08-05 10:00:00",
        "updateTime": "2026-08-05 10:00:00"
      }
    ]
  }
}

获取文章详情

路径参数：id — 平台生成的文章 ID。

Query 参数：lang（可选，默认 en）— 仅用于标签名称的回退语言；文章正文与标题始终返回全部语言版本。

返回该文章的完整信息：article 主表记录、i18n 该文章所有语言版本列表、tags 标签列表（含 tagId 与按 lang fallback 解析出的 name）。

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

# 成功
{
    "code": 200,
    "message": "Success",
    "data": {
        "article": {
            "id": 73,
            "deleted": null,
            "createTime": "2026-08-12 10:00:58",
            "updateTime": "2026-08-12 10:00:58",
            "categoryId": 1,
            "coverImg": "https://example.com/cover.jpg",
            "isRecommend": 0,
            "isTop": 0,
            "viewCount": 0,
            "sort": 0,
            "status": 0,
            "publishTime": "2026-08-05 10:00:00",
            "title": null,
            "subtitle": null,
            "summary": null,
            "author": null,
            "source": null,
            "categoryName": null
        },
        "i18n": [
            {
                "id": 155,
                "createTime": "2026-08-12 10:00:58",
                "updateTime": "2026-08-12 10:00:58",
                "articleId": 73,
                "lang": "en",
                "title": "New Progress in Lancang-Mekong Cooperation",
                "subtitle": "Countries Jointly Promote Regional Connectivity",
                "summary": "Recently, the LMC mechanism has made new progress...",
                "content": "
Detailed content...
",
                "author": "LMC Secretariat",
                "source": "Partner Platform A",
                "seoTitle": null,
                "seoKeywords": null,
                "seoDescription": null
            },
            {
                "id": 154,
                "createTime": "2026-08-12 10:00:58",
                "updateTime": "2026-08-12 10:00:58",
                "articleId": 73,
                "lang": "zh-CN",
                "title": "澜湄合作新进展-更新了",
                "subtitle": "多国共同推进区域互联互通",
                "summary": "近日，澜湄合作机制迎来新进展...",
                "content": "
详细正文内容...
",
                "author": "联盟秘书处",
                "source": "合作伙伴平台A",
                "seoTitle": "澜湄合作新进展 - 官网",
                "seoKeywords": "澜湄,合作,区域互联",
                "seoDescription": "澜湄合作机制最新进展报告"
            }
        ],
        "tags": [
            {
                "tagId": 1,
                "name": "New Tag 1"
            },
            {
                "tagId": 2,
                "name": "标签2"
            }
        ]
    }
}

# 文章不存在
{ "code": 2001, "message": "文章不存在" }

更新文章

路径参数：id — 平台生成的文章 ID（创建时返回的 article.id）

请求体与创建接口字段一致，但均为可选。接口采用部分更新（patch 语义）：仅覆盖请求体中传入的字段，未传入的字段与未传入的语言版本保持原值不变。响应结构与创建接口相同（article 为更新后主表记录，i18n 仅返回本次传入的语言列表）。

# 仅修改 zh-CN 的标题，其余字段与 en 版本均不变
PUT /api/open/v1/cms/article/123
{
  "i18n": [
    { "lang": "zh-CN", "title": "新标题" }
  ]
}

# 仅下架（status=0），其余全不变
PUT /api/open/v1/cms/article/123
{ "status": 0 }

# 清空标签：传空数组（不传 tagIds 字段则保留原标签）
PUT /api/open/v1/cms/article/123
{ "tagIds": [] }

撤稿（逻辑删除）

路径参数：id — 平台生成的文章 ID（创建时返回的 article.id）。

撤销已推送的文章。采用逻辑删除：主表 cms_article 置 deleted=1，数据保留、可恢复；同时级联物理清理 cms_article_i18n、cms_article_tag 关联行，避免孤儿数据。门户侧按 deleted=0 过滤后将不再展示该文章。

DELETE /api/open/v1/cms/article/123

# 成功
{
  "code": 200,
  "message": "success",
  "data": null
}

# 文章不存在
{
  "code": 2002,
  "message": "Article not found",
  "data": null
}

关键返回字段说明

外部平台接入指引

1. 联系管理员创建 OpenApp，勾选 Scope cms:article:write
2. 获取 AppId 和 AppSecret（仅展示一次）
3. 实现 HMAC-SHA256 签名算法（见第 4 章）
4. 调用 GET /api/open/v1/cms/category?lang=zh-CN 获取分类树，确定 categoryId
5. 调用 GET /api/open/v1/cms/tag?lang=zh-CN 获取标签列表，确定 tagIds
6. 构造请求体，计算签名，调用 POST /api/open/v1/cms/article
7. 保存返回的 article.id，后续更新必需
8. 如需更新，调用 PUT /api/open/v1/cms/article/{id}
9. 如需撤稿，调用 DELETE /api/open/v1/cms/article/{id}

推送接口错误码

# 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())

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())

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"

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