HubSpot

核心用法

HubSpot Skill 是 Maton 平台提供的 HubSpot CRM 官方 API 代理服务，通过 gateway.maton.ai 网关实现对 HubSpot 原生 API 的透明转发。核心工作流程：

1. 认证获取：在 maton.ai 注册获取 MATON_API_KEY，所有请求通过 Authorization: Bearer 头部传递
2. 连接管理：在 ctrl.maton.ai 创建 HubSpot OAuth 连接，完成浏览器授权流程获得访问令牌
3. API 调用：通过 https://gateway.maton.ai/hubspot/{native-api-path} 格式调用任意 HubSpot API，网关自动注入 OAuth Token

支持完整 CRM 对象生命周期管理：

• 联系人（Contacts）：创建、查询、更新、删除、搜索（支持 email、name 等多条件过滤）
• 公司（Companies）：域名关联、行业枚举值管理、员工规模追踪
• 交易（Deals）： Pipeline 阶段管理、金额追踪
• 关联（Associations v4）：Contact-Company、Deal-Contact、Deal-Company 多对多关系
• 批量操作：单次最多 100 条记录的批量读/写/更新/归档

显著优点

• 零 OAuth 维护成本：托管式 Token 刷新，开发者无需处理 HubSpot 的 6 小时 Token 过期机制
• 原生 API 100% 兼容：直接透传 HubSpot v3/v4 API，支持所有官方端点包括 Properties、Search、Associations
• 多租户隔离：通过 Maton-Connection 头部支持同一 API Key 下的多 HubSpot 账户切换
• 企业级批量能力：内置 100 条/请求的批处理上限，适配大数据同步场景

潜在局限与风险

| 类别 | 说明 |

|------|------|

| **速率限制** | 10 req/sec/账户，高频场景需本地队列缓冲 |

| **软删除陷阱** | Archive/Delete 为 90 天软删除，误操作恢复依赖 HubSpot 后台，无 API 即时回滚 |

| **行业枚举耦合** | Company `industry` 字段需使用 HubSpot 预定义枚举值，自由文本会被拒绝 |

| **Shell 环境敏感** | `curl` 管道到 `jq` 时 `$MATON_API_KEY` 可能不展开，需用 Python/Node 替代 |

| **依赖单点** | Maton 网关故障将完全阻断访问，无直接 fallback 到 HubSpot 官方端点的路径 |

适合人群

• SaaS 集成开发者：需快速嵌入 CRM 数据同步，不愿投入 OAuth 工程成本
• 数据迁移工程师：从旧系统向 HubSpot 批量导入联系人/公司/交易记录
• RevOps 自动化团队：构建 Lead-to-Cash 流程自动化，依赖 Deal Pipeline 状态监听
• 多品牌集团 IT：单一技术栈管理多个 HubSpot 门户的跨账户数据聚合

常规风险

• 数据合规：联系人邮箱、电话流经 Maton 网关，需确认 DPA（数据处理协议）覆盖
• Token 泄露面：虽然 OAuth Token 不暴露给调用方，但 MATON_API_KEY 泄露将导致所有连接账户暴露
• API 变更延迟：HubSpot 官方 API 弃用字段时，网关透传可能延迟同步文档更新

核心用法

HubSpot skill 通过 Maton 平台提供托管式 OAuth 认证，无需自行处理 HubSpot 的 OAuth 流程。用户仅需在 maton.ai 注册获取 API Key，即可通过统一网关访问完整的 HubSpot CRM API V3/V4。

典型工作流：
1. 创建连接：POST ctrl.maton.ai/connections 获取授权链接
2. 完成 OAuth：浏览器打开返回的 url 授权
3. 调用 API：通过 gateway.maton.ai/hubspot/{path} 操作 CRM 数据

支持的核心操作：

• Contacts：增删改查、搜索过滤（支持 EQ/CONTAINS_TOKEN 等 8 种运算符）
• Companies：完整 CRUD，注意 industry 字段需使用枚举值
• Deals：交易金额、阶段管理（如 appointmentscheduled → qualifiedtobuy）
• Associations：V4 API 支持对象关联（Contact↔Company、Deal↔Contact 等）
• Batch 操作：单次最多 100 条记录的批量读写

分页机制：列表接口返回 paging.next.after 游标，通过 ?after= 参数翻页。

显著优点

1. 零 OAuth 维护成本：Maton 托管令牌刷新，开发者只需关注业务逻辑
2. 统一认证层：单个 MATON_API_KEY 管理多连接，支持多 HubSpot 账户切换（Maton-Connection 头部）
3. 完整 API 覆盖：涵盖 V3 对象操作 + V4 关联 API，支持 Properties 元数据查询
4. 安全传输：全链路 HTTPS + Bearer Token，API Key 从环境变量读取
5. 批量效率：100 条/请求的 batch 操作，适合数据迁移和同步场景

潜在缺点与局限性

1. 平台锁定风险：完全依赖 Maton 网关，若服务中断则无法直连 HubSpot
2. 速率限制：10 req/sec/账户的硬性限制，高并发场景需自行队列化
3. 连接管理成本：多账户场景需手动维护 connection_id，无自动路由机制
4. 软删除陷阱：Delete 为 90 天内可恢复的逻辑删除，非物理删除
5. 行业枚举约束：Company 的 industry 字段值受限，需先查询 Properties API
6. curl 兼容性坑：URL 含方括号时需 curl -g，管道传输时环境变量可能不展开

适合人群

• 销售运营团队：快速搭建线索分配、客户状态同步自动化
• SaaS 集成开发者：需要将用户数据双向同步至 HubSpot 的第三方应用
• 数据分析师：批量导出 CRM 数据做离线分析（配合 batch/read）
• 无后端团队：通过纯文档即可让非工程师完成 HubSpot 集成

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| API Key 泄露 | `MATON_API_KEY` 泄露导致账户被滥用 | 使用 secrets 管理、定期轮换、最小权限原则 |

| OAuth 授权范围过宽 | HubSpot 连接授权了不必要的权限范围 | 在 Maton 控制台审查并限制 scope |

| 数据合规 | 处理欧盟联系人数据需考虑 GDPR | 实施数据最小化、记录处理日志 |

| 软删除误恢复 | 90 天内误删记录可被恢复，但超期永久丢失 | 关键操作前备份、实施审批流程 |

| 关联操作失败 | 错误的 `associationTypeId` 导致关联失败 | 参考文档中的标准 ID（279/3/341）|

安全等级 S：纯文档型技能，无本地代码执行，依赖外部可信 API（Maton），环境变量管理密钥，符合 GDPR 数据最小化原则。