密令管理系统 · 开放 API 对接文档

1. 概述

开放 API 供企业系统对接密令管理能力，支持：批量申请密令、查询密令（含可投放的推广链接）、续期、触发审核状态同步、统计。

• 协议：HTTP POST/GET，请求与响应均为 JSON（UTF-8）
• 所有业务接口均需携带 API Key（见 鉴权说明），仅健康检查 /open/v1/ping 免鉴权
• 开放 API 与管理台登录体系相互独立，使用 /open/v1 前缀区分

2. 快速开始（三步接入）

1. 向管理员申请 API Key（形如 kl_xxxxxxxxxxxxxxxx）
2. 调用 GET /open/v1/accounts 获取可用的 account_id，调用 GET /open/v1/keywords 确认连通性
3. 按业务调用 POST /open/v1/keywords/apply 申请密令，之后轮询 GET /open/v1/keywords?status=approved 获取生效密令及推广链接

3. 鉴权说明

除 /open/v1/ping 外，所有请求必须携带 API Key，支持以下两种方式（任选其一）：

• API Key 由管理员在管理台「开放 API」页签创建，仅在创建时完整展示一次，请妥善保存
• Key 泄漏或更换时应通知管理员禁用/重建；被禁用的 Key 立即失效

4. 通用约定

4.1 响应格式

所有接口统一返回三段式结构：

{"code": 0, "message": "ok", "data": { ... } }

• code：0 表示成功；失败时为对应的 HTTP 状态码（401 / 404 / 422 / 429 等），此时 data 为空、message 为错误说明
• HTTP 状态码与 code 保持一致，可按 HTTP 状态码做统一拦截

4.2 时间格式

ISO 8601 本地时间字符串，例如 2026-11-14T08:30:00；days_left 为距离有效期结束的剩余天数（整数，负数表示已过期）。

4.3 分页约定

• page 从 1 开始；page_size 默认 20，最大 100
• 列表接口返回 total / page / page_size / list

4.4 限流

每个 API Key 每分钟 60 次。超出返回 429，请降低频率或合并批量操作（如批量申请一次提交多个关键词）。建议轮询间隔不低于 30 秒。

4.5 请求格式

POST 接口请求体为 JSON，务必携带 Content-Type: application/json；GET 接口参数放 URL query。

5. 接口详情

5.1 健康检查 免鉴权

用于探活与连通性验证，不消耗限流配额。

响应示例：

{
  "code": 0,
  "message": "ok",
  "data": { "service": "kouling", "version": "v1", "time": "2026-10-11T00:54:12" }
}

5.2 账号列表 需鉴权

获取系统中可用的投放账号，其 id 用于申请密令时指定 account_id。

响应 data：

[
  { "id": 1, "name": "测试账号", "status": "ok" }
]

5.3 批量申请密令 需鉴权

批量提交密令申请，逐条独立处理，部分失败不影响其余条目。

请求体：

请求示例：

curl -X POST "{BASE}/open/v1/keywords/apply" \
  -H "X-API-Key: kl_xxx" -H "Content-Type: application/json" \
  -d '{
    "account_id": 1,
    "items": [
      { "keyword": "618大促", "sub_media_id": "1000499921", "promotion_bit_id": "6431480", "material_id": 866 },
      { "keyword": "外卖红包", "sub_media_id": "1000499921", "promotion_bit_id": "6431480", "material_id": 866, "valid_days": 30 }
    ]
  }'

响应 data（逐条结果）：

[
  { "keyword": "618大促", "ok": true,  "message": "申请已提交", "order_id": 9 },
  { "keyword": "外卖红包", "ok": false, "message": "推广位不存在，请先同步推广位", "order_id": 10 }
]

5.4 查询密令列表（含推广链接） 需鉴权

分页查询密令。要获取可直接投放的链接，请传 status=approved，取结果中的 promotion_link。

Query 参数：

响应 data：

{
  "total": 8, "page": 1, "page_size": 20,
  "list": [
    {
      "id": 2,
      "keyword": "测试1122311",
      "platform": "meituan",
      "status": "approved",
      "sub_media_name": "e推联盟",
      "promotion_bit_name": "自营测试",
      "material_id": 7,
      "valid_start": "2026-10-17T08:30:00",
      "valid_end": "2026-11-13T08:30:00",
      "days_left": 33,
      "promotion_link": "imeituan://www.meituan.com/takeout/browser?inner_url=...",
      "created_at": "2026-10-11T00:54:12"
    }
  ]
}

5.5 密令详情 需鉴权

返回单条密令，字段同 5.4 列表项。密令不存在返回 404。

5.6 续期密令 需鉴权

对指定密令以相同配置（关键词/推广位/素材/城市）重新申请新一期有效期，生成一条新记录并关联原记录。

请求体：

• 该密令已有「审核中或生效中」的续期记录时返回 400，避免重复续期
• source=jhtg 的记录（经 5.9 apply-by-sid 创建）只能经本开放 API 续期：管理后台手动续期与系统自动续期均不处理
• 系统到期前 3 天的自动续期仅对后台手动来源（source=manual）的记录生效；jhtg 来源是否续期、何时续由调用方按订单门槛决定

响应 data：

{
  "order_id": 12,
  "status": "applying",
  "valid_start": "2026-10-26T10:00:00",
  "valid_end": "2026-11-25T10:00:00"
}

order_id 为新生成记录的编号，valid_start / valid_end 为新有效期起止（ISO 时间）。

5.7 触发状态同步 需鉴权

从平台拉取最新审核记录：更新已有密令状态、导入平台新增记录。系统每 30 分钟自动执行一次，对接方在申请后可主动调用以尽快拿到审核结果。

Query 参数：account_id（可选，不传则同步全部账号）。

响应 data：

[
  { "account": "测试账号", "ok": true, "message": "同步完成：更新 0 条，导入 2 条" }
]

5.8 统计概览 需鉴权

响应 data：

{
  "total": 8, "applying": 0, "approved": 2,
  "expired": 6, "expiring_7d": 0
}

5.9 按 sid 申请密令（聚合推广系统对接） 需鉴权

供聚合推广系统等消费方使用：调用方只知道自己侧的媒体 ID 与推广位 sid，由本系统反查账号与推广位后代为提交申请。六步流程：校验平台 → 按 sub_media_id 反查绑定账号 → 按 sid 查推广位（找不到先刷新该媒体推广位再找一次）→ 占用判重（过期记录先置 expired，同账号同词在途/生效则拒绝）→ 调平台申请 → 落库（source=jhtg）并返回新记录编号与有效期。

请求体：

响应 data（形同 5.6 续期，返回新记录）：

{
  "order_id": 15,
  "status": "applying",
  "valid_start": "2026-10-26T10:00:00",
  "valid_end": "2026-11-25T10:00:00"
}

业务错误统一返回 {"code": 状态码, "message": "说明", "data": {"error": "错误码"}}，错误码如下：

5.10 查询密令词占用 需鉴权

申请前预检：查询密令词是否已被任一账号的在途（applying）或生效（approved）记录占用（全局视角，与 5.9 的同账号判重口径不同）。已过有效期、被驳回或申请失败的记录不算占用；查询会先把过期记录置为 expired，与申请判重同口径。

Query 参数：

响应 data：

{ "occupied": false }

请求示例：

curl "{BASE}/open/v1/keywords/check?keyword=外卖红包&platform=meituan" -H "X-API-Key: kl_xxx"

5.11 批量查询密令状态 需鉴权

按记录编号批量查询密令状态：按传入 ids 的顺序返回存在的记录，不存在的编号自动跳过（不报错）。适合消费方申请后轮询终态。

请求体：

请求示例：

curl -X POST "{BASE}/open/v1/keywords/batch-get" \
  -H "X-API-Key: kl_xxx" -H "Content-Type: application/json" \
  -d '{ "ids": [12, 15, 999] }'

响应 data（上例中 999 不存在，返回 2 条）：

[
  {
    "order_id": 12,
    "keyword": "外卖红包",
    "platform": "meituan",
    "status": "approved",
    "valid_start": "2026-10-26T10:00:00",
    "valid_end": "2026-11-25T10:00:00",
    "reject_reason": null,
    "renewal_of_id": null,
    "source": "jhtg"
  },
  {
    "order_id": 15,
    "keyword": "618大促",
    "platform": "meituan",
    "status": "rejected",
    "valid_start": null,
    "valid_end": null,
    "reject_reason": "素材不合规",
    "renewal_of_id": 12,
    "source": "manual"
  }
]

6. 密令状态说明

7. 错误码一览

错误响应示例：

HTTP 401
{ "code": 401, "message": "API Key 无效或已禁用" }

8. 对接示例代码

8.1 查询生效密令并取推广链接 — Python

import requests

BASE = "{BASE}"
HEADERS = {"X-API-Key": "kl_xxx"}

# 1) 拉取生效中的密令
r = requests.get(f"{BASE}/open/v1/keywords",
                 params={"status": "approved", "page": 1, "page_size": 50},
                 headers=HEADERS, timeout=15).json()
assert r["code"] == 0, r["message"]

for item in r["data"]["list"]:
    print(item["keyword"], item["promotion_link"], f"剩余{item['days_left']}天")

# 2) 批量申请（如需要）
r = requests.post(f"{BASE}/open/v1/keywords/apply",
                  headers=HEADERS, timeout=30,
                  json={"account_id": 1, "items": [{
                      "keyword": "618大促",
                      "sub_media_id": "1000499921",
                      "promotion_bit_id": "6431480",
                      "material_id": 866,
                  }]}).json()
print(r["data"])

8.2 查询生效密令 — Node.js（fetch）

const BASE = "{BASE}";
const res = await fetch(`${BASE}/open/v1/keywords?status=approved`, {
  headers: { "X-API-Key": "kl_xxx" },
});
const body = await res.json();
if (body.code !== 0) throw new Error(body.message);
for (const item of body.data.list) {
  console.log(item.keyword, item.promotion_link);
}

8.3 申请后轮询拿结果 — curl

# 1. 申请
curl -X POST "{BASE}/open/v1/keywords/apply" -H "X-API-Key: kl_xxx" \
     -H "Content-Type: application/json" \
     -d '{"items":[{"keyword":"618大促","sub_media_id":"1000499921","promotion_bit_id":"6431480","material_id":866}]}'

# 2. 等 1 分钟后同步
curl -X POST "{BASE}/open/v1/sync" -H "X-API-Key: kl_xxx"

# 3. 查询生效密令
curl "{BASE}/open/v1/keywords?status=approved" -H "X-API-Key: kl_xxx"

9. 常见问题 FAQ

Q1：申请密令后多久能拿到推广链接？

平台审核通常数秒完成，但需等系统同步后才能查到。建议：申请 → 约 1 分钟后调 POST /open/v1/sync → 查 status=approved 拿 promotion_link。系统另每 30 分钟自动同步一次。

Q2：promotion_link 可以直接投放吗？

可以。它是美团联盟生成的跳转链接（imeituan://...），用户在美团 App 内打开即跳转对应活动页。请勿自行拼接或修改参数。

Q3：同一关键词可以重复申请吗？

同一关键词 + 同一推广位在有效期内不建议重复申请（平台会占用审核资源）。到期需要继续使用时调 renew 接口；系统到期前 3 天的自动续期仅针对后台手动来源（source=manual）的记录，jhtg 来源是否续期由调用方决定。

Q4：返回 429 怎么办？

已触发限流（每 Key 每分钟 60 次）。轮询间隔建议 ≥30 秒；批量申请合并为一次调用（items 数组）。

Q5：API Key 忘了 / 泄漏了怎么办？

联系管理员：管理台「开放 API」页签可查看完整 Key、禁用或重建。泄漏请立即禁用。

Q6：sub_media_id / promotion_bit_id / material_id 从哪里获取？

由管理员在管理台提供（管理台「申请密令」页可选择媒体与推广位并看到对应 ID）。素材 ID 为美团联盟素材编号。

10. 变更记录

后续新平台（淘宝联盟 / 京东联盟）接入时，将在现有端点上增加 platform 参数或新增前缀，届时在此页更新变更记录。