使用 HubSpot CLI 创建 CRM 应用程序

本文介绍如何使用 HubSpot CLI 创建新的应用程序。你可以在本地文件中定义应用程序配置，这些文件将打包为一个项目，并可上传至你的开发者账户以供后续集成。

前提条件

你需要一个 开发者账户 用来创建应用程序。

操作步骤

  1. 获取所需的认证信息
  2. 设置本地环境
  3. 创建并配置应用程序

获取所需的认证信息

获取应用程序创建过程中所需的全部认证凭证。
  1. 从 HubSpot 获取个人访问密钥。
    1. 登录你的 HubSpot 开发者账户。
    2. 在左侧导航栏，进入 开发 > 密钥 > 个人访问密钥，点击 生成个人访问密钥。

    3. 在 个人访问密钥 栏，复制生成的密钥并妥善保存，以供后续使用。

  2. 从 Yeastar PBX 获取回调 URL。
    1. 登录 PBX 管理网页，进入 应用对接 > CRM 集成。
    2. 点击 HubSpot。

    3. 在 网络信息 栏中，选择 主页地址，并记录下 回调 URL，以便后续在 HubSpot 中使用。
      注： 主页地址 为 PBX 的 域名，用于组成对接时使用的 回调 URL。

设置本地环境

安装所需的依赖项并与 HubSpot 进行认证，准备本地开发环境。

  1. 安装 Node.js (版本 20 或更高)。
    1. 访问 nodejs.org，下载最新的 LTS 版本并安装到本地电脑中。
    2. 在电脑中启动终端，运行以下命令验证安装。
      node --version
# 示例输出： v24.15.0
  2. 安装 HubSpot CLI。
    1. 在终端中运行以下命令进行安装。
      npm install -g @hubspot/cli

      当看到类似 changed 704 packages in 2m 的输出时，表示安装成功。

    2. 可选： 运行以下命令验证安装。
      hs --version
# 示例输出： 8.9.0
  3. 将本地环境连接至 HubSpot。
    1. 在终端中运行以下命令：
      hs account auth
      终端将提示输入个人访问密钥。
    2. 直接按任意键继续，然后根据提示粘贴 个人访问密钥。
    3. 设置一个名称，以便在 CLI 中引用此账户。

      当终端显示 SUCCESS 信息时，表示该账户已关联并设置为默认账户。

创建并配置应用程序

在本地定义应用程序的设置，包括权限和回调 URI，然后将项目上传到 HubSpot。

  1. 为你的项目创建一个本地文件夹，并在终端中打开。
    # 示例
# 在 D 盘创建一个名为 "HubSpot CLI" 的文件夹
mkdir D:\HubSpot CLI

# 进入文件夹
cd D:\HubSpot CLI
  2. 创建项目。
    1. 运行以下命令。
      hs project create
    2. 设置项目。

      • name：设置项目名称。
      • dest：指定项目的创建位置。
        注： 如要使用当前文件夹，直接按 Enter 键。
      • project-base：选择 App。
      • distribution：选择 Privately。
      • auth：选择 OAuth。
      • features：直接按 Enter 键跳过以继续创建。

      等待终端返回 SUCCESS 消息。此时项目中将添加一个 app-hsmeta.json 文件。

  3. 修改应用程序配置。
    1. 在文件资源管理器中，进入以下路径找到 app-hsmeta.json 文件。
      <你的项目文件夹>/src/app/app-hsmeta.json
    2. 使用代码编辑器打开该文件。
    3. 修改以下设置：

      • redirectUrls：粘贴从 PBX 获取的 回调 URL。
      • requiredScopes：粘贴以下权限范围。
         "requiredScopes": [
        "oauth",
        "crm.objects.contacts.read",
        "settings.users.write",
        "crm.objects.contacts.write",
        "crm.objects.companies.write",
        "settings.users.read",
        "crm.schemas.contacts.read",
        "crm.objects.companies.read",
        "crm.objects.deals.read",
        "crm.objects.deals.write",
        "crm.schemas.companies.read",
        "crm.schemas.companies.write",
        "crm.schemas.contacts.write",
        "crm.schemas.deals.read",
        "crm.schemas.deals.write",
        "crm.objects.owners.read",
        "settings.users.teams.write",
        "settings.users.teams.read"
      ]
    4. 保存变更。
  4. 将项目上传至 HubSpot。
    1. 在终端中，进入项目文件夹的根目录。
      # 示例 
cd D:\HubSpot CLI\pbx-hs-integration
    2. 运行以下命令：
      hs project upload
      终端将提示项目不存在并要求确认创建。
    3. 输入 Y 以确认创建。

      HubSpot 将创建应用程序并触发新的构建。

执行结果

应用程序已创建并上传到你的 HubSpot 账户。你可以登录 HubSpot 门户查看应用程序详情 (路径：开发 > 项目)。
注： 应用程序配置文件在本地源代码中进行管理。如需更改，需更新本地文件并运行 hs project upload 以更新到 HubSpot。

后续操作