项目的集成选项卡用于将一个项目连接到其他系统:
- 外发 Webhook将项目事件(创建任务、冲刺开始、创建文档……)推送到您拥有的 HTTPS 端点,并附带签名,以便接收方验证其可信性。
- 传入 Webhook 令牌允许外部系统(表单工具、GitHub、脚本)在项目中创建任务或评论。
- 公共 API令牌通过 SolaProjects API 授予其他系统对项目任务和工时的有范围限制的读取或写入权限。
- 原生服务提供商就绪状态会显示预置连接(Slack、Microsoft Teams、GitHub、GitLab、Google Calendar、Google Drive、OneDrive、Zapier / IFTTT)及各连接是否可用。
当项目需要与其他工具交互,例如向客户仪表板发布任务更新,或将网站咨询转换为任务时,请使用它。项目经理和管理员负责设置;通常每个项目与 IT 联系人一起设置一次。
有两个页面名为集成。本页介绍项目选项卡。侧边栏工作区部分的集成项目(
/projects/settings/integrations)是组织的SolaCount 连接 — 请参阅下文组织 SolaCount 连接及预算与财务。
#哪里可以找到
| 侧边栏 | 项目区域 → 集成(位于自动化与人工智能之间) |
| URL | /projects/{project}/integrations |
| 命令面板 | 集成 · {project name},位于当前项目之下 |
由谁查看:
- 套餐:集成功能属于高级套餐(企业套餐也包含)。较低套餐会隐藏此选项卡。付费套餐到期后,该选项卡会消失,也不再提供 Webhook,直到续费。
- 角色:只有能够编辑项目的人员才能加载该选项卡(参见权限)。其他人会看到"我们无法加载集成。"以及重试。
#屏幕导览
#标题卡片
集成 — 外发 Webhook、传入令牌以及投递历史。
| 卡片 | 含义 |
|---|---|
| 传出 | 有效的出站 Webhook。 |
| 传入令牌 | 有效且未撤销的传入令牌。 |
| 最近交付记录 | 投递尝试列在最近投递中。 |
| 投递失败 | 其中失败的尝试次数(大于零时显示为红色)。 |
#外发 Webhook 卡片
将项目事件以 HMAC-SHA256 签名后 POST 到外部 HTTPS 端点。 在右上角点击 新建 Webhook。
每张 Webhook 卡片显示名称、端点 URL、状态徽标(启用、禁用或已归档)、每个已订阅事件的标签,以及{n} 次投递 · {n} 次失败。行操作(已归档的 Webhook 除外):编辑、测试、轮换密钥、归档。
空状态:没有外发 Webhook — 创建一个以将事件推送到外部系统。
#传入 Webhook 令牌卡片
允许外部系统通过携带密钥令牌的 POST 请求创建任务/评论。请在右上角点击新建令牌。
每张令牌卡片:名称、提供方(自定义或GitHub)· 上次使用 {date}或从未使用,徽标为启用、停用或已撤销。操作(已撤销令牌除外):轮换、撤销。
空状态:没有传入令牌 — 创建一个令牌以接收入站 Webhook。
#公共 API 卡片
为已记录的项目、任务和工时记录端点创建有范围限制的持有者令牌。 按钮:文档(在新标签页中打开 OpenAPI 参考)和 新建令牌。
每张令牌卡片:名称、最后使用 {date} / 从未使用、状态徽章,以及每项权限一个标签。操作:轮换、撤销。
空状态:没有 API 令牌 — 为公共 API 创建一个令牌。
#最近交付卡片
外发投递尝试及其结果。 带有计数的徽标。
| 列 | 含义 |
|---|---|
| 触发时机 | 交付日期。 |
| Webhook | Webhook 名称,或 已归档的 Webhook。 |
| 活动 | 事件类型,例如 task.status_changed。 |
| 状态 | 已送达(绿色)、待处理(琥珀色,等待或重试中)、失败(红色)、已跳过。 |
| 尝试 | SolaProjects 已尝试的次数。 |
| 响应 | 您的端点返回的 HTTP 状态码;若未收到响应则为错误,或为—。 |
| (按钮) | 对任何未投递成功的投递重试。 |
空状态:尚无投递记录 — 事件触发或您发送测试后,投递尝试会显示在此处。
#原生提供商就绪卡片
针对特定服务商集成的连接状态和设置前提条件。 每个服务商一个磁贴:
| 服务商 | 功能 |
|---|---|
| Slack | 向 Slack 发送项目通知,并从 Slack 接收任务指令。 |
| Microsoft Teams | 向 Teams 频道发送项目通知并支持 Teams 操作。 |
| GitHub | 将代码库事件、问题、拉取请求和提交链接到项目任务。 |
| GitLab | 将 GitLab 合并请求、问题和流水线事件链接到项目任务。 |
| Google Calendar | 将项目里程碑和任务日期同步到 Google Calendar。 |
| Google Drive | 将项目文档附加或同步到 Google Drive 文件夹。 |
| OneDrive | 将项目文档附加或同步到 OneDrive 文件夹。 |
| Zapier / IFTTT | 向无代码平台开放 SolaProjects 的触发器和操作。 |
每个卡片显示状态(可用、待处理、已启用、失败)、功能,以及已检测到正式服务商配置。或本地模拟器可用;生产凭据属于激活设置。(该服务商尚未在您的组织正式启用)。还可能显示因缺少设置而受阻:…、激活说明:…、OAuth 回调待处理。、最后错误:…、最后一条消息或最后收到的事件。
#您可以发送的事件
在 webhook 表单中勾选一个或多个:
| 活动 | 发送时间 |
|---|---|
task.created |
创建任务(包括通过传入的 Webhook 创建)。 |
task.updated |
任务被编辑。 |
task.status_changed |
任务状态发生变化。 |
task.completed |
任务被标记为完成。 |
task.blocked |
任务被标记为阻塞。 |
comment.created |
添加了任务评论。 |
doc.created |
已创建项目文档。 |
time_entry.created |
已记录工时。 |
milestone.completed |
里程碑已完成。 |
sprint.started / sprint.completed |
冲刺开始/完成时。 |
share_link.created |
已创建访客共享链接。 |
automation.run_failed / automation.rule_failed |
自动化运行失败。 |
ai.suggestion_applied |
已应用 AI 建议。 |
每个请求都是 JSON POST,带有请求头X-SolaProjects-Event(事件类型)、X-SolaProjects-Delivery(投递 ID)、X-SolaProjects-Signature(使用签名密钥对原始请求体计算的 HMAC-SHA256)以及User-Agent: SolaProjects-Webhooks/1.0。信任请求前请先验证签名。
重试。失败的投递会在约 1、5、15 和 60 分钟后自动重试;第五次尝试后,它将保持失败状态。使用重试可手动再次尝试。
#任务
#创建传出 webhook
-
打开项目 → 集成 → 新建 Webhook。
-
填写新建外发 Webhook:
字段 必填 规则 / 默认设置 注释 名称 是的 最多 160 个字符。 例如 客户仪表板。 端点 URL (HTTPS) 是的 有效的 URL,最多 2,048 个字符,必须为公开的 HTTPS。 占位符 https://example.com/hooks/solaprojects。本地和专用网络地址会被拒绝:"请使用公共 HTTPS 端点。本地和专用网络 URL 已被阻止。"事件 是的 至少一项。 参见上方表格。 活跃 — 默认勾选。 取消勾选可将其保存为 已禁用。 -
点击创建。您会看到传出 Webhook 已创建。及签名密钥对话框:“请立即保存 — 仅显示一次,之后无法再次获取。” 点击复制(已复制到剪贴板。),将密钥保存到接收系统,然后点击完成。
#编辑、测试、轮换和归档 Webhook
| 行动 | 步骤 | 结果 |
|---|---|---|
| 编辑 | 更改名称、URL、事件,或将启用 → 保存。 | 传出 Webhook 已更新。 |
| 测试 | 点击测试。 | 测试投递已排队。 一行记录会出现在 最近投递 中。 |
| 轮换密钥 | 确认 轮换密钥 ——“当前密钥将停止工作。请使用新密钥更新已连接的服务。” | 密钥已轮换。 新密钥只显示一次。 |
| 存档 | 确认 归档 Webhook ——“此传出 Webhook 将停止推送项目事件。” | Webhook 已归档。徽章显示已归档;不再投递;历史记录保留。 |
#创建传入 webhook 令牌
- 在 传入 Webhook 令牌 上点击 新建令牌。
- 名称(必填,最多 160 个字符)以及 提供方:自定义(默认)或 GitHub。
- 点击创建 → 入站令牌已创建。请复制仅显示一次的入站 Webhook 令牌:“将此作为入站 Webhook URL 中的令牌使用。仅显示一次。”
外部系统随后会发送 POST /api/projects/webhooks/incoming/{token},请求体为 JSON(每个发送方每分钟限 60 次请求):
| 服务商 | 正文 | 发生的事情 |
|---|---|---|
| 自定义 | {"title": "...", "description": "...", "priority": "high"} |
在 待办 中创建一个私人任务(优先级默认为 medium;标题最多 180 个字符)。响应中包含新的 task_key。 |
| 自定义 | {"task_key": "ALN-14", "comment": "..."} |
为该任务添加一条内部评论。 |
| GitHub | 签发或签发评论事件 | 问题会转为任务;若问题标题中包含任务编号(例如 ALN-14),其评论会成为该任务的评论。 |
其他任何请求都会被拒绝,并显示“Webhook rejected.”;已撤销或错误的令牌会得到相同的响应。任务和评论由创建该令牌的人员署名。
轮换会签发新令牌并立即撤销旧令牌(令牌已轮换。)。撤销会询问撤销令牌 — “使用此令牌的请求将不再具有访问权限。” → 令牌已撤销。
#创建公共 API 令牌
-
在 公共 API 上点击 新建令牌。
-
名称(必填,最多 120 个字符)以及 权限(至少一项;
projects:read、tasks:read和time:read已默认勾选):能力 允许 projects:read阅读此项目。 tasks:read/tasks:write读取 / 创建和更新任务。 time:read/time:write读取 / 创建工时记录。 -
创建 → API 令牌已创建。 复制 项目 API 令牌:“将此作为 /api/v1 的 Bearer 令牌使用。仅显示一次。”
通过 API 创建的任务会触发与应用内创建任务相同的自动化和 webhook。轮换 → 确认轮换令牌(“当前令牌将停止工作。请使用新令牌更新已连接的服务。”)→ API 令牌已轮换。撤销 → API 令牌已撤销。
#重试失败的发送
在最近交付中,点击该行的重试 → 已重试交付。稍后查看状态和响应。
#连接原生服务提供商
- 在提供商卡片上选择渠道(例如 Slack 的#projects),然后点击连接 → {Provider} 连接已开始。
- 在授权对话框中完成 {Provider} 授权,点击 完成回调(或 稍后)→ 原生集成已连接。
- 连接后,可使用发送测试({Provider} 测试消息已发送。)、刷新({Provider} 已刷新。)或断开连接({Provider} 已断开连接。)。
模拟器模式下的卡片还会显示 模拟事件 和 错误,用于在提供商正式上线前检查设置;它们不会连接真实服务。
#状态
| 对象 | 状态 |
|---|---|
| 外发 Webhook | 启用、已禁用(取消勾选“启用”后保存)、已归档 |
| 发货 | 待处理、已送达、失败、已跳过 |
| 传入 / API 令牌 | 启用、停用、已撤销 |
| 原生提供商 | 可用、待处理、活动、失败 |
#权限
| 角色 | 打开该选项卡 | 创建 / 更改 webhooks、令牌、提供商 |
|---|---|---|
| 组织所有者 | 是的 | 是的 |
| 项目管理员 | 是的 | 是的 |
| 在此担任项目经理的项目经理 | 是的 | 是的 |
| 项目成员、项目查看者、访客 | 否 | 否 |
如果组织停用了集成编辑,标签页为只读(没有新建、行操作或重试)。更改被拒绝时会显示“集成编辑已停用或您没有权限。”;页面过时时会显示“请刷新后重试。”一次性对话框关闭后,密钥和令牌不会再次显示,即使所有者也无法查看。
#组织 SolaCount 连接
工作区侧栏的集成(/projects/settings/integrations)是另一个页面。它显示 SolaProjects 是否连接到 SolaCount(已连接、可连接、集成已暂停、已断开连接——保留历史记录等),并允许组织所有者或财务管理员连接、暂停、断开或检查连接。单个项目可在其设置选项卡中选择不使用财务集成(集成卡片 → 内部项目/财务已禁用)。参见预算与财务及 SolaProjects 概览。
#操作示例
#示例 1 — 询价转为任务(日常)
{User 1 name} 希望 {Showroom project name}(DEMO-FIT)的网站咨询能够转为任务。
- 新建令牌 → 名称 网站咨询,提供方 自定义 → 创建;她将令牌交给网站开发人员。
- 网站过账
{"title": "Quote request – reception desk", "priority": "high"}。 - 任务ALN-31 报价请求 – 前台出现在待办中,为私有,优先级为高。令牌卡显示上次使用 10 月 6 日。
#示例 2 — 客户仪表板数据推送出现故障(完整场景)
{User 2 name} 连接 {Organization name} 的站点仪表板。
| 步骤 | 行动 | 结果 |
|---|---|---|
| 1 | 新建 Webhook:站点仪表板,https://hooks.company.example.com/projects,事件 task.status_changed,task.completed,milestone.completed。 |
外发 Webhook 已创建。签名密钥已复制到仪表板。 |
| 2 | 测试。 | 测试投递已排队。;该行 已投递,响应 200。 |
| 3 | {User 1 name} 将 ALN-12 移至已完成。 | 两次交付:task.status_changed和task.completed,均为已交付。 |
| 4 | 仪表板因维护而暂时不可用。 | 下一次交付显示待处理,然后显示失败,响应为 503;页眉中以红色显示失败交付 1;大约在 1、5、15、60 分钟后重试。 |
| 5 | 仪表板返回;{User 2 name} 点击 重试。 | 已重试投递。 → 已送达。 |
| 6 | IT 怀疑密钥已泄露。{User 2 name} 点击轮换密钥并确认。 | 密钥已轮换。;新密钥只显示一次;IT 部门更新仪表板。 |
#连接方式
| 位置 | 链接 |
|---|---|
| 任务 | 传入令牌和 API 可创建任务和评论;任务变更会发送事件。 |
| 规划 | 里程碑完成以及冲刺开始/完成会发送事件。 |
| 自动化 | 在 SolaProjects 内操作;失败的运行可以作为事件发出。 |
| 访客共享链接 | share_link.created 事件。 |
| 人工智能 | ai.suggestion_applied 事件。 |
| 工时跟踪 | time_entry.created 事件;时间 API 权限。 |
| 设置 | 按项目的 SolaCount 财务开关。 |
#提示与常见问题
| 问题 | 原因 | 解决方法 |
|---|---|---|
| 缺少标签页。 | 套餐低于 Premium 或已过期。 | 升级或续订。 |
| 使用公共 HTTPS 端点… | URL 为 http、localhost 或私有地址。 |
请使用公开的 HTTPS 网址。 |
| 丢失了密钥或令牌。 | 仅显示一次。 | 轮换,并更新其他系统。 |
| 投递以 4xx 代码失败。 | 您的端点拒绝了该请求(通常是签名校验失败)。 | 请检查端点是否使用当前密钥。 |
| Webhook 已拒绝。传入调用时。 | 令牌已撤销或错误,或请求正文中没有 title 或 task_key + comment。 |
检查令牌和请求体。 |
| 评论未从 GitHub 添加。 | 问题标题中没有任务键。 | 在问题标题中填写密钥(例如 ALN-14)。 |
| API 返回访问被拒绝。 | 令牌缺少相应权限或已被撤销。 | 创建具有适当权限的令牌。 |
| 提供方显示 本地模拟器可用… | 您的组织尚未正式启用。 | 请联系 Solavel 支持人员咨询激活事宜。 |
#相关
- 自动化 · 任务 · 规划
- 设置 · 预算与财务 · 访客共享链接
- 工时审批与计费 · SolaProjects 概览
- 中的项目SolaCount