L Harness REST API参考:全功能OpenAPI端点清单与调用示例大全

原创2026-11-16 17:47:481,712 阅读

L Harness REST API参考:全功能OpenAPI端点清单与调用示例大全

L Harness 是一款自托管的 LINE 官方账号 CRM 工具,提供步骤消息、群发广播、表单和预约等营销自动化能力。本文是 L Harness REST API 完整参考:汇总全部 OpenAPI 端点清单、认证方式、统一响应格式与常用调用示例,帮助你快速上手用 API 驱动整个 CRM 工作流。

L Harness REST API 管理面板界面:聊天列表、消息会话与好友详情


快速开始:认证与 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

L Harness API 驱动的客服聊天界面:旧版操作员聊天布局

按条件圈选人群发送专属优惠(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

掌握这份端点清单后,你就可以用几行请求把"加好友 → 自动欢迎 → 打标签 → 群发 → 转化追踪"整条营销链路跑通。祝使用愉快 🚀

登录后查看全文
line-harness-oss