L Harness REST API参考:全功能OpenAPI端点清单与调用示例大全
L Harness REST API参考:全功能OpenAPI端点清单与调用示例大全
L Harness 是一款自托管的 LINE 官方账号 CRM 工具,提供步骤消息、群发广播、表单和预约等营销自动化能力。本文是 L Harness REST API 完整参考:汇总全部 OpenAPI 端点清单、认证方式、统一响应格式与常用调用示例,帮助你快速上手用 API 驱动整个 CRM 工作流。
快速开始:认证与 Base URL
所有受保护端点使用 Bearer Token 认证,API Key 通过环境变量 API_KEY 配置:
Authorization: Bearer YOUR_API_KEY
部署后的 Base URL 形如:
https://your-worker.your-subdomain.workers.dev
最简调用示例——获取好友列表(支持分页参数 limit、offset):
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://your-worker.workers.dev/api/friends?limit=50&offset=0"
30秒找到你的 OpenAPI 文档
L Harness 自带交互式 API 文档,无需翻源码即可浏览所有端点:
| 地址 | 说明 |
|---|---|
GET /docs |
Swagger UI 交互式文档界面 |
GET /openapi.json |
OpenAPI 3.1 规范 JSON |
规范定义在 openapi.ts 中,与路由代码同源,保证文档与实际端点一致。完整的端点速查表见 20-API-Reference.md。
统一响应格式:一次看懂所有返回
成功响应
{ "success": true, "data": { } }
错误响应
{ "success": false, "error": "错误信息" }
分页响应
列表接口统一返回分页结构,查询参数为 limit(默认 50)与 offset(默认 0):
{
"success": true,
"data": { "items": [], "total": 150, "page": 1, "limit": 50, "hasNextPage": true }
}
常用状态码
| 状态码 | 含义 |
|---|---|
| 200 / 201 | 成功 / 创建成功 |
| 302 | 重定向(跟踪链接跳转) |
| 400 | 请求参数错误 |
| 401 | 认证失败 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
全功能端点清单:按业务模块速查
以下是核心 REST API 端点总览(所有 /api/* 端点均需 Bearer 认证):
👥 好友与标签(Friends & Tags)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/friends |
好友列表(分页、按标签筛选) |
| GET | /api/friends/count |
好友总数 |
| GET | /api/friends/:id |
好友详情(含标签) |
| POST | /api/friends/:id/tags |
为友添加标签 |
| DELETE | /api/friends/:id/tags/:tagId |
移除标签 |
| POST | /api/friends/:id/messages |
向该友发送消息 |
| GET / POST | /api/friends/:id/score |
查询 / 手动加减评分 |
| GET / POST / DELETE | /api/tags... |
标签的增删查 |
📇 场景步骤消息(Scenarios)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET / POST | /api/scenarios |
场景列表 / 创建(触发类型:friend_add、tag_added、manual) |
| GET / PUT / DELETE | /api/scenarios/:id |
场景详情(含 steps)/ 更新 / 删除 |
| POST | /api/scenarios/:id/steps |
添加步骤(delayMinutes、messageType、条件分支) |
| PUT / DELETE | /api/scenarios/:id/steps/:stepId |
更新 / 删除步骤 |
| POST | /api/scenarios/:id/enroll/:friendId |
手动将友加入场景 |
创建"好友添加后自动欢迎"场景示例:
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"欢迎流程","triggerType":"friend_add"}' \
https://your-worker.workers.dev/api/scenarios
📢 群发广播(Broadcasts)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET / POST | /api/broadcasts |
列表 / 创建(targetType: all、tag、segment) |
| PUT / DELETE | /api/broadcasts/:id |
更新(仅 draft/scheduled)/ 删除 |
| POST | /api/broadcasts/:id/send |
立即发送 |
| POST | /api/broadcasts/:id/send-segment |
按条件圈选人群发送 |
状态流转:draft → scheduled → sending → sent,支持 scheduledAt 定时群发。
📝 表单(Forms)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET / POST | /api/forms |
表单列表 / 创建(字段类型含 text、email、select、date 等 9 种) |
| GET | /api/forms/:id |
表单定义(免认证,供提交页使用) |
| POST | /api/forms/:id/submit |
提交表单(免认证,可联动打标签、入场景) |
| GET | /api/forms/:id/submissions |
回答列表 |
🎯 其他核心模块
| 模块 | 代表端点 | 用途 |
|---|---|---|
| Rich Menus | GET/POST /api/rich-menus |
LINE 富菜单管理与发布 |
| Tracked Links | /api/tracked-links、GET /t/:linkId |
跟踪链接创建与免认证跳转 |
| Reminders | /api/reminders/:id/enroll/:friendId |
按日期预约提醒(如课程、会议) |
| Scoring | /api/scoring-rules |
评分规则(按事件自动加减分) |
| Automations | /api/automations |
事件驱动自动化规则与执行日志 |
| Webhooks | /api/webhooks/incoming、/api/webhooks/outgoing |
外部事件接收(带 secret)与出站通知 |
| Notifications | /api/notifications/rules |
站内通知规则 |
| Chats | /api/chats、/api/operators |
客服会话分配、状态与人工回复 |
| Conversions | /api/conversions/track、/api/conversions/report |
CV 转化记录与报表 |
| Affiliates | /api/affiliates、POST /api/affiliates/click(免认证) |
联盟推广、点击归因与佣金报表 |
| Users | /api/users/:id/link、/api/users/match |
跨账号用户身份打通 |
| Line Accounts | /api/line-accounts |
多 LINE 账号接入与管理 |
| Booking / Events / Webinars | /api/booking、/api/events、/api/webinars |
预约、活动报名与网络研讨会 |
| Entry Routes | /api/entry-routes、/api/traffic-pools |
流量入口路由与流量池分配 |
🌐 免认证公开端点
| 路径 | 说明 |
|---|---|
POST /webhook |
LINE Messaging API Webhook(签名校验) |
GET /docs / GET /openapi.json |
API 文档 |
POST /api/affiliates/click |
联盟点击记录 |
GET /t/:linkId |
跟踪链接跳转 |
POST /api/forms/:id/submit |
表单提交 |
POST /api/integrations/stripe/webhook |
Stripe 支付回调 |
调用示例:客服会话与广播人群圈选
为某位好友的会话指派客服并更新状态:
curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operatorId":"op-001","status":"in_progress"}' \
https://your-worker.workers.dev/api/chats/:chatId
按条件圈选人群发送专属优惠(segment 广播):
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"conditions":{"operator":"AND","rules":[{"field":"tag","value":"VIP"}]}}' \
https://your-worker.workers.dev/api/broadcasts/:id/send-segment
更省事的两种姿势:TypeScript SDK 与 MCP
不想手写 HTTP 调用?官方提供两种更高效的集成方式:
1. TypeScript SDK(@line-harness/sdk) —— 与 Worker API 一一对应,并封装了高阶工作流:
import { LineHarness } from '@line-harness/sdk'
const client = new LineHarness({ apiUrl, apiKey })
// 一次调用创建 3 步教育场景
await client.createStepScenario('欢迎流程', 'friend_add', [
{ delay: '0m', type: 'text', content: '欢迎!感谢添加' },
{ delay: '1d', type: 'text', content: '这三点建议先看看…' },
{ delay: '3d', type: 'flex', content: flexJson },
])
// 一键全员群发 / 按标签群发
await client.broadcastText('周末大促 5 折!')
SDK 用法详情见 packages/sdk/README.md 与 19-SDK-Reference.md。
2. MCP Server —— L Harness 的 API-first 设计天然面向 AI Agent(如 Claude Code)集成,MCP 工具可直接调用上述端点完成自动化运营,源码位于 packages/mcp-server/。
上手路径小结
| 目标 | 推荐路径 |
|---|---|
| 快速了解端点 | 访问部署实例的 GET /docs |
| 机器读取规范 | GET /openapi.json |
| 手动调试 | curl + Bearer Token(见上文示例) |
| 程序化集成 | @line-harness/sdk 或 MCP Server |
| 部署与环境配置 | 21-Deployment.md |
掌握这份端点清单后,你就可以用几行请求把"加好友 → 自动欢迎 → 打标签 → 群发 → 转化追踪"整条营销链路跑通。祝使用愉快 🚀

