项目接口

以下接口的完整地址都以 https://api.yqpj.com/app-api/project/open-api 开头，请求头带 X-Api-Key: <你的密钥>。每次调用都会记入密钥的调用日志。

定位项目

修改项目、登记费用等接口需要先指明是哪个项目，可以用下面任意一种方式，只能定位到你是创建者或已接受开发者的项目：

GET /me　当前密钥信息

返回密钥对应的用户与权限，常用来检查密钥是否有效。

所需权限：无（有效密钥即可）。对应命令：yqpj-agent whoami

返回示例

{
  "code": 0,
  "data": {
    "userId": 128,
    "tenantId": 1,
    "name": "张三",
    "keyName": "MacBook 上的 Claude",
    "scopes": ["PROJECT_READ", "AGENT_MANAGE"]
  },
  "msg": ""
}

GET /projects　我的项目

列出你能处理反馈的进行中项目（你是创建者或已接受的开发者），以及每个项目的值守接入情况。

所需权限：查看我的项目（PROJECT_READ）。对应命令：yqpj-agent projects [关键字]

请求参数（查询串）

返回示例

{
  "code": 0,
  "data": [
    {
      "id": 34,
      "no": "PRJ20261019001",
      "name": "钱包服务",
      "status": "DEVELOPING",
      "agentName": "钱包服务·反馈值守",
      "agentRepoPath": "/Users/me/Project/wallet",
      "agentBranch": "master",
      "agentOnline": true
    }
  ],
  "msg": ""
}

还没接入值守的项目，agentName、agentRepoPath、agentBranch 为 null，agentOnline 为 false。

POST /projects/create　新建项目

以密钥用户为创建者新建项目，可以同时加合作方、登记费用、推进到指定阶段。整个过程是一个事务，任一步失败全部回滚。

所需权限：新建项目（PROJECT_WRITE）。对应命令：yqpj-agent project-create <请求 JSON 文件>

请求参数

请求示例

{
  "name": "小额贷",
  "requirement": "小额贷款 App + 后台",
  "devCycleMin": 30,
  "devCycleMax": 45,
  "cycleUnit": "DAY",
  "middleman": "xuan",
  "devFee": 5500,
  "devFeeCurrency": "USDT",
  "fees": [
    { "categoryCode": "maintain", "amount": 200, "chargeType": "PERIODIC", "period": "MONTH" }
  ],
  "status": "MAINTAINING",
  "dealDate": "2026-09-01",
  "testDate": "2026-10-10",
  "onlineDate": "2026-10-20",
  "maintainDate": "2026-10-21",
  "nextChargeDate": "2026-10-31",
  "priorPeriodMode": "FREE"
}

返回示例

{
  "code": 0,
  "data": {
    "id": 52,
    "no": "PRJ20261022001",
    "name": "小额贷",
    "status": "MAINTAINING",
    "middleman": "通讯录联系人「xuan」（线下，已加入）",
    "devFee": 5500,
    "feeCount": 2
  },
  "msg": ""
}

规则说明

• 防重复：你名下已有同名（不分大小写）且未结束的项目时拒绝新建，避免重复调用建出两份。
• 合作方：先在你的通讯录里按名字或真实姓名精确找，找到一个即加入（线下联系人直接加入，已入驻平台的发邀请待确认）；通讯录里有多个同名时报错。通讯录没有再按用户名或昵称精确找平台用户并发邀请，找不到或有多个时报错，请先把合作方加进通讯录。
• 阶段推进：项目先以报价中建好，登记完费用后按报价中 → 开发中 → 测试中 → 已上线 → 维护中逐级推进到目标阶段，每一级与 H5 上操作一致。进入维护中时，首期维护账单按已登记的周期费生成。

POST /projects/update　修改项目信息

只修改给了值的字段，其余字段、对接联系人、附件、参考站点保持不变。

所需权限：新建项目（PROJECT_WRITE）。对应命令：yqpj-agent project-update <项目名 | 业务编号 | 编号> <JSON 文件>

请求参数

除下表字段外，还需带上「定位项目」的字段。

请求示例

{
  "project": "小额贷",
  "name": "小额贷二期",
  "status": "MAINTAINING",
  "maintainDate": "2026-10-21",
  "nextChargeDate": "2026-10-31",
  "priorPeriodMode": "OFFLINE_PAID"
}

返回示例

{
  "code": 0,
  "data": {
    "id": 52,
    "no": "PRJ20261022001",
    "name": "小额贷二期",
    "oldName": "小额贷",
    "status": "MAINTAINING",
    "dealTime": 1788192000000,
    "testTime": 1791561600000,
    "onlineTime": 1792425600000,
    "maintainTime": 1792512000000
  },
  "msg": ""
}

规则说明

• 谁能改：名称、需求、备注、开发周期只有项目创建者能改（与 H5 编辑一致）；成交、测试、上线日期创建者或已接受的开发者都能改。
• 改名：群名与处理端名称（「项目名·反馈值守」）随之更新。
• 先修日期，再推进阶段：同时给了节点日期和 status 时，先修正已过的节点，再按新阶段补后面的节点。
• 阶段只能往后：从当前阶段逐级推进到目标阶段；目标早于当前阶段或项目已结束时报错。推进时补的节点日期取当天，进入维护中时使用 maintainDate、nextChargeDate、priorPeriodMode。
• 已在维护中：不传 status（或传 MAINTAINING）而传了 maintainDate、nextChargeDate、priorPeriodMode 任一项时，修改维护开始日期与下次收费日；没给 maintainDate 就沿用原维护开始日期。与 H5 一致，已有手动收款的维护账单时不允许修改。

POST /projects/fees/save　登记项目费用

按内置分类登记一次性或周期性费用。同分类的已有费用项被覆盖，其它费用项保留。

所需权限：新建项目（PROJECT_WRITE），且你是项目创建者或已接受的开发者。对应命令：yqpj-agent fee-save <项目名 | 业务编号 | 编号> <fees.json>

请求参数

除 fees 外，还需带上「定位项目」的字段。

请求示例

{
  "project": "小额贷",
  "fees": [
    {
      "categoryCode": "maintain",
      "amount": 200,
      "currency": "USDT",
      "chargeType": "PERIODIC",
      "period": "MONTH",
      "billDay": 28,
      "nextChargeDate": "2026-10-31",
      "priorPeriodMode": "OFFLINE_PAID",
      "remark": "含服务器巡检"
    }
  ]
}

返回示例

{
  "code": 0,
  "data": { "projectId": 52, "saved": 1, "total": 2 },
  "msg": ""
}

saved 是本次提交的费用项数，total 是登记后项目的费用项总数。