# @bigcommerce/api-nodejs 中文文档

规范地址：https://npmcn.com/package/%40bigcommerce/api-nodejs/

版本：0\.1\.2-alpha
npm 元数据更新时间：2026-10-13T23:32:48.474Z
中文译文更新时间：2026-11-08T02:31:30.885Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bigcommerce/api-nodejs
原文对照：https://npmcn.com/package/%40bigcommerce/api-nodejs/?lang=original
项目主页：https://github.com/bigcommerce/bigcommerce-api-node#readme
源码仓库：https://github.com/bigcommerce/bigcommerce-api-node

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

- 包体积（解压后）：2.9 MB，289 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14
- 运行依赖：3 个
- 首次发布：2022-08-16T19:46:10.653Z
- 最新版本发布：2023-07-24T18:46:04.861Z
- 近 30 天下载量：2305（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

用于认证和与 BigCommerce API 通信的节点模块

## 安装

```sh
npm install @bigcommerce/api-nodejs
```

也可以使用：`pnpm add @bigcommerce/api-nodejs`、`yarn add @bigcommerce/api-nodejs`、`bun add @bigcommerce/api-nodejs`

## README

# 节点商业

用于认证和与BigCommerce API通信的节点模块.

## 安装(开发中)

1.  克隆此寄存器 : `git clone git@github.com:bigcommerce/bigcommerce-api-node.git`
2.  导航到已克隆仓库 : `cd bigcommerce-api-node`
3.  运行 [npm 链接](https://docs.npmjs.com/cli/v8/commands/npm-link)数字 : `npm link`

现在,你可以导航到其他软件包的目录(例如, [样本-应用-节点](https://github.com/bigcommerce/sample-app-nodejs)运行 `npm link bigcommerce-api-node` 这样你就可以使用和测试这个软件包,仿佛它是从国家预防机制下载的.

## 类型生成

这个 `bigcommerce-api-node` 软件包从 Open API 光谱中自动生成类型 `.yml` 为我们提供动力的文件 [公共 API 文档](https://developer.bigcommerce.com/)在为《公约》 `bigcommerce-api-node` 软件包,您可能认为有必要从光谱中重新生成类型.

为此,只需运行:

```sh
npm run generate
```

此命令将 :

1.  运行 `npm run init` 汇编 `TypeGenerator.ts` 类
2.  运行 `dist/generate/TypeGenerator.js` 生成类型
3.  运行 `npm build` 将类型构建到分布式节点.js包中

## 使用量

首先,将软件包导入您的项目 :

```js
import BigCommerce from '@bigcommerce/api-nodejs';
```

然后,创建带有与您的使用大小写相关的配置选项的 BigCommerce 对象 .

### 大商业对象

主要内容 `BigCommerce` 导入是一个包含大商业节点客户端不同用途的属性的对象。 现有属性说明如下:

-   `Auth`: 此类可以被即时处理, 用来处理商家点击时开始的 OAuth 流 **安装** 在单击应用程序上.
-   `Rest`:此类可被即时化并用于向BigCommerce Public REST API提出API请求.

## 奥奥特

这个 `bigcommerce-api-node` 软件包可用于处理商家点击时开始的 OAuth 流 **安装** 在单击应用程序上.

首先,创建大商业对象 `clientId`, (中文(简体) ), `clientSecret`,以及 `authCallback` 所需的配置选项:

```js
const bigcommerceAuth = new BigCommerce.Auth({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  authCallback: 'https://yourapplication.com/auth',
});
```

这个 `bigcommerceAuth` 上面创建的对象暴露出两种公开方法: `authorize` 财务报告和审定财务报表 `verifyJWT`。 。 。 .

这个 `authorize` 方法需要一个参数——包含字符串值的对象 `code`, (中文(简体) ), `scope`,以及 `context`,当一个商家安装您的应用程序时,这些请求由 GET 请求提供到您的商店.

```js
const payload = await bigcommerceAuth.authorize({code, scope, context});
```

存储在 `payload` 变量将包含以下密钥/值配对:

```js
{
  access_token: '123abc',
  scope: 'store_v2_orders etc.',
  user: {
    id: 12345,
    username: 'user.email@example.com',
    email: 'user.email@example.com',
  },
  context: 'stores/{STORE_HASH}',
  account_uuid: 'uuid-string'
}
```

这个 `verifyJWT` 可使用该方法核查并返还该装置返回的有效载荷 `load`, (中文(简体) ), `uninstall`,以及 `remove User` 召回电话。 每次事件都会触发从BigCommerce到您的应用程序的召回端点的请求,其中包含 `signed_payload_jwt` 作为查询参数。 一旦你解析 `signed_payload_jwt` 从请求参数,你可以把它传递到 `verifyJWT` 方法如下:

```js
const payload = bigcommerceAuth.verifyJWT(signed_payload_jwt);
```

存储在 `payload` 变量将包含以下密钥/值配对:

```js
{
  aud: 'YOUR_CLIENT_ID',
  iss: 'bc',
  iat: 1646844813,
  nbf: 1646844808,
  exp: 1646931213,
  jti: 'uuid-value',
  sub: 'stores/{STORE_HASH}',
  user: { id: 1470672, email: 'user.email@example.com' },
  owner: { id: 1470672, email: 'owner.email@example.com' },
  url: '/'
}
```

## 资源

这个 `bigcommerce-api-node` 软件包可用于与 BigCommerce 公共 REST API 通信.

```js
const bigcommerceRest = new BigCommerce.Rest({
  storeHash: 'yourStoreHash',
  accessToken: 'yourStoreAccessToken',
})

// bigcommerceRest.<resource_name>.<method_name>
```

每种方法返回 a `Promise` 解决包含资源数据的响应.

```js
bigcommerceRest.v2.orders
  .list({ limit: 5 })
  .then(orders => console.log(orders))
  .catch(err => console.error(err));
```

一些资源包括: `listAll()` 返回一个方法 [显示器](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#iterators) 允许您循环所有可用的资源, 并处理 pagination .

```js
for await (const order of bigcommerceRest.v2.orders.listAll()) {
  console.log(order);
}
```

## 限制费率管理

这个 `RestClient` class 提供了与 BigCommerce API 限速器相关的状态信息。 现有资料包括:

-   `msToReset`: 时间( 毫秒) 至限制窗口重排速度
-   `nextWindowTime`数字 : `Date` 对象,用于开始下一个限制速度窗口
-   `windowSize`: 当前速度限制窗口的总大小
-   `requestsRemaining`: 在执行费率限制之前,保留在目前窗口中的请求数量
-   `requestsQuota`: 每个窗口允许的请求总数

每次提出要求都会更新这些资料。 它可以通过 `rateLimitManager` 用于避免收到 `429` 从服务器出错 .

```js
bigcommerceRest.rateLimitManager.status  // <-- { msToReset, windowSize, requestsRemaining, requestsQuota }
```

`RestClient` 可选择配置以延迟请求,直到满足最低请求阈值的下个速率限制窗口.

```js
  const bigcommerceRest = new BigCommerce.Rest({
    storeHash: STORE_HASH,
    accessToken: ACCESS_TOKEN,
    rateLimitConfig: {
      enableWait: true,
      minRequestsRemaining: 10,
    },
```

此外,在满足请求阈值时,还可以提供自定义的回调对象.

```js
  const limitCallback = params => console.log(params.message);

  const bigcommerceRest = new BigCommerce.Rest({
    storeHash: STORE_HASH,
    accessToken: ACCESS_TOKEN,
    rateLimitConfig: {
      enableWait: false,
      minRequestsRemaining: 10,
      callbackParams: { message: 'request threshold reached' },
      callback: limitCallback  // <-- function called with callbackParams when minRequestsRemaining threashold is met
    },
```

### 现有资源和方法

-   页:1
    -   v2. 顺序
        -   `get(orderId)`: 获得命令
        -   `update(orderId, data)`: 更新顺序
        -   `archive(orderId)`: 存档命令
        -   `count()`: 获得命令数
        -   `list([params])`: 获取所有命令
        -   `listAll([params])`: 获取所有命令( 已插入)
        -   `create(data)`: 创建顺序
        -   `archiveAll()`: 归档所有命令
    -   v2. 命令. 命令库
        -   `list(orderId[, params])`: 列表顺序
        -   `listAll(orderId[, params])`: 列表顺序套接字(已插入)
    -   生产
        -   `list(orderId[, params])`: 列表顺序产品
        -   `listAll(orderId[, params])`: 列表顺序产品(已加入)
        -   `get(orderId, productId)`: 获取顺序产品
    -   v2. 命令. 命令税
        -   `list(orderId[, params])`: 获得所有顺序税
        -   `listAll(orderId[, params])`: 获取所有顺序税( 已插入)
    -   v2. 命令. 命令状态
        -   `list()`: 获取全部顺序状态
        -   `get(statusId)`: 获得单一顺序状态
    -   v2. 订单
        -   `list(orderId[, params])`: 获得发货订单
        -   `listAll(orderId[, params])`: 订购装运(装入)
        -   `create(orderId, data)`: 创建发货顺序
        -   `deleteAll(orderId)`: 删除所有发货顺序
        -   `count(orderId)`获得订单运输数
        -   `get(orderId, shipmentId)`: 获得货物
        -   `update(orderId, shipmentId, data)`: 更新货运
        -   `delete(orderId, shipmentId)`: 删除命令
    -   v2. 命令. 命令
        -   `list(orderId[, params])`: 获取订单航运地址
        -   `listAll(orderId[, params])`: 获取订单发运地址( 已插入)
        -   `get(orderId, addressId)`: 获取航运地址
        -   `update(orderId, addressId, data)`: 更新航运地址
    -   v2. 顺序. 命令
        -   `list(orderId[, params])`: 获取命令信件
        -   `listAll(orderId[, params])`: 获取顺序信件( 已插入)
    -   v2. 命令. 命令跳动引号
        -   `list(orderId, addressId)`: 获得订单航运

## 常见问题

### @bigcommerce/api-nodejs 是什么？

用于认证和与 BigCommerce API 通信的节点模块

### 如何安装 @bigcommerce/api-nodejs？

在项目目录运行 npm install @bigcommerce/api-nodejs，或使用 pnpm add / yarn add / bun add。

### @bigcommerce/api-nodejs 支持 TypeScript 吗？

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

### @bigcommerce/api-nodejs 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bigcommerce/api-nodejs 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bigcommerce/api-nodejs 可以商用吗？

@bigcommerce/api-nodejs 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bigcommerce/api-nodejs 的下载量有多少？

根据 npm 官方下载统计，@bigcommerce/api-nodejs 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,305 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bigcommerce/api-nodejs 还在维护吗？

最新版本 0\.1\.2-alpha 发布于 2023/07/25（3 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/08/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。