演示 API

模拟动作接口文档

从服务发现、模拟请求与幂等，到 CRM 回执、回流任务和重置的项目接口约定。

调用顺序

先 GET 项目服务目录。本说明自定义了本项目的动作字段，第三方 Agent 是否采用取决于其实现。

创建临时演示会话 POST /api/demo/session
提交模拟咨询或预约 POST /api/demo/actions
读取本会话所选行业的回执 POST /api/demo/state
为已有线索生成优化待办 POST /api/demo/feedback
清除当前会话指定行业的闭环 POST /api/demo/reset

请求与回执

所有 POST 使用 application/json（UTF-8），最大 8192 字节。先向 /api/demo/session 提交 {}，201 响应提供 session_id 和 expires_in。将返回值作为后续请求头 X-Demo-Session。请只在自己的演示会话内使用。

模拟咨询示例

必填行业、服务、动作、问题和同意标记。可选 case_id 为 case- 加小写 UUIDv4。预约示例将 action 改为 appointment。不会写入日历或创建真实预约。

POST /api/demo/actions
Content-Type: application/json
X-Demo-Session: <当前临时会话>
Idempotency-Key: demo-guide-001

{
  "scenario": "seal",
  "service_id": "svc-seal",
  "action": "inquiry",
  "question_id": "q1",
  "consent": true,
  "attribution": {
    "ai_source": "demo-agent",
    "landing_page": "/guides/seal",
    "utm_campaign": "demo-growth"
  },
  "input_sources": {
    "ai_source": "demo",
    "landing_page": "form",
    "utm_campaign": "query"
  }
}

同一会话内，8–80 位字母、数字、短横线或下划线组成的幂等键标识一次动作。首次返回 201，相同业务参数重放返回 200 和同一线索 ID。不同参数复用同键返回 409。程序单独创建的会话可在工作台「数据报告 → 载入程序调用的回执」中输入临时标识，并在该标签页核对同一案例。以下是成功回执的字段节选，完整响应见 OpenAPI。

{
  "simulated": true,
  "replayed": false,
  "request_id": "req-12345678-1234-4567-8123-123456789012",
  "lead": {
    "scenario": "seal",
    "service_id": "svc-seal",
    "question_id": "q1",
    "stage": 0,
    "attribution": {
      "utm_campaign": {
        "value": "demo-growth",
        "source": "query",
        "verified": false
      }
    }
  },
  "feedback_task": null
}

state 与 reset 的请求体为 {"scenario":"seal"}； feedback 请求体为 {"request_id":"本次回执编号"}。相同反馈重复提交会返回原待办。

归因字段和证据边界

任意来源值都只是自报或观察到的线索。每项返回 value、source 和 verified。verified 恒为 false。缺失项返回 null、unknown、false。

ai_source 接受 demo-agent, demo-form, demo-search，ai_platform 接受 demo-lab, demo-assistant。
agent_id、conversation_id 以 demo- 开头，后接字母或数字，限 64 字符。X-Demo-Agent 可补充缺失的 agent_id。
utm_source、utm_medium、utm_campaign、utm_term、utm_content 以英文字母开头，限 48 个字母、数字、短横线、下划线。
citation_url、landing_page、referrer 只记录本站公开路径（首页、三份指南、目录和接口文档），丢弃查询与片段。同源 Referer 可提供来源页线索。外部引荐地址不入库。系统不会访问所填链接。
input_sources 可标注 form、query 或 demo。请求头来源为 header，来源标记同样未经证实。

存储、限流与失败重试

单进程内存会话自创建起 30 分钟失效，下一次调用时回收。单会话每分钟最多 12 次动作或反馈，同一连接来源每分钟 12 次会话创建、120 次 API 请求，全进程每分钟 600 次。最多 128 个活动会话、每会话每行业 12 个幂等记录、全进程 512 个。重启服务会清空内存。

首次动作可设 simulate_failure=true，503 后相同请求可手动重试。没有持久重试队列。浏览器保存当前标签页的会话和跟进状态。重置只清除此会话所选行业的闭环。

错误响应

格式为 {"simulated":true,"error":{"code":"…","message":"…"}}。限流时可读取 Retry-After。

400 invalid_json / invalid_length　正文须为有效 UTF-8 JSON 对象。键名不能重复，长度必须与声明一致。
401 session_required / session_expired　模拟会话缺失或已到期。新会话不能读取原会话数据。
403 origin_forbidden / consent_required　浏览器来源不匹配，或尚未同意处理模拟请求。
404 not_found / receipt_not_found　端点或当前会话的请求记录不存在。
405 method_not_allowed　本接口只接受 POST。
409 idempotency_conflict　已用幂等键与本次业务参数冲突。
411 length_required　请提供 Content-Length。
413 payload_too_large　JSON 请求体超过 8192 字节。
415 unsupported_media_type　请使用 application/json，无压缩正文。
422 invalid_input　字段、类型、来源标签、链接或行业与服务映射不符合约定。
429 rate_limited / capacity_limited　达到速率或内存容量边界。查看 Retry-After。
503 crm_unavailable　本次模拟交付失败。可用相同会话、相同业务参数和幂等键手动重试。

接入真实服务前

真实 CRM、邮件、订单、日历、支付及 Webhook 均未接入。启用须先确认系统所有者、接收方、允许字段、用户同意和保留期限，再设计服务端身份与权限、企业隔离、密钥托管与轮换、签名与防重放、审计脱敏、持久幂等和受控重试。本演示无需配置商业凭据。