# @useairfoil/producer-hubspot 中文文档

规范地址：https://npmcn.com/package/%40useairfoil/producer-hubspot/

版本：0\.0\.3
npm 元数据更新时间：2026-11-02T18:47:29.705Z
中文译文更新时间：2026-11-02T19:41:20.861Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40useairfoil/producer-hubspot
原文对照：https://npmcn.com/package/%40useairfoil/producer-hubspot/?lang=original
项目主页：https://github.com/useairfoil/connector-kit#readme
源码仓库：https://github.com/useairfoil/connector-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：554 kB，54 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-10-29T07:38:50.870Z
- 最新版本发布：2026-11-02T18:47:29.351Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

同步HubSpot CRM记录，自定义对象，所有者，团队，管道，列表和属性定义从一个HubSpot帐户。它回填每个资源，然后每5分钟轮询CRM记录和自定义对象，其余的每小时轮询一次。使用应用程序客户端

## 安装

```sh
npm install @useairfoil/producer-hubspot
```

也可以使用：`pnpm add @useairfoil/producer-hubspot`、`yarn add @useairfoil/producer-hubspot`、`bun add @useairfoil/producer-hubspot`

## README

# HubSpot的生产商

同步HubSpot CRM记录，自定义对象，所有者，团队，管道，列表和 属性定义从一个HubSpot帐户。然后，它会回填每个资源 每5分钟轮询一次CRM记录和自定义对象，其余每小时轮询一次。 有了一个应用程序客户端秘密，它也需要webhooks `POST /webhooks/hubspot`.

| 资源 | 什么 |
| --- | --- |
| `contacts`， `companies`， `deals`， `tickets` | 核心CRM记录 |
| `calls`， `emails`， `meetings`， `notes`， `tasks`， `communications`， `postal_mail` | 活动 |
| `feedback_submissions` | 反馈调查的答案 |
| `line_items`， `products`， `quotes`， `discounts`， `fees`， `taxes` | 产品及报价 |
| `leads` | 领导 |
| `invoices`， `orders`， `carts`， `commerce_payments`， `subscriptions` | 商务 |
| `goal_targets`， `deal_split` | 目标和交易分歧 |
| `users` | HubSpot用户和他们的用户属性 |
| `custom_objects` | 每个自定义对象类型的记录 |
| `owners`， `teams` | 记录所有者和他们的团队 |
| `pipelines` | 管道及其阶段 |
| `lists` | 列表（段），没有成员 |
| `properties` | 属性定义，以命名 `properties` 键和值 |

## 配置

| 变量 | 要求 | 默认的 |
| --- | --- | --- |
| `HUBSPOT_ACCESS_TOKEN` | 是 | 无 |
| `HUBSPOT_CLIENT_SECRET` | 否 | 无 |

没有 `HUBSPOT_CLIENT_SECRET`， webhook关闭，每一个变化都来自 轮询。

## 设置

仅对于轮询，在下面创建服务密钥 **开发→密钥→服务 键** 使用这些读作用域：

-   `crm.objects.contacts.read`， `crm.schemas.contacts.read`
-   `crm.objects.companies.read`， `crm.schemas.companies.read`
-   `crm.objects.deals.read`， `crm.schemas.deals.read`
-   `crm.objects.tickets.read`， `crm.schemas.tickets.read`
-   `crm.objects.line_items.read`， `crm.schemas.line_items.read`
-   `crm.objects.products.read`
-   `crm.objects.owners.read`
-   `sales-email-read`
-   `crm.objects.quotes.read`， `crm.objects.leads.read`
-   `crm.objects.feedback_submissions.read`， `crm.objects.goals.read`， `crm.objects.users.read`
-   `crm.objects.invoices.read`， `crm.objects.orders.read`， `crm.objects.carts.read`， `crm.objects.commercepayments.read`， `crm.objects.subscriptions.read`
-   `crm.objects.custom.read`， `crm.schemas.custom.read`
-   `crm.lists.read`， `settings.users.teams.read`

通信、邮政邮件、折扣、费用、税收和交易分割都不需要 额外的范围。

使用该键作为 `HUBSPOT_ACCESS_TOKEN`.

服务密钥不能接收webhook。对于webhooks，上传应用程序 `hubspot-app/` 用HubSpot CLI代替：

1.  集 `targetUrl` 在 `hubspot-app/src/app/webhooks/webhooks-hsmeta.json` 来 `<connector>/webhooks/hubspot`.
2.  运行 `hs account auth`,然后 `hs project upload` 从 `hubspot-app/`.
3.  安装应用程序 **开发→项目→翼型连接器→ 分布**.
4.  使用Distribution选项卡中的访问令牌作为 `HUBSPOT_ACCESS_TOKEN` 和 从Auth选项卡获取客户端密钥 `HUBSPOT_CLIENT_SECRET`.

应用程序会请求上面的每个作用域，而静态授权的应用程序不能创建一个 可选的范围。对于一个没有功能的客户，比如定制对象、线索， 或Commerce Hub，将其范围从 `hubspot-app/src/app/app-hsmeta.json` 以及它的订阅 `webhooks-hsmeta.json` 在上传之前。

对于自定义对象webhook，添加 `object.creation`， `object.deletion`, `object.restore` 具有对象名称的订阅，例如 `vehicle`,因为 `objectType`。该应用程序无法为你列出每个帐户的自定义对象。

一个令牌读取一个帐户，因此为每个帐户运行一个连接器。

## API版本

连接器使用 `2026-09` API路径，例如 `/crm/objects/2026-09/contacts`.

## 数据

-   CRM表中保留每个非空属性 `properties`，通过内部名称； 作为字符串。新的自定义属性会自动显示。敏感属性 都被遗漏了。
-   联系，交易，门票，活动，报价，线索，商业记录，线路 项目、交易分割和自定义对象具有关联的记录id列表。
-   `custom_objects` 保存每个自定义对象类型。 `object_type_id` (如 `2-123`), `object_type` （它的名字）说哪个，和 `key` 是 `<object_type_id>:<id>`。已删除类型的行保留。
-   `properties` 命名键 `properties` 下拉菜单的值。 管道阶段 `pipelines`.
-   `users` 具有用户属性。 `owners` 将用户映射到记录上的所有者id。
-   被删除的记录 `_deleted`。合并到另一个数据库中的记录也是如此。
-   所有者、管道和属性定义保持不变 `archived = true` 当 移除。删除的团队和列表保持原样。
-   CRM记录表（包括自定义对象）保存客户数据，例如 姓名、电子邮件、电话号码、消息正文和表单答案。对待他们 作为客户数据。

## 限制

-   计算的属性和关联列表可以是一天前的，也可以是一周前的 活动、行项目和产品。webhook带来关联变化 马上。
-   如果没有webhook，这些删除就会被遗漏：GDPR删除、删除的电子邮件、 会议、通信、发票、付款、订阅、用户和交易 分裂。HubSpot无法列出它们。
-   没有特征的帐户，例如线索或自定义对象或令牌 如果没有它的作用域，将使该表出错。其他表保持同步。
-   交易分割没有webhook，所以它们只能来自轮询。自定义对象 协会名单也只能通过投票更新，最多晚一天。
-   一个新的自定义对象类型会在一小时内出现。
-   从回收站恢复的记录在下一次读取时返回：A 网络钩，搜索命中，或者全文重读。
-   搜索，删除记录的投票，以及完整的重读都是共享这个账户的 每日API限制与其他应用程序。

## 演示数据

`pnpm demo --size 128MiB` 在没有HubSpot的情况下写入编造的HubSpot数据 凭证。有关标志和变量，请参阅Connector Kit README 的需求。

每个公司都有联系人，处理行项目，报价，分割，门票， 销售活动，线索，一旦赢得交易，订阅，订单， 发票、付款和入职项目 `custom_objects`。属性 使用HubSpot的内部名称。帐户设置只写一次，不会写 随着规模的增长：所有者、用户、团队、管道、属性、列表、 产品、折扣、费用、税收和目标。

## 地方发展

```bash
cd connectors/producer-hubspot
pnpm sandbox
```

要录制录像机，请输入一个测试帐户的服务密钥 `.env`、删除 `test/__cassettes__/api.vcr.test.cassette`，然后跑 `pnpm test:ci`。记录 只需要几分钟。提交前请检查新卡带的个人资料 它。

`pnpm start` 运行托管连接器。它需要Wings和PostgreSQL 连接器套件README中的变量。

## 常见问题

### @useairfoil/producer-hubspot 是什么？

同步HubSpot CRM记录，自定义对象，所有者，团队，管道，列表和属性定义从一个HubSpot帐户。它回填每个资源，然后每5分钟轮询CRM记录和自定义对象，其余的每小时轮询一次。使用应用程序客户端

### 如何安装 @useairfoil/producer-hubspot？

在项目目录运行 npm install @useairfoil/producer-hubspot，或使用 pnpm add / yarn add / bun add。

### @useairfoil/producer-hubspot 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @useairfoil/producer-hubspot 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @useairfoil/producer-hubspot 可以商用吗？

@useairfoil/producer-hubspot 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @useairfoil/producer-hubspot 还在维护吗？

最新版本 0\.0\.3 发布于 2026/11/03（今天）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/10/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。