REST API

概览

]project-open[ 通过 /intranet-rest/ 提供 REST 风格的接口，适合以下集成：

• 从 CRM 或合同系统同步客户与项目；
• 把工时数据推送到财务或 BI 系统；
• 为移动端或门户提供只读数据；
• 自动化报表与数据校验。

接口路径与字段可能随版本调整。开发前请先在测试环境确认实际返回结构，并以系统自带的接口文档为准。

认证

推荐使用令牌认证，在请求头中携带：

GET /intranet-rest/project/ HTTP/1.1
Host: pm.example.com
Authorization: Bearer <token>
Accept: application/json

令牌应只授予必要的权限，并绑定到专用集成账号。不要使用个人管理员账号生成长期令牌。

常用端点

资源	方法	路径
项目列表	GET	/intranet-rest/project/
项目详情	GET	/intranet-rest/project/{id}
创建项目	POST	/intranet-rest/project/
更新项目	PUT	/intranet-rest/project/{id}
任务列表	GET	/intranet-rest/task/
工时列表	GET	/intranet-rest/hour/
创建工时	POST	/intranet-rest/hour/
客户列表	GET	/intranet-rest/company/

查询示例

查询进行中的项目，按更新时间倒序，取前 20 条：

curl -s "https://pm.example.com/intranet-rest/project/?status=active&limit=20&orderby=last_modified" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

返回结构通常为数组，字段包含项目编号、名称、客户、状态与日期：

[
  {
    "project_id": 10231,
    "project_nr": "PRJ-2026-018",
    "project_name": "某客户门户本地化",
    "company_id": 881,
    "project_status_id": 76,
    "start_date": "2026-09-01",
    "end_date": "2026-12-31"
  }
]

创建工时记录：

curl -s -X POST "https://pm.example.com/intranet-rest/hour/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 2041,
    "project_id": 10231,
    "task_id": 55821,
    "day": "2026-10-08",
    "hours": 6.5,
    "note": "术语表整理与初译"
  }'

分页与筛选

常见查询参数：

• limit / offset：分页；
• orderby：排序字段；
• status：按状态过滤；
• company_id、project_id：按关联对象过滤。

大批量同步时建议使用增量字段（如 last_modified）而不是全量拉取，并控制单页大小在 100 条以内。

错误处理

接口使用 HTTP 状态码表达结果：

状态码	含义	处理建议
200	成功	—
400	参数错误	检查字段类型与必填项
401	未认证	检查令牌是否过期
403	无权限	检查集成账号角色
404	资源不存在	确认 ID 与路径
409	冲突	通常是唯一约束或状态不允许
500	服务端错误	记录请求 ID 并联系管理员

建议在集成层统一记录请求与响应摘要（脱敏后），便于排查。

集成建议

不要直接写业务表

即使数据库可访问，也应通过接口或业务过程写入数据，否则容易绕过权限、审计与派生字段计算。

使用幂等键

批量创建数据时，在外部系统维护唯一键（如合同编号），重试前先查询是否已存在，避免重复记录。

控制写入频率

工时与财务数据建议按批提交，避免高频单条写入。批量失败时要能定位到具体记录。

只读账号优先

报表与 BI 集成优先使用只读账号；写入权限只授予确实需要的集成。

下一步

• 参与贡献
• 架构概览