Developers / API Reference

把能力，
变成接口。

同一套 REST + JSON 接口，连接官网、小程序、ERP 与企业微信。先读结构，再接沙箱。本页为文档结构与交互示意，正式域名、密钥与 SDK 待开通。

v1RESTJSONBearerWebhook中文 / EN

快速开始 QUICK START

所有接口使用 HTTPS 与 JSON。请求需带上租户令牌，响应统一返回 request_id，便于排查链路问题。

BASE URL示例域名 · 待开通
https://api.yunbu.example/v1
1
申请令牌提交企业信息与用途，开通测试租户。
2
调用接口用 Bearer Token 调用智能体、线索或订单接口。
3
订阅事件配置 Webhook，接收线索、订单与工单变化。
示意说明：以上域名为占位地址，实际域名、密钥与沙箱环境待补充。示例数据不代表真实客户。

鉴权 AUTHENTICATION

在请求头中携带 Authorization: Bearer <token>。令牌绑定租户与权限范围，不同环境使用不同令牌。

REQUESTcurl
curl https://api.yunbu.example/v1/leads \
  -H "Authorization: Bearer $YUNBU_API_KEY" \
  -H "Content-Type: application/json"
安全：密钥只在服务端使用，不要写入前端代码、公开仓库或小程序包。泄露后立即在控制台轮换。

智能体对话 POST /v1/agent/chat

把客户问题交给企业知识库驱动的智能体，返回回答、引用与用量。可指定 agent 与租户上下文。

REQUEST BODYapplication/json
{
  "agent": "growth-os",
  "tenant": "yunbu-demo",
  "message": "官网询盘少，怎么接？",
  "context": { "source": "website", "channel": "web" }
}
RESPONSE200 OK
{
  "request_id": "req_demo_001",
  "reply": "先接住询盘，再谈投放……",
  "citations": ["kb_growth_01"],
  "usage": { "tokens": 128 }
}
字段类型说明
agentstring智能体标识，默认 growth-os。
messagestring用户问题，建议不超过 2000 字。
contextobject来源、渠道、页面等上下文，可选。
replystring智能体回答，正式环境附带引用。

线索写入 POST /v1/leads

官网表单、小程序与广告落地页统一写入线索池，自动去重并标记来源。

REQUEST BODYapplication/json
{
  "name": "张先生",
  "company": "示例制造",
  "contact": "待补充",
  "source": "website",
  "need": "官网 + 小程序"
}
RESPONSE201 Created
{
  "request_id": "req_demo_002",
  "id": "lead_demo_88",
  "status": "new"
}
隐私：正式上线前需补充隐私政策与授权文案；联系方式只存储于受控租户，不写入日志。

订单查询 GET /v1/orders

按状态与时间分页查询订单，用于对账、交付排期与经营看板。

REQUESTquery
GET /v1/orders?page=1&limit=20&status=paid
RESPONSE200 OK
{
  "items": [
    { "id": "ord_demo_01", "amount": 19800, "status": "paid" }
  ],
  "page": 1,
  "total": 1
}

金额单位为分，示例金额为评审示意，不代表真实报价。

知识库检索 POST /v1/knowledge/search

在企业知识库中做语义检索，返回片段、来源与相关度，用于智能客服与内部助手。

REQUEST BODYapplication/json
{
  "query": "代运营包含哪些服务",
  "top_k": 3
}
RESPONSE200 OK
{
  "chunks": [
    { "id": "kb_ops_02", "score": 0.92, "text": "策略、内容、投放……" }
  ]
}

Webhook EVENTS

订阅业务事件，系统以 POST 推送 JSON。请校验签名并做幂等处理。

事件触发时机用途
lead.created新线索写入通知销售、写入 CRM
order.paid订单支付成功开通服务、触发交付
ticket.updated工单状态变化同步企微、通知客户
HEADERSsignature
X-Yunbu-Signature: t=1730000000,v1=<hmac-sha256>

签名原文为 t + "." + body，使用 Webhook 密钥做 HMAC-SHA256。时间戳超过 5 分钟视为过期。

错误码 ERRORS

状态码含义处理建议
400参数缺失或格式错误检查字段类型与必填项
401令牌缺失或失效重新签发并在服务端配置
403权限范围不足申请对应 scope
404资源不存在确认租户与资源 ID
429触发限流按响应头退避重试
500服务异常带 request_id 联系技术支持

错误响应统一包含 request_id 与 message，不要在客户端直接展示原始错误。

限流与版本 LIMITS & VERSIONING

  • 限流：默认 60 次 / 分钟 / 令牌，生产环境按合同调整（示意）。
  • 重试：遇到 429 或 5xx，按指数退避重试，最多 3 次。
  • 版本：路径包含版本号，破坏性变更发布新版本，旧版本保留过渡期。
  • 幂等：写入接口支持 Idempotency-Key，重复请求不会重复创建。
当前状态：文档结构为评审示意，正式域名、SDK、沙箱与 SLA 待开通后补充。
↑