API 参考

Motivation Money 在 /api/v1/ 提供 REST API，用于程序化访问薪资发放、员工管理、资金库、Webhook 和审计日志。该 API 既可供人工工具使用，也可供 AI 智能体调用。

基础 URL

https://money.motivationlabs.ai/api/v1

认证

所有 API 请求需在 Authorization 头中携带 Bearer Token：

Authorization: Bearer mpk_live_<key>

API 密钥在 Motivation Money 仪表盘的 设置 > API 密钥 中创建。每个密钥具有：

• 名称 — 供参考的标签
• 作用域 — 控制密钥访问权限的权限集
• 过期时间 — 可选的过期日期
• 完整密钥仅在创建时显示一次。请妥善保管。

作用域

每个 API 密钥都附带一组控制访问的作用域。作用域遵循 resource:action 格式：

支持通配符作用域：payroll:* 授予所有薪资发放操作权限，* 授予完全访问权限。

速率限制

API 对每个 API 密钥执行滑动窗口速率限制，每 60 秒 100 次请求。

超过限制时，API 返回 429 Too Many Requests，并附带 Retry-After 头指示等待秒数。

幂等性

所有创建资源的 POST 请求需要包含 UUID v4 的 Idempotency-Key 头：

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

使用相同幂等键重试请求时，API 返回原始响应而不创建重复记录。

响应格式

成功响应结构如下：

{
  "data": { ... },
  "meta": { ... }
}

分页响应包含分页元数据：

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6
  }
}

错误响应返回：

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description",
    "details": null
  }
}

常见错误码

约定

• 金额以美分整数表示。850000 = $8,500.00。
• 时间戳为 UTC 的 ISO 8601 格式。2026-03-14T10:30:00Z。
• 长时间操作（如付款执行）返回 202 Accepted。

OpenAPI 规范

机器可读的 OpenAPI 3.1.0 规范可在以下地址获取：

GET /api/v1/openapi.json

可用于生成客户端 SDK、配置 AI 智能体工具定义，或导入 API 测试工具。

快速链接

• 薪资发放批次 — 创建、确认、执行和管理薪资发放批次
• 付款 — 查看和管理单笔付款
• 员工 — 添加、更新和列出团队成员
• 资金库 — 查询 Safe 和 CEX 余额
• Webhooks — 订阅实时事件
• 审计日志 — 查询完整操作历史