Reference / REST
REST API 参考
HumanAPI 的全部 HTTP 端点。除三个公开探针外,所有端点都需要 API Key;列表端点返回统一的分页包络,写操作使用明确的资源状态机。
规范版本 v2.0.0
基础路径 /api
内容类型 application/json
限流 120 次 / 60s
01 / Endpoints
端点总览
本地开发时基础 URL 为 http://localhost:3000,所有路径相对于 /api。标注“公开”的端点无需认证,其余端点需要 Bearer Token 或 x-api-key。
| 方法 | 路径 | 说明 | 认证 |
| GET | /api | 服务信息与版本 | 公开 |
| GET | /api/health | 存活探针(liveness) | 公开 |
| GET | /api/ready | 就绪探针,探测 PostgreSQL | 公开 |
| GET | /api/humans | 检索专家档案 | API Key |
| POST | /api/humans | 注册专家档案 | API Key |
| GET | /api/humans/:id | 档案详情与最近评价 | API Key |
| PUT | /api/humans/:id | 部分更新档案 | API Key |
| GET | /api/humans/:id/reviews | 分页读取专家评价 | API Key |
| GET | /api/tasks | 任务列表 | API Key |
| POST | /api/tasks | 创建任务并匹配专家 | API Key |
| GET | /api/tasks/:id | 任务详情 | API Key |
| PUT | /api/tasks/:id | 更新任务 | API Key |
| DELETE | /api/tasks/:id | 删除任务 | API Key |
| GET | /api/bookings | 预约列表 | API Key |
| POST | /api/bookings | 创建预约(原子抢占) | API Key |
| GET | /api/bookings/:id | 预约详情 | API Key |
| PUT | /api/bookings/:id | 修改预约时间 | API Key |
| POST | /api/bookings/:id/:action | 预约状态迁移 | API Key |
| POST | /api/bookings/:id/reviews | 提交评价 | API Key |
| GET | /api/bookings/:id/messages | 读取预约消息 | API Key |
| POST | /api/bookings/:id/messages | 发送预约消息 | API Key |
| POST | /api/bookings/:id/disputes | 创建争议 | API Key |
| GET | /api/disputes | 争议列表 | API Key |
| GET | /api/disputes/:id | 争议详情 | API Key |
| PUT | /api/disputes/:id | 更新争议状态 | API Key |
| GET | /api/mcp | MCP 工具清单 | API Key |
| POST | /api/mcp | 调用 MCP 工具 | API Key |
02 / Authentication
认证
除 GET /api、GET /api/health、GET /api/ready 三个公开端点外,所有私有端点都需要 API Key。支持两种等价方式:
Authorization: Bearer <API_KEY>
x-api-key: <API_KEY>
服务端以常量时间比较校验 Key;缺失或不匹配返回 401,并带 WWW-Authenticate: Bearer 响应头。若服务端未配置 API_KEY 环境变量,私有端点返回 503。
请求示例
// 任选一种认证头,效果相同
const apiKey = process.env.HUMANAPI_API_KEY;
const response = await fetch("http://localhost:3000/api/humans", {
headers: {
authorization: `Bearer ${apiKey}`,
// 或使用: "x-api-key": apiKey,
},
});
if (response.status === 401) {
throw new Error("API Key 缺失或无效");
}
安全提示:API Key 只应保存在服务端环境或 MCP 客户端环境中,不要写入浏览器端代码或提交进仓库。
03 / Conventions
约定
统一响应包络
所有端点返回 JSON。成功时为 { "success": true, "data": ..., "pagination"?: {...} };失败时为 { "success": false, "error": "...", "details"?: [{ "field", "message" }] }。
成功 · 列表
{
"success": true,
"data": [],
"pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}
失败 · 校验错误
{
"success": false,
"error": "Validation failed",
"details": [
{ "field": "rating", "message": "rating must be at most 5" }
]
}
ID 语义
| 字段 | 含义 |
id / humanId(humans 相关) | HumanProfile.id,专家档案主键 |
agentId / userId / reviewerId / senderId / reporterId | User.id,用户主键 |
taskId / bookingId / disputeId / messageId | 各资源自主键 |
时间与金额
- 时间字段使用 ISO 8601 字符串(含时区偏移),如
2026-11-05T02:00:00.000Z。
estimatedDuration 单位为分钟;maxDistance 与 distance 单位为米。
- 金额字段
paymentAmount 与 hourlyRate 跟随 currency 字段(默认 CNY)。
04 / Service
服务信息
三个公开端点用于服务发现与部署探活,均无需认证。
GET
/api
公开
服务信息。version 字段来自 package.json。
响应示例 · 200
{
"name": "HumanAPI",
"version": "2.0.0",
"description": "Humans as a Service - 让人类成为可调用的 API",
"baseUrl": "http://localhost:3000",
"endpoints": {
"mcp": "/api/mcp",
"humans": "/api/humans",
"tasks": "/api/tasks",
"bookings": "/api/bookings"
},
"documentation": "https://github.com/bit-cook/HumanAPI"
}
GET
/api/health
公开
存活探针(liveness):只报告进程状态,不检查数据库。返回 status、timestamp、uptime、version。
响应示例 · 200
{
"status": "ok",
"timestamp": "2026-10-29T08:30:00.000Z",
"uptime": 3612.48,
"version": "2.0.0"
}
GET
/api/ready
公开
就绪探针(readiness):执行 SELECT 1 探测 PostgreSQL。数据库不可用时返回 503。
响应示例 · 200 / 503
{ "status": "ready", "version": "2.0.0" }
{ "status": "not_ready", "version": "2.0.0" }
05 / Humans
专家 humans
专家档案(HumanProfile)是匹配与预约的核心资源。默认只返回 verified: true 的档案。
GET
/api/humans
需要 API Key
按技能、位置、费率、评分与可用性检索专家,按用户评分降序返回。
查询参数
| 参数 | 类型 | 默认 | 说明 |
skills | string | — | 逗号分隔,要求全部命中(verified 技能) |
lat / lon | number | — | 须同时提供;提供后元素附带 locationMatch 与 distance(米) |
maxDistance | number | 10000 | 最大距离(米) |
rateMin | number | 0 | 最低时薪 |
rateMax | number | 999999 | 最高时薪 |
ratingMin | number | 0 | 最低评分(0–5) |
availableNow | boolean | true | 仅返回当前可接单的专家 |
page | number | 1 | 页码 |
limit | number | 20 | 每页数量,最大 100 |
请求示例
const query = new URLSearchParams({
skills: "现场调研",
lat: "31.2304",
lon: "121.4737",
maxDistance: "5000",
ratingMin: "4",
rateMax: "200",
availableNow: "true",
page: "1",
limit: "20",
});
const response = await fetch(`http://localhost:3000/api/humans?${query}`, {
headers: { authorization: `Bearer ${process.env.HUMANAPI_API_KEY}` },
});
const { data, pagination } = await response.json();
响应示例 · 200
{
"success": true,
"data": [
{
"id": "hp_9k2f71xa",
"userId": "usr_4c8d10be",
"name": "林晓",
"avatar": null,
"rating": 4.8,
"totalReviews": 126,
"skills": [{ "name": "现场调研", "verified": true }],
"hourlyRate": 150,
"currency": "CNY",
"available": true,
"verified": true,
"totalTasks": 87,
"successRate": 0.97,
"location": { "lat": 31.2304, "lon": 121.4737, "city": "上海", "country": "中国" },
"certifications": [],
"locationMatch": true,
"distance": 1250
}
],
"pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}
元素字段:id、userId、name、avatar、rating、totalReviews、skills、hourlyRate、currency、available、verified、totalTasks、successRate、location、certifications;提供 lat/lon 时追加 locationMatch 与 distance。
POST
/api/humans
需要 API Key
注册专家档案。技能的 verified 一律置 false;该用户已存在档案时返回 400。
请求体
| 字段 | 类型 | 必填 | 说明 |
userId | string | 是 | User.id,档案归属用户 |
location | object | 是 | { lat, lon, address?, city?, country? } |
skills | array | 是 | [{ name }] 技能条目 |
hourlyRate | number | 是 | 时薪 |
currency | string | 否 | 币种,默认 CNY |
bio | string | 否 | 个人简介 |
请求示例
const response = await fetch("http://localhost:3000/api/humans", {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
userId: "usr_4c8d10be",
location: { lat: 31.2304, lon: 121.4737, city: "上海", country: "中国" },
skills: [{ name: "现场调研" }],
hourlyRate: 150,
currency: "CNY",
bio: "十年市场调研经验,可承接线下访谈与数据收集。",
}),
});
const profile = await response.json();
响应示例 · 201
{
"success": true,
"data": {
"id": "hp_9k2f71xa",
"userId": "usr_4c8d10be",
"skills": [{ "name": "现场调研", "verified": false }],
"hourlyRate": 150,
"currency": "CNY",
"available": true,
"verified": false,
"totalTasks": 0,
"successRate": 0
}
}
GET
/api/humans/:id
需要 API Key
档案详情,附带最近 10 条评价。:id 为 HumanProfile.id;不存在时返回 404。
响应示例 · 200
{
"success": true,
"data": {
"id": "hp_9k2f71xa",
"userId": "usr_4c8d10be",
"name": "林晓",
"avatar": null,
"rating": 4.8,
"totalReviews": 126,
"bio": "十年市场调研经验,可承接线下访谈与数据收集。",
"skills": [{ "name": "现场调研", "verified": true }],
"hourlyRate": 150,
"currency": "CNY",
"available": true,
"verified": true,
"totalTasks": 87,
"successRate": 0.97,
"location": { "lat": 31.2304, "lon": 121.4737, "city": "上海" },
"certifications": [],
"recentReviews": [
{
"id": "rev_5m2ka91x",
"rating": 5,
"comment": "响应迅速,报告完整。",
"createdAt": "2026-09-18T09:12:00.000Z"
}
]
}
}
PUT
/api/humans/:id
需要 API Key
部分更新档案,可改字段:bio、location、skills、hourlyRate、currency、available。档案不存在返回 404。
请求示例
const humanId = "hp_9k2f71xa";
const response = await fetch(`http://localhost:3000/api/humans/${humanId}`, {
method: "PUT",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
hourlyRate: 180,
available: false,
bio: "十月排期已满,十一月开放预约。",
}),
});
响应示例 · 200
{
"success": true,
"data": {
"id": "hp_9k2f71xa",
"hourlyRate": 180,
"available": false,
"bio": "十月排期已满,十一月开放预约。",
"updatedAt": "2026-10-29T08:45:00.000Z"
}
}
GET
/api/humans/:id/reviews
需要 API Key
分页读取某位专家收到的评价。
查询参数
| 参数 | 类型 | 默认 | 说明 |
page | number | 1 | 页码 |
limit | number | 20 | 每页数量,最大 100 |
响应示例 · 200
{
"success": true,
"data": [
{
"id": "rev_5m2ka91x",
"bookingId": "bkg_5t8wa31q",
"reviewerId": "usr_2b71de04",
"rating": 5,
"comment": "响应迅速,报告完整。",
"createdAt": "2026-09-18T09:12:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 126, "totalPages": 7 }
}
06 / Tasks
任务 tasks
任务描述需要人类介入的工作。status 取值:DRAFT、OPEN、ASSIGNED、IN_PROGRESS、COMPLETED、CANCELLED。
GET
/api/tasks
需要 API Key
任务列表,按创建时间降序,附带 agent / human 摘要。
查询参数
| 参数 | 类型 | 默认 | 说明 |
status | enum | — | DRAFT / OPEN / ASSIGNED / IN_PROGRESS / COMPLETED / CANCELLED |
agentId | string | — | 按发起方 User.id 过滤 |
humanId | string | — | 按执行方 User.id 过滤 |
page | number | 1 | 页码 |
limit | number | 20 | 每页数量,最大 100 |
响应示例 · 200
{
"success": true,
"data": [
{
"id": "tsk_7h3kd92m",
"agentId": "usr_2b71de04",
"humanId": null,
"title": "线下门店巡查",
"description": "拍摄三家门店的陈列照片并填写检查表。",
"skills": ["现场调研", "摄影"],
"status": "OPEN",
"priority": "NORMAL",
"location": { "lat": 31.2304, "lon": 121.4737, "city": "上海" },
"scheduledTime": "2026-11-05T02:00:00.000Z",
"estimatedDuration": 120,
"paymentAmount": 300,
"currency": "CNY",
"agent": { "id": "usr_2b71de04", "name": "ResearchBot" },
"human": null,
"createdAt": "2026-10-28T10:00:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 8, "totalPages": 1 }
}
POST
/api/tasks
需要 API Key
创建任务,返回任务本身与前 10 名匹配专家(matchedHumans,元素带五维 score:技能、位置、评分、可用性、价格)。
请求体
| 字段 | 类型 | 必填 | 说明 |
agentId | string | 是 | 发起方 User.id |
title | string | 是 | 标题 |
description | string | 是 | 任务描述 |
skills | string[] | 是 | 所需技能 |
location | object | 是 | { lat, lon, address?, city?, country? } |
scheduledTime | string | 否 | 计划执行时间(ISO 8601) |
estimatedDuration | number | 是 | 预计时长(分钟) |
paymentAmount | number | 是 | 报酬金额 |
currency | string | 否 | 币种,默认 CNY |
priority | string | 否 | 优先级 |
请求示例
const response = await fetch("http://localhost:3000/api/tasks", {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
agentId: "usr_2b71de04",
title: "线下门店巡查",
description: "拍摄三家门店的陈列照片并填写检查表。",
skills: ["现场调研", "摄影"],
location: { lat: 31.2304, lon: 121.4737, city: "上海" },
scheduledTime: "2026-11-05T02:00:00.000Z",
estimatedDuration: 120,
paymentAmount: 300,
currency: "CNY",
priority: "NORMAL",
}),
});
const { task, matchedHumans } = (await response.json()).data;
响应示例 · 201
{
"success": true,
"data": {
"task": {
"id": "tsk_7h3kd92m",
"status": "OPEN",
"title": "线下门店巡查",
"createdAt": "2026-10-28T10:00:00.000Z"
},
"matchedHumans": [
{
"id": "hp_9k2f71xa",
"name": "林晓",
"hourlyRate": 150,
"rating": 4.8,
"score": {
"skills": 1,
"location": 0.92,
"rating": 0.96,
"availability": 1,
"price": 0.75,
"total": 0.93
}
}
]
}
}
GET
/api/tasks/:id
需要 API Key
任务详情,含关联的 booking 与 messages。不存在返回 404。
PUT
/api/tasks/:id
需要 API Key
更新任务。仅 DRAFT / OPEN 且未被预约的任务可编辑,否则返回 409。
DELETE
/api/tasks/:id
需要 API Key
删除任务。同样仅限 DRAFT / OPEN 且未预约,否则 409;成功返回 200。
07 / Bookings
预约 bookings
预约把任务与专家绑定,并通过明确的状态机推进:PENDING → CONFIRMED → IN_PROGRESS → COMPLETED,任意非终态可进入 CANCELLED 或 DISPUTED。
GET
/api/bookings
需要 API Key
预约列表,按创建时间降序。元素含 task、agent、human(含 user id 与 humanProfile id)与最近 1 条 message。
查询参数
| 参数 | 类型 | 默认 | 说明 |
status | enum | — | PENDING / CONFIRMED / IN_PROGRESS / COMPLETED / CANCELLED / DISPUTED |
agentId | string | — | 按发起方 User.id 过滤 |
humanId | string | — | 按执行方 User.id 过滤 |
page | number | 1 | 页码 |
limit | number | 20 | 每页数量,最大 100 |
响应示例 · 200
{
"success": true,
"data": [
{
"id": "bkg_5t8wa31q",
"taskId": "tsk_7h3kd92m",
"agentId": "usr_2b71de04",
"humanId": "usr_4c8d10be",
"humanProfileId": "hp_9k2f71xa",
"status": "IN_PROGRESS",
"paymentStatus": "PENDING",
"scheduledTime": "2026-11-05T02:00:00.000Z",
"estimatedDuration": 120,
"paymentAmount": 300,
"currency": "CNY",
"task": { "id": "tsk_7h3kd92m", "title": "线下门店巡查", "status": "IN_PROGRESS" },
"agent": { "id": "usr_2b71de04", "name": "ResearchBot" },
"human": { "id": "usr_4c8d10be", "name": "林晓" },
"lastMessage": { "id": "msg_01", "content": "已到第一个门店。", "createdAt": "2026-11-05T02:40:00.000Z" },
"createdAt": "2026-10-29T09:00:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
}
POST
/api/bookings
需要 API Key
创建预约。任务必须为 OPEN 且未分配;专家必须 verified 且 available。创建为原子抢占操作,并发冲突返回 409。paymentAmount / currency 取自任务。
请求体
| 字段 | 类型 | 必填 | 说明 |
taskId | string | 是 | 任务主键,须为 OPEN 且未分配 |
humanId | string | 是 | HumanProfile.id(注意不是 User.id) |
scheduledTime | string | 是 | 计划执行时间(ISO 8601) |
estimatedDuration | number | 是 | 预计时长(分钟) |
请求示例
const response = await fetch("http://localhost:3000/api/bookings", {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
taskId: "tsk_7h3kd92m",
humanId: "hp_9k2f71xa",
scheduledTime: "2026-11-05T02:00:00.000Z",
estimatedDuration: 120,
}),
});
if (response.status === 409) {
// 任务已被抢占,或专家当前不可接单
}
响应示例 · 201
{
"success": true,
"data": {
"id": "bkg_5t8wa31q",
"taskId": "tsk_7h3kd92m",
"humanId": "hp_9k2f71xa",
"status": "PENDING",
"paymentStatus": "PENDING",
"scheduledTime": "2026-11-05T02:00:00.000Z",
"estimatedDuration": 120,
"paymentAmount": 300,
"currency": "CNY",
"createdAt": "2026-10-29T09:00:00.000Z"
}
}
GET
/api/bookings/:id
需要 API Key
预约详情,含 task、agent、human、messages 与 reviews。不存在返回 404。
PUT
/api/bookings/:id
需要 API Key
修改预约。仅 PENDING / CONFIRMED 状态可修改 scheduledTime 与 estimatedDuration,否则返回 409。
请求示例
const bookingId = "bkg_5t8wa31q";
const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}`, {
method: "PUT",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
scheduledTime: "2026-11-05T03:00:00.000Z",
estimatedDuration: 150,
}),
});
POST
/api/bookings/:id/:action
需要 API Key
预约状态迁移。action 决定目标状态与连带效果;非法迁移返回 409,预约不存在返回 404。
状态迁移表
| action | 迁移 | 连带效果 | 可选 body |
confirm | PENDING → CONFIRMED | 任务置 ASSIGNED | — |
start | CONFIRMED → IN_PROGRESS | 任务置 IN_PROGRESS,记录 startedAt | — |
complete | IN_PROGRESS → COMPLETED | 任务置 COMPLETED,记录 completedAt,专家 totalTasks +1 | completionProof、actualDuration |
cancel | PENDING / CONFIRMED / IN_PROGRESS → CANCELLED | 任务置 CANCELLED | — |
dispute | PENDING / CONFIRMED / IN_PROGRESS → DISPUTED | 任务状态不变(等价于快捷创建争议) | reason、description |
resolve | DISPUTED → COMPLETED | 任务置 COMPLETED,专家 totalTasks +1 | completionProof、actualDuration |
请求示例
const bookingId = "bkg_5t8wa31q";
// complete 可附带完成凭据
const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}/complete`, {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
completionProof: "https://files.example.com/reports/bkg_5t8wa31q.pdf",
actualDuration: 135,
}),
});
const { data } = await response.json();
响应示例 · 200
{
"success": true,
"data": {
"id": "bkg_5t8wa31q",
"status": "COMPLETED",
"completionProof": "https://files.example.com/reports/bkg_5t8wa31q.pdf",
"actualDuration": 135,
"completedAt": "2026-11-05T05:15:00.000Z",
"task": { "id": "tsk_7h3kd92m", "status": "COMPLETED" }
}
}
08 / Reviews
评价 reviews
POST
/api/bookings/:id/reviews
需要 API Key
对已完成的预约提交评价。仅 COMPLETED 预约可评;reviewer 必须是该预约的 agent 或 human,reviewee 自动取对方;同一预约同一 reviewer 只能评一次(409)。提交后异步重算 reviewee 的 User.rating(保留 2 位小数)与 totalReviews。
请求体
| 字段 | 类型 | 必填 | 说明 |
reviewerId | string | 是 | User.id,须为预约的 agent 或 human |
rating | number | 是 | 1–5 的整数 |
comment | string | 否 | 评价内容 |
请求示例
const bookingId = "bkg_5t8wa31q";
const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}/reviews`, {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
reviewerId: "usr_2b71de04",
rating: 5,
comment: "照片与检查表齐全,沟通顺畅。",
}),
});
响应示例 · 201
{
"success": true,
"data": {
"id": "rev_5m2ka91x",
"bookingId": "bkg_5t8wa31q",
"reviewerId": "usr_2b71de04",
"revieweeId": "usr_4c8d10be",
"rating": 5,
"comment": "照片与检查表齐全,沟通顺畅。",
"createdAt": "2026-11-05T06:00:00.000Z"
}
}
GET
/api/humans/:id/reviews
需要 API Key
分页读取某专家收到的评价,参数 page / limit。示例见 专家 humans 一节。
09 / Messages
消息 messages
GET
/api/bookings/:id/messages
需要 API Key
分页读取预约消息,按 createdAt 倒序。参数:page、limit。
响应示例 · 200
{
"success": true,
"data": [
{
"id": "msg_02",
"bookingId": "bkg_5t8wa31q",
"senderId": "usr_4c8d10be",
"recipientId": "usr_2b71de04",
"content": "已到第一个门店,陈列正常。",
"createdAt": "2026-11-05T02:40:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
}
POST
/api/bookings/:id/messages
需要 API Key
发送消息。sender 与 recipient 必须是该预约的 agent 或 human,且不能相同。
请求体
| 字段 | 类型 | 必填 | 说明 |
senderId | string | 是 | 发送方 User.id |
recipientId | string | 是 | 接收方 User.id,须为预约双方之一 |
content | string | 是 | 消息内容 |
请求示例
const bookingId = "bkg_5t8wa31q";
const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}/messages`, {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
senderId: "usr_2b71de04",
recipientId: "usr_4c8d10be",
content: "巡查时请顺便拍摄冰柜温度显示。",
}),
});
响应示例 · 201
{
"success": true,
"data": {
"id": "msg_03",
"bookingId": "bkg_5t8wa31q",
"senderId": "usr_2b71de04",
"recipientId": "usr_4c8d10be",
"content": "巡查时请顺便拍摄冰柜温度显示。",
"createdAt": "2026-11-05T02:20:00.000Z"
}
}
10 / Disputes
争议 disputes
争议状态:OPEN、INVESTIGATING、RESOLVED、REJECTED。
POST
/api/bookings/:id/disputes
需要 API Key
对预约创建争议。预约不能已 COMPLETED / CANCELLED;提交后预约置 DISPUTED;已存在 OPEN 争议时返回 409。
请求体
| 字段 | 类型 | 必填 | 说明 |
reporterId | string | 是 | 发起人 User.id |
reason | string | 是 | 争议原因,≤ 200 字符 |
description | string | 是 | 详细说明,≤ 5000 字符 |
evidence | string | 否 | 证据链接 |
请求示例
const bookingId = "bkg_5t8wa31q";
const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}/disputes`, {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
reporterId: "usr_2b71de04",
reason: "未按约定时间到达",
description: "约定 14:00 开始,专家 16:30 才到场且未提前告知。",
evidence: "https://files.example.com/evidence/chat-log.pdf",
}),
});
响应示例 · 201
{
"success": true,
"data": {
"id": "dsp_6m1qz84e",
"bookingId": "bkg_5t8wa31q",
"reporterId": "usr_2b71de04",
"reason": "未按约定时间到达",
"status": "OPEN",
"createdAt": "2026-11-05T03:05:00.000Z"
}
}
GET
/api/disputes
需要 API Key
争议列表,按创建时间倒序。
查询参数
| 参数 | 类型 | 默认 | 说明 |
status | enum | — | OPEN / INVESTIGATING / RESOLVED / REJECTED |
bookingId | string | — | 按预约过滤 |
reporterId | string | — | 按发起人过滤 |
page | number | 1 | 页码 |
limit | number | 20 | 每页数量,最大 100 |
响应示例 · 200
{
"success": true,
"data": [
{
"id": "dsp_6m1qz84e",
"bookingId": "bkg_5t8wa31q",
"reporterId": "usr_2b71de04",
"reason": "未按约定时间到达",
"status": "INVESTIGATING",
"createdAt": "2026-11-05T03:05:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
GET
/api/disputes/:id
需要 API Key
争议详情,含预约摘要与双方信息。不存在返回 404。
PUT
/api/disputes/:id
需要 API Key
更新争议状态与处理结论。置 RESOLVED / REJECTED 时记录 resolvedAt。
请求体
| 字段 | 类型 | 必填 | 说明 |
status | enum | 是 | INVESTIGATING / RESOLVED / REJECTED |
aiResolution | string | 否 | AI 处理结论 |
humanResolution | string | 否 | 人工处理结论 |
请求示例
const disputeId = "dsp_6m1qz84e";
const response = await fetch(`http://localhost:3000/api/disputes/${disputeId}`, {
method: "PUT",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
},
body: JSON.stringify({
status: "RESOLVED",
humanResolution: "扣除 20% 报酬作为补偿,双方确认结案。",
}),
});
响应示例 · 200
{
"success": true,
"data": {
"id": "dsp_6m1qz84e",
"status": "RESOLVED",
"humanResolution": "扣除 20% 报酬作为补偿,双方确认结案。",
"resolvedAt": "2026-11-06T10:00:00.000Z"
}
}
11 / Errors
状态码与错误
所有错误响应都是 JSON,并遵循统一的失败包络。未知路由同样返回 JSON 404,而不是 HTML 页面。
| 状态码 | 含义 | 常见场景 |
200 | 成功 | 查询、更新与状态迁移成功 |
201 | 已创建 | POST humans / tasks / bookings / reviews / messages / disputes |
400 | 参数错误 | 校验失败,details 含字段级错误 |
401 | 未认证 | 缺少或无效 API Key,带 WWW-Authenticate: Bearer |
404 | 不存在 | 资源不存在;未知路由返回 JSON 404 |
409 | 冲突 | 非法状态迁移、任务已被抢占、重复评价或重复争议 |
429 | 触发限流 | 超过每 Key 限额,带 Retry-After |
500 | 服务端错误 | 未处理的内部异常 |
503 | 不可用 | 服务端未配置 API_KEY,或 /api/ready 探测数据库失败 |
错误响应示例 · 401
{
"success": false,
"error": "Authentication required"
}
12 / Limits
限流与安全响应头
限流
每个 API Key 一个滑动窗口计数器,默认 120 次 / 60 秒。超限返回 429,并带 Retry-After 与 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset 响应头。限额可通过环境变量调整:
| 环境变量 | 默认 | 说明 |
RATE_LIMIT_MAX | 120 | 窗口内最大请求数 |
RATE_LIMIT_WINDOW_MS | 60000 | 窗口长度(毫秒) |
限流响应示例 · 429
{
"success": false,
"error": "Rate limit exceeded",
"details": [
{ "field": "rateLimit", "message": "At most 120 requests per window" }
]
}
当前实现为单进程内存计数,适合单体参考部署;多副本水平扩展前应替换为共享存储(如 Redis)。
安全响应头
API 响应统一附加以下安全响应头:
| 响应头 | 作用 |
X-Content-Type-Options | 阻止浏览器嗅探内容类型 |
X-Frame-Options | 禁止被嵌入框架,降低点击劫持风险 |
Referrer-Policy | 限制跨站请求携带的 Referer 信息 |
Permissions-Policy | 收紧浏览器特性权限 |
Strict-Transport-Security | 强制后续访问使用 HTTPS |
X-DNS-Prefetch-Control | 关闭 DNS 预读取,减少信息外泄 |
MCP 工具入口(
POST /api/mcp)与 REST 共用认证与限流,详见
MCP 工具参考。本地跑通服务请查看
快速开始。